> ## Documentation Index
> Fetch the complete documentation index at: https://developer.uphold.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Update proof-of-address
> Update the proof-of-address process for a user.
export const RestEndpointSubjects = ({subjects = []}) => {
const subjectToIconMap = {
'client': 'browser',
'user:individual': 'user',
'user:business': 'briefcase'
};
if (subjects.length === 0) {
return null;
}
return <>
{subjects.map(subject =>
{subject}
)}
;
};
**Update proof-of-address** is the endpoint through which the user proves their declared address of residence.
## Via document submission
If electronic verification is not possible, the user must provide a document to prove their address, usually by providing a utility bill or bank statement.
The document is provided as a media file, passed in `input.media`. At this time, only a single media file is supported for this process.
A document that proves the user's address of residence.
File Category: `document` (which allows pdf files as well as typical images content-types)
Files are created and uploaded using the [Create File](../files/create-file) endpoint.
## Via electronic verification
Some KYC providers allow for address verification through electronic means, without requiring providing any documents.
They usually do this by checking the user's declared address of residence against public and third-party records, such as government, credit, banking, and utility records.
## Verification rejection reasons
When the process completes with `status: failed`, `output.reason` indicates why the verification was rejected:
* `address-mismatch`: the submitted document does not match the declared address.
* `name-mismatch`: the name on the submitted document does not match the user's profile.
* `provider-verification-rejected`: the upstream provider rejected the submission. When present, `output.providerDetails.reasons[]` carries provider-specific codes that can be surfaced to the user.
## OpenAPI
````yaml _media/specs/core-openapi.mintlify.json patch /core/kyc/processes/proof-of-address
openapi: 3.1.0
info:
version: 0.1.0
title: Core API
description: >-
The Core API provides essential building blocks that empower businesses to
embed financial services into their applications.
contact:
name: Uphold API Team
email: developers@uphold.com
url: https://developer.uphold.com
servers:
- url: https://api.enterprise.sandbox.uphold.com
description: Sandbox
- url: https://api.enterprise.uphold.com
description: Production
security:
- OAuth2: []
tags:
- name: Authentication
description: Authentication.
- name: Countries
description: Countries.
- name: Users
description: Users.
- name: KYC
description: Individual User's KYC.
- name: KYB
description: Business User's KYB.
- name: Capabilities
description: User capabilities.
- name: Terms of service
description: User terms of service.
- name: Files
description: Files.
- name: Assets
description: Assets, networks and rails.
- name: Accounts
description: Accounts.
- name: External accounts
description: External accounts.
- name: Transactions
description: Transactions.
- name: Portfolio
description: Portfolio.
- name: Statements
description: Statements.
- name: Metadata
description: Metadata.
- name: Webhooks
description: Webhooks.
paths:
/core/kyc/processes/proof-of-address:
patch:
tags:
- KYC
summary: Update proof-of-address
description: Update the proof-of-address process for a user.
operationId: core.update-kyc-proof-of-address
requestBody:
$ref: '#/components/requestBodies/update-kyc-proof-of-address-request-body'
responses:
'200':
$ref: '#/components/responses/update-kyc-proof-of-address-response'
'404':
$ref: >-
#/components/responses/update-kyc-proof-of-address-not-found-response
'409':
$ref: '#/components/responses/update-kyc-proof-of-address-conflict-response'
security:
- OAuth2:
- core.kyc.proof-of-address:update
components:
requestBodies:
update-kyc-proof-of-address-request-body:
content:
application/json:
schema:
type: object
discriminator:
propertyName: type
mapping:
electronic-verification:
$ref: >-
#/components/schemas/update-kyc-proof-of-address-electronic-verification
document-submission:
$ref: >-
#/components/schemas/update-kyc-proof-of-address-document-submission
oneOf:
- $ref: >-
#/components/schemas/update-kyc-proof-of-address-document-submission
title: Document submission
- $ref: >-
#/components/schemas/update-kyc-proof-of-address-electronic-verification
title: Electronic verification
required:
- type
examples:
Update Process via Document Submission - Partner-verified:
value:
type: document-submission
input:
media:
- context: address-proof
fileId: 459c0447-8916-4bad-bb67-f2354fcfb10b
output:
provider: sumsub
person:
givenName: John
familyName: Doe
address:
country: GB
subdivision: GB-MAN
city: Manchester
line1: 1 High Street
line2: Northern Quarter
postalCode: M4 1AA
verifiedAt: '2020-01-01T00:00:00.000Z'
Update Process via Electronic Verification - Partner-verified:
value:
type: electronic-verification
input:
data:
givenName: John
familyName: Doe
address:
country: GB
subdivision: GB-MAN
city: Manchester
line1: 1 High Street
line2: Northern Quarter
postalCode: M4 1AA
output:
provider: sumsub
verifiedAt: '2020-01-01T00:00:00.000Z'
responses:
update-kyc-proof-of-address-response:
description: KYC proof-of-address process updated.
content:
application/json:
schema:
type: object
properties:
proofOfAddress:
$ref: '#/components/schemas/kyc-proof-of-address'
required:
- proofOfAddress
examples:
Process Updated via Document Submission - Partner-verified:
value:
proofOfAddress:
code: proof-of-address
status: ok
type: document-submission
verification:
model: partner-verified
method: manual
dependencies:
- phone
- profile
- address
submittable: false
input:
media:
- context: address-proof
fileId: 459c0447-8916-4bad-bb67-f2354fcfb10b
output:
provider: sumsub
person:
givenName: John
familyName: Doe
address:
country: GB
subdivision: GB-MAN
city: Manchester
line1: 1 High Street
line2: Northern Quarter
postalCode: M4 1AA
verifiedAt: '2020-01-01T00:00:00.000Z'
Process Updated via Electronic Verification - Partner-verified:
value:
proofOfAddress:
code: proof-of-address
status: ok
type: electronic-verification
verification:
model: partner-verified
method: automatic
triggers:
- identity
dependencies:
- phone
- profile
- address
submittable: false
input:
data:
givenName: John
familyName: Doe
address:
country: GB
subdivision: GB-MAN
city: Manchester
line1: 1 High Street
line2: Northern Quarter
postalCode: M4 1AA
output:
provider: sumsub
verifiedAt: '2020-01-01T00:00:00.000Z'
Process Updated from Identity:
value:
proofOfAddress:
code: proof-of-address
status: ok
type: from-identity
verification:
model: partner-verified
method: automatic
dependencies:
- phone
- profile
- address
submittable: false
output:
provider: veriff
person:
givenName: John
familyName: Doe
address:
country: GB
subdivision: GB-MAN
city: Manchester
line1: 1 High Street
line2: Northern Quarter
postalCode: M4 1AA
verifiedAt: '2020-01-01T00:00:00.000Z'
headers:
x-uphold-request-id:
description: >-
A unique identifier for the request that can be shared with Uphold
for troubleshooting purposes.
required: true
schema:
type: string
format: uuid
examples:
Request ID:
value: 9092ee4d-f0fb-42e9-8787-b668dbcec531
update-kyc-proof-of-address-not-found-response:
description: Resource not found.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
examples:
File Not Found:
value:
code: entity_not_found
message: A file specified in the media array cannot be found
details:
entity: file
headers:
x-uphold-request-id:
description: >-
A unique identifier for the request that can be shared with Uphold
for troubleshooting purposes.
required: true
schema:
type: string
format: uuid
examples:
Request ID:
value: 9092ee4d-f0fb-42e9-8787-b668dbcec531
update-kyc-proof-of-address-conflict-response:
description: Business logic error.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
examples:
Given Name Contains Invalid Characters:
value:
code: invalid_characters
message: The request has invalid characters
details:
context: body
property: output.person.givenName
Family Name Contains Invalid Characters:
value:
code: invalid_characters
message: The request has invalid characters
details:
context: body
property: output.person.familyName
Address Country Not Supported:
value:
code: country_not_supported
message: The country is not supported
details:
context: body
property: output.person.address.country
Address Subdivision Not Supported:
value:
code: subdivision_not_supported
message: The subdivision is not supported
details:
context: body
property: output.person.address.subdivision
File Invalid:
value:
code: file_invalid
message: A file specified in the media array has not been uploaded
Verified Date Invalid:
value:
code: date_invalid
message: The date must be in the past
details:
rule: difference-greater-than-threshold
threshold:
limit: 0
unit: milliseconds
context: body
property: output.verifiedAt
Missing Declared Information:
value:
code: operation_not_allowed
message: >-
User cannot submit proof-of-address due to incomplete declared
information
details:
reasons:
- missing-name
- incomplete-address
Process Updates Not Allowed:
value:
code: operation_not_allowed
message: The current status of the process does not allow updates
details:
reasons:
- kyc-process-update-not-allowed
Uphold-Verified Updates Not Allowed:
value:
code: operation_not_allowed
message: Uphold-verified 'proof-of-address' updates are not allowed
details:
reasons:
- permission-denied
headers:
x-uphold-request-id:
description: >-
A unique identifier for the request that can be shared with Uphold
for troubleshooting purposes.
required: true
schema:
type: string
format: uuid
examples:
Request ID:
value: 9092ee4d-f0fb-42e9-8787-b668dbcec531
schemas:
update-kyc-proof-of-address-electronic-verification:
type: object
properties:
type:
description: The proof-of-address submission type.
type: string
enum:
- electronic-verification
input:
description: Input of the KYC process.
type: object
properties:
data:
description: The declared data used to verify the process.
type: object
properties:
givenName:
allOf:
- $ref: '#/components/schemas/string-no-edge-spaces'
- description: The given name.
type: string
maxLength: 200
familyName:
allOf:
- $ref: '#/components/schemas/string-no-edge-spaces'
- description: The family name or surname.
type: string
maxLength: 200
address:
allOf:
- $ref: '#/components/schemas/address-for-request'
- type: object
required:
- country
required:
- givenName
- address
required:
- data
output:
description: Output of the KYC process.
type: object
properties:
provider:
allOf:
- $ref: '#/components/schemas/string-no-edge-spaces'
- description: The provider used to verify the KYC process.
type: string
maxLength: 100
verifiedAt:
description: The date and time of the verification.
type: string
format: date-time
required:
- provider
- verifiedAt
required:
- type
- input
update-kyc-proof-of-address-document-submission:
type: object
properties:
type:
description: The proof-of-address submission type.
type: string
enum:
- document-submission
input:
description: Input of the KYC process.
type: object
properties:
media:
type: array
minItems: 1
maxItems: 5
items:
type: object
properties:
context:
description: The context of the file.
type: string
enum:
- address-proof
fileId:
description: The id of the file.
type: string
format: uuid
required:
- context
- fileId
required:
- media
output:
description: Output of the KYC process.
type: object
properties:
provider:
allOf:
- $ref: '#/components/schemas/string-no-edge-spaces'
- description: The provider used to verify the KYC process.
type: string
maxLength: 100
person:
description: The person information.
type: object
properties:
givenName:
allOf:
- $ref: '#/components/schemas/string-no-edge-spaces'
- description: The person's given name.
type: string
maxLength: 200
familyName:
allOf:
- $ref: '#/components/schemas/string-no-edge-spaces'
- description: The person's family name or surname.
type: string
maxLength: 200
address:
allOf:
- $ref: '#/components/schemas/address-for-request'
- type: object
required:
- country
required:
- givenName
- address
verifiedAt:
description: The date and time of the verification.
type: string
format: date-time
required:
- provider
- person
- verifiedAt
required:
- type
- input
kyc-proof-of-address:
discriminator:
propertyName: type
mapping:
none:
$ref: '#/components/schemas/kyc-proof-of-address-none'
document-submission:
$ref: '#/components/schemas/kyc-proof-of-address-document-submission'
electronic-verification:
$ref: '#/components/schemas/kyc-proof-of-address-electronic-verification'
from-identity:
$ref: '#/components/schemas/kyc-proof-of-address-from-identity'
oneOf:
- $ref: '#/components/schemas/kyc-proof-of-address-none'
title: None
- $ref: '#/components/schemas/kyc-proof-of-address-document-submission'
title: Document submission
- $ref: '#/components/schemas/kyc-proof-of-address-electronic-verification'
title: Electronic verification
- $ref: '#/components/schemas/kyc-proof-of-address-from-identity'
title: From identity
error:
description: The error information.
type: object
properties:
code:
description: >-
A short string with a brief explanation about the error code
reported.
type: string
message:
description: A human-readable message providing more details about the error.
type: string
details:
description: Additional information about the error reported.
type: object
additionalProperties: true
required:
- code
- message
string-no-edge-spaces:
type: string
pattern: ^\S.*\S$|^\S$
address-for-request:
description: The address information.
type: object
properties:
country:
allOf:
- $ref: '#/components/schemas/country-code-for-request'
- description: The country of the address.
subdivision:
allOf:
- $ref: '#/components/schemas/subdivision-code-for-request'
- description: The subdivision of the address.
city:
allOf:
- $ref: '#/components/schemas/string-no-edge-spaces'
- description: The city of the address.
type: string
maxLength: 100
line1:
allOf:
- $ref: '#/components/schemas/string-no-edge-spaces'
- description: The first line of the address.
type: string
maxLength: 150
line2:
allOf:
- $ref: '#/components/schemas/string-no-edge-spaces'
- description: The second line of the address.
type: string
maxLength: 100
postalCode:
allOf:
- $ref: '#/components/schemas/string-no-edge-spaces'
- description: The postal code of the address.
type: string
maxLength: 20
kyc-proof-of-address-none:
title: None
type: object
properties:
code:
description: The code of the KYC process.
type: string
status:
$ref: '#/components/schemas/kyc-process-status'
type:
description: The proof-of-address submission type.
type: string
enum:
- none
verification:
allOf:
- $ref: '#/components/schemas/kyc-process-verification'
- type: object
properties:
submittable:
description: Whether this process currently accepts a new submission.
type: boolean
required:
- submittable
required:
- code
- status
kyc-proof-of-address-document-submission:
title: Document Submission
type: object
properties:
code:
description: The code of the KYC process.
type: string
status:
$ref: '#/components/schemas/kyc-process-status'
type:
description: The proof-of-address submission type.
type: string
enum:
- document-submission
verification:
allOf:
- $ref: '#/components/schemas/kyc-process-verification'
- type: object
properties:
submittable:
description: Whether this process currently accepts a new submission.
type: boolean
required:
- submittable
input:
description: Input of the KYC process.
type: object
properties:
media:
description: The media that was collected during the process.
type: array
items:
type: object
properties:
context:
description: The context of the file.
type: string
enum:
- address-proof
fileId:
description: The id of the file.
type: string
format: uuid
required:
- context
- fileId
required:
- media
output:
description: Output of the KYC process.
type: object
properties:
provider:
description: The provider used to verify the KYC process.
type: string
providerDetails:
description: The provider details associated with the verification.
type: object
properties:
reasons:
description: The reasons associated with the verification.
type: array
items:
type: string
reason:
description: The reason associated with the verification.
type: string
enum:
- address-mismatch
- name-mismatch
- provider-verification-rejected
person:
description: The person information.
type: object
properties:
givenName:
description: The person's given name.
type: string
familyName:
description: The person's family name or surname.
type: string
address:
allOf:
- $ref: '#/components/schemas/address'
- type: object
verifiedAt:
description: The date and time of the verification.
type: string
format: date-time
required:
- provider
- verifiedAt
required:
- code
- status
- type
kyc-proof-of-address-electronic-verification:
title: Electronic Verification
type: object
properties:
code:
description: The code of the KYC process.
type: string
status:
$ref: '#/components/schemas/kyc-process-status'
type:
description: The proof-of-address submission type.
type: string
enum:
- electronic-verification
verification:
allOf:
- $ref: '#/components/schemas/kyc-process-verification'
- type: object
properties:
submittable:
description: Whether this process currently accepts a new submission.
type: boolean
required:
- submittable
input:
description: Input of the KYC process.
type: object
properties:
data:
description: The declared data used to verify the process.
type: object
properties:
givenName:
description: The given name.
type: string
familyName:
description: The family name or surname.
type: string
address:
allOf:
- $ref: '#/components/schemas/address'
- type: object
required:
- country
required:
- givenName
- address
required:
- data
output:
description: Output of the KYC process.
type: object
properties:
provider:
description: The provider used to verify the KYC process.
type: string
reason:
description: The reason associated with the verification.
type: string
enum:
- address-mismatch
- name-mismatch
verifiedAt:
description: The date and time of the verification.
type: string
format: date-time
required:
- provider
- verifiedAt
required:
- code
- status
- type
kyc-proof-of-address-from-identity:
title: From Identity
type: object
properties:
code:
description: The code of the KYC process.
type: string
status:
$ref: '#/components/schemas/kyc-process-status'
type:
description: The proof-of-address submission type.
type: string
enum:
- from-identity
verification:
allOf:
- $ref: '#/components/schemas/kyc-process-verification'
- type: object
properties:
submittable:
description: Whether this process currently accepts a new submission.
type: boolean
required:
- submittable
output:
description: Output of the KYC process.
type: object
properties:
provider:
description: The provider used to verify the KYC process.
type: string
reason:
description: The reason associated with the verification.
type: string
enum:
- address-mismatch
- name-mismatch
person:
description: The person information.
type: object
properties:
givenName:
description: The person's given name.
type: string
familyName:
description: The person's family name or surname.
type: string
address:
allOf:
- $ref: '#/components/schemas/address'
- type: object
verifiedAt:
description: The date and time of the verification.
type: string
format: date-time
required:
- provider
- verifiedAt
required:
- code
- status
- type
country-code-for-request:
type: string
pattern: ^[A-Z]{2}$
subdivision-code-for-request:
type: string
pattern: ^[A-Z]{2}-[A-Z0-9]{1,3}$
kyc-process-status:
description: Status of the KYC process.
type: string
enum:
- ok
- failed
- running
- pending
- exempt
kyc-process-verification:
description: Configuration of this process.
type: object
properties:
model:
description: The verification model to complete this process.
type: string
enum:
- partner-verified
- uphold-verified
method:
description: >-
Whether this process is verified automatically in the background or
requires user action.
type: string
enum:
- automatic
- manual
triggers:
description: >-
Other processes that, once updated, trigger this process to run
automatically. Only present when `method` is `automatic`.
type: array
items:
type: string
enum:
- profile
- identity
dependencies:
$ref: '#/components/schemas/kyc-process-dependencies'
required:
- model
- method
- dependencies
address:
description: The address information.
type: object
properties:
country:
description: The country of the address.
type: string
subdivision:
description: The subdivision of the address.
type: string
city:
description: The city of the address.
type: string
line1:
description: The first line of the address.
type: string
line2:
description: The second line of the address.
type: string
postalCode:
description: The postal code of the address.
type: string
kyc-process-dependencies:
description: The processes that must be updated before you can update this one.
type: array
items:
type: string
enum:
- profile
- address
- email
- phone
- identity
- proof-of-address
- customer-due-diligence
- enhanced-due-diligence
- crypto-risk-assessment
- self-categorization-statement
- tax-details
securitySchemes:
OAuth2:
type: oauth2
description: OAuth 2.0 authentication.
flows:
clientCredentials:
tokenUrl: /core/oauth2/token
scopes:
core.users:act-on-behalf-of: Grants access to act on behalf of a user
core.users:create: Grants access to create users
core.users:read: Grants access to view users
core.users:delete: Grants access to delete users
core.users.metadata:read: Grants access to view user metadata
core.users.metadata:write: Grants access to modify user metadata
core.kyc:read: Grants access to view KYC processes
core.kyc.profile:update: Grants access to update profile KYC process
core.kyc.address:update: Grants access to update address KYC process
core.kyc.email:update: Grants access to update email KYC process
core.kyc.phone:update: Grants access to update phone KYC process
core.kyc.identity:update: Grants access to update identity KYC process
core.kyc.proof-of-address:update: Grants access to update proof-of-address KYC process
core.kyc.customer-due-diligence:update: Grants access to update customer due diligence KYC process
core.kyc.enhanced-due-diligence:update: Grants access to update enhanced due diligence KYC process
core.kyc.crypto-risk-assessment:update: Grants access to update crypto risk assessment KYC process
core.kyc.self-categorization-statement:update: Grants access to update self-categorization statement KYC process
core.kyc.tax-details:update: Grants access to update tax details KYC process
core.capabilities:read: Grants access to view user capabilities
core.terms-of-service:read: Grants access to view terms of service
core.terms-of-service:accept: Grants access to accept terms of service
core.files:create: Grants access to create files
core.files:read: Grants access to view files
core.files.metadata:read: Grants access to view files metadata
core.files.metadata:write: Grants access to modify files metadata
core.accounts:create: Grants access to create accounts
core.accounts:read: Grants access to view accounts
core.accounts:update: Grants access to update accounts
core.accounts:archive: Grants access to archive accounts
core.accounts:deposit-method: >-
Grants access to deposit method needed for depositing into
accounts
core.accounts:use-test-helpers: Grants access to test helpers of accounts
core.accounts.metadata:read: Grants access to view accounts metadata
core.accounts.metadata:write: Grants access to modify accounts metadata
core.assets:use-test-helpers: Grants access to test helpers of assets
core.external-accounts:create: Grants access to create external accounts
core.external-accounts:read: Grants access to view external accounts
core.external-accounts:update: Grants access to update external accounts
core.external-accounts:delete: Grants access to delete external accounts
core.external-accounts.metadata:read: Grants access to view external accounts metadata
core.external-accounts.metadata:write: Grants access to modify external accounts metadata
core.transactions:create: Grants access to commit quotes
core.transactions:read: Grants access to view transactions
core.transactions.metadata:read: Grants access to view transactions metadata
core.transactions.metadata:write: Grants access to modify transactions metadata
core.transactions.requests-for-information:read: Grants access to view transactions requests for information
core.transactions.requests-for-information:update: Grants access to update transactions requests for information
core.portfolio:read: >-
Grants access to view portfolio overview, performance, and
historical balance
core.statements:read: Grants access to read statements
core.webhooks:management-link: Grants access to create webhook management links
````