> ## 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 tax details
> Update the tax details 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 tax details** is the endpoint used to collect and submit tax information required by applicable regulatory frameworks. This includes tax residency details, taxpayer identification numbers, and certification of the accuracy of the provided information.
Requirements vary by region — for example, US citizens must provide information for submitting [IRS Form W-9](https://www.irs.gov/pub/irs-pdf/fw9.pdf), while EU residents must declare their countries of tax residence and relevant tax identification numbers.
When calling [`GET /core/kyc?detailed=taxDetails`](./get-overview), you will get a `hint` property which includes a [dynamic form](/developer-guides/resources/dynamic-forms/introduction) schema and UI schema.
The `hint` property will also be available in responses of this endpoint, in case there are still questions to be answered.
For more information about forms, refer to the [form-based processes](./introduction#form-based-processes) section.
## OpenAPI
````yaml _media/specs/core-openapi.mintlify.json patch /core/kyc/processes/tax-details
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/tax-details:
patch:
tags:
- KYC
summary: Update tax details
description: Update the tax details process for a user.
operationId: core.update-kyc-tax-details
parameters:
- $ref: '#/components/parameters/accept-language'
requestBody:
$ref: '#/components/requestBodies/update-kyc-tax-details-request-body'
responses:
'200':
$ref: '#/components/responses/update-kyc-tax-details-response'
'409':
$ref: '#/components/responses/update-kyc-tax-details-conflict-response'
security:
- OAuth2:
- core.kyc.tax-details:update
components:
parameters:
accept-language:
name: Accept-Language
description: The natural language and locale that the client prefers.
in: header
schema:
type: string
examples:
English (UK):
value: en-GB
requestBodies:
update-kyc-tax-details-request-body:
content:
application/json:
schema:
title: Dynamic Form
description: >-
Dynamic form input following the [JSON
Forms](https://jsonforms.io/) specification, enabling progressive
disclosure of properties and anytime submissions to keep tax
details up to date.
type: object
properties:
input:
type: object
additionalProperties: true
minProperties: 1
maxProperties: 1
output:
$ref: >-
#/components/schemas/update-kyc-tax-details-request-body-output
required:
- input
examples:
Update Process - Uphold-verified:
value:
input:
taxResidency:
countries:
- GB
responses:
update-kyc-tax-details-response:
description: KYC tax details process updated.
content:
application/json:
schema:
type: object
properties:
taxDetails:
$ref: '#/components/schemas/kyc-tax-details'
required:
- taxDetails
examples:
Process Updated - Uphold-verified:
value:
taxDetails:
code: tax-details
status: pending
verification:
model: uphold-verified
method: manual
dependencies:
- profile
input:
taxResidency:
countries:
- GB
taxIdentification:
documents:
- type: tin
country: GB
hint:
type: form
schema:
type: object
additionalProperties: false
properties:
taxResidency:
title: Tax Residency Declaration
type: object
additionalProperties: false
properties:
countries:
title: In which countries are you a tax resident?
type: array
uniqueItems: true
minItems: 1
items:
type: string
pattern: ^[A-Z]{2}$
required:
- countries
taxIdentification:
title: Tax Identification and Certification
type: object
additionalProperties: false
properties:
documents:
title: Tax Identification Documents
type: array
uniqueItems: true
items:
type: object
properties:
country:
title: Country
type: string
type:
title: Document type
type: string
number:
title: Document number
type: string
pattern: ^\S.*\S$|^\S$
maxLength: 15
reason:
title: >-
If you don't have a TIN, please select a
reason
type: string
oneOf:
- const: country-does-not-issue-document
title: >-
My country does not issue TINs or
equivalent to its residents.
- const: user-unable-to-obtain-document
title: I am unable to obtain a TIN.
- const: law-does-not-require-document
title: >-
The local law does not require me to
have a TIN.
justification:
title: I am unable to obtain a TIN because
type: string
pattern: ^\S.*\S$|^\S$
maxLength: 1000
required:
- country
- type
allOf:
- oneOf:
- type: object
properties:
country:
const: GB
type:
const: tin
required:
- type
- country
- if:
type: object
properties:
reason:
const: user-unable-to-obtain-document
required:
- reason
then:
type: object
properties:
justification: true
required:
- justification
- oneOf:
- type: object
properties:
number: true
required:
- number
- type: object
properties:
reason: true
required:
- reason
allOf:
- contains:
type: object
properties:
type:
const: tin
country:
const: GB
required:
- type
- country
minContains: 1
maxContains: 1
certify:
title: >-
I confirm that the information provided is
accurate.
type: boolean
const: true
required:
- documents
- certify
uiSchema:
type: Categorization
elements:
- label: Tax Residency Declaration
type: Category
elements:
- label: In which countries are you a tax resident?
type: Control
scope: '#/properties/taxResidency/properties/countries'
options:
data:
source: countries
exclude:
restrictions:
- scope: citizenship
- label: Tax Identification and Certification
type: Category
elements:
- label: Tax Identification Documents
type: ListWithDetail
scope: >-
#/properties/taxIdentification/properties/documents
options:
elementLabelProp: country
disableAdd: true
disableRemove: true
showSortButtons: false
detail:
type: ListWithDetail
elements:
- type: Group
elements:
- label: Document type
type: Control
scope: '#/properties/type'
options:
readonly: true
- label: Country
type: Control
scope: '#/properties/country'
options:
readonly: true
- label: Document number
type: Control
scope: '#/properties/number'
- label: >-
If you don't have a TIN, please select a
reason
type: Control
scope: '#/properties/reason'
- label: I am unable to obtain a TIN because
type: Control
scope: '#/properties/justification'
- label: >-
I confirm that the information provided is
accurate.
type: Control
scope: >-
#/properties/taxIdentification/properties/certify
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-tax-details-conflict-response:
description: Business logic error.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
examples:
Address Country Not Supported:
value:
code: country_not_supported
message: The country is not supported
details:
context: body
property: input.taxResidency.address.country
Address Subdivision Not Supported:
value:
code: subdivision_not_supported
message: The subdivision is not supported
details:
context: body
property: input.taxResidency.address.subdivision
Address Postal Code Invalid:
value:
code: postal_code_invalid
message: The postal code is invalid
details:
context: body
property: input.taxResidency.address.postalCode
Countries Country Not Supported:
value:
code: country_not_supported
message: The country is not supported
details:
context: body
property: input.taxResidency.countries[0]
Document Number Invalid:
value:
code: document_number_invalid
message: The provided document number is invalid
details:
context: body
property: input.taxIdentification.documents[0].number
Document Reason Not Supported:
value:
code: document_reason_not_supported
message: The provided document reason is not supported
details:
context: body
property: input.taxIdentification.documents[0].reason
Certification Signature Mismatch:
value:
code: certification_signature_mismatch
message: The signature does not match the user's full name
details:
context: body
property: input.taxIdentification.signature
Incomplete Declared Information:
value:
code: operation_not_allowed
message: >-
User cannot submit tax details due to incomplete declared
information
details:
reasons:
- incomplete-profile
- incomplete-address
Process Updates Not Allowed:
value:
code: operation_not_allowed
message: The process is not required for this user
details:
reasons:
- kyc-process-status-exempt
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-tax-details-request-body-output:
description: Output of the KYC process.
type: object
properties:
result:
description: The result of the verification.
type: string
enum:
- approved
- rejected
verifiedAt:
description: The date and time of the verification.
type: string
format: date-time
required:
- result
- verifiedAt
kyc-tax-details:
type: object
properties:
code:
description: The code of the KYC process.
type: string
status:
$ref: '#/components/schemas/kyc-process-status'
verification:
$ref: '#/components/schemas/kyc-process-verification'
input:
description: The declared tax details.
type: object
additionalProperties: true
minProperties: 1
output:
description: Output of the KYC process.
type: object
properties:
result:
description: The result of the verification.
type: string
enum:
- approved
- rejected
verifiedAt:
description: The date and time of the verification.
type: string
format: date-time
required:
- result
- verifiedAt
hint:
$ref: '#/components/schemas/kyc-process-hint-form'
required:
- code
- status
error:
description: The error information.
allOf:
- $ref: '#/components/schemas/feedback'
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:
- none
- 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
kyc-process-hint-form:
description: Hints for the KYC process.
type: object
properties:
type:
description: The type of the hint.
type: string
enum:
- form
formId:
description: The id of the form.
type: string
format: uuid
schema:
description: >-
The definition of the structure and validation rules for this KYC
process form.
It follows the [JSON Schema](https://json-schema.org/) specification
with the power of [JSON Forms](https://jsonforms.io/).
The schema is iterative, meaning that new questions and properties
can be added dynamically as the KYC process evolves. This allows for
a flexible and adaptive form structure that can accommodate changes
and new requirements over time.
type: object
additionalProperties: true
uiSchema:
description: >-
The `uiSchema` property defines the general layout and presentation
of the form by means of different UI schema elements.
It follows the [JSON Forms](https://jsonforms.io/) specification and
is used to customize the appearance and behavior of the form fields.
The `uiSchema` includes the following elements:
- `Layouts`: Used to structure the form layout. It includes
properties like `type` to define the layout type (e.g.,
`Categorization`) and `elements` to define the child elements.
- `Controls`: Used to define the form controls. It includes
properties like `scope` to point to the corresponding schema
property and `label` to define the control's label.
- `Rules`: Used to define conditional visibility rules for form
controls. It includes properties like `effect` to define the rule
effect (e.g., `SHOW`) and `condition` to define the rule condition.
The `uiSchema` is iterative, meaning that new controls and layout
elements can be added dynamically as the KYC process evolves. This
allows for a flexible and dynamic form layout, enhancing the user
experience by providing a structured and intuitive form design that
can adapt to new requirements and changes over time.
type: object
additionalProperties: true
required:
- type
- schema
- uiSchema
feedback:
description: A feedback message with a code and human-readable description.
type: object
properties:
code:
description: A short string with a brief explanation about the code reported.
type: string
message:
description: A human-readable message providing more details.
type: string
details:
description: Additional information about the feedback reported.
type: object
additionalProperties: true
required:
- code
- message
kyc-process-dependencies:
description: The processes that must be updated before you can update this one.
type: array
items:
type: string
enum:
- profile
- 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
````