Core API
- Concepts
- Introduction
- GETGet overview
- PATCHUpdate email
- PATCHUpdate phone
- PATCHUpdate profile
- PATCHUpdate address
- PATCHUpdate identity
- PATCHUpdate proof of address
- PATCHUpdate customer due diligence
- PATCHUpdate enhanced due diligence
- PATCHUpdate crypto risk assessment
- PATCHUpdate self-categorization statement
- PATCHUpdate tax details
Topper API
Widgets API
Copy
Ask AI
curl --request PATCH \
--url https://api.enterprise.sandbox.uphold.com/core/kyc/processes/tax-details \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"input": {
"taxResidency": {
"countries": [
"GB"
]
}
}
}
'Copy
Ask AI
{
"taxDetails": {
"status": "pending",
"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}$"
}
}
}
},
"taxIdentification": {
"title": "Tax Identification and Certification",
"type": "object",
"additionalProperties": false,
"properties": {
"documents": {
"title": "Tax Identification Documents",
"type": "array",
"items": {
"allOf": [
{
"type": "object",
"properties": {
"country": {
"title": "Country",
"type": "string",
"enum": [
"GB"
]
},
"type": {
"title": "Document type",
"type": "string",
"enum": [
"tin"
]
},
"number": {
"title": "Document number",
"type": "string",
"pattern": "^\\S.*\\S$|^\\S$"
},
"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"
]
},
{
"if": {
"type": "object",
"properties": {
"reason": {
"const": "user-unable-to-obtain-document"
}
},
"required": [
"reason"
]
},
"then": {
"type": "object",
"required": [
"justification"
]
}
},
{
"oneOf": [
{
"type": "object",
"required": [
"number"
]
},
{
"type": "object",
"required": [
"reason"
]
}
]
}
]
}
},
"certify": {
"title": "I confirm that the information provided is accurate.",
"type": "boolean"
}
},
"required": [
"documents",
"certify"
]
}
}
},
"uiSchema": {
"type": "Categorization",
"elements": [
{
"label": "Tax Residency Declaration",
"type": "Category",
"elements": [
{
"label": "Countries of tax residence",
"type": "Control",
"scope": "#/properties/taxResidency/countries"
}
]
},
{
"label": "Tax Identification and Certification",
"type": "Category",
"elements": [
{
"label": "Tax identification documents",
"type": "Control",
"scope": "#/properties/taxIdentification/documents"
},
{
"label": "I confirm that the information provided is accurate.",
"type": "Control",
"scope": "#/properties/taxIdentification/certify"
}
]
}
]
}
}
}
}KYC
Update tax details
Update the tax details process for a user.
PATCH
/
core
/
kyc
/
processes
/
tax-details
Copy
Ask AI
curl --request PATCH \
--url https://api.enterprise.sandbox.uphold.com/core/kyc/processes/tax-details \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"input": {
"taxResidency": {
"countries": [
"GB"
]
}
}
}
'Copy
Ask AI
{
"taxDetails": {
"status": "pending",
"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}$"
}
}
}
},
"taxIdentification": {
"title": "Tax Identification and Certification",
"type": "object",
"additionalProperties": false,
"properties": {
"documents": {
"title": "Tax Identification Documents",
"type": "array",
"items": {
"allOf": [
{
"type": "object",
"properties": {
"country": {
"title": "Country",
"type": "string",
"enum": [
"GB"
]
},
"type": {
"title": "Document type",
"type": "string",
"enum": [
"tin"
]
},
"number": {
"title": "Document number",
"type": "string",
"pattern": "^\\S.*\\S$|^\\S$"
},
"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"
]
},
{
"if": {
"type": "object",
"properties": {
"reason": {
"const": "user-unable-to-obtain-document"
}
},
"required": [
"reason"
]
},
"then": {
"type": "object",
"required": [
"justification"
]
}
},
{
"oneOf": [
{
"type": "object",
"required": [
"number"
]
},
{
"type": "object",
"required": [
"reason"
]
}
]
}
]
}
},
"certify": {
"title": "I confirm that the information provided is accurate.",
"type": "boolean"
}
},
"required": [
"documents",
"certify"
]
}
}
},
"uiSchema": {
"type": "Categorization",
"elements": [
{
"label": "Tax Residency Declaration",
"type": "Category",
"elements": [
{
"label": "Countries of tax residence",
"type": "Control",
"scope": "#/properties/taxResidency/countries"
}
]
},
{
"label": "Tax Identification and Certification",
"type": "Category",
"elements": [
{
"label": "Tax identification documents",
"type": "Control",
"scope": "#/properties/taxIdentification/documents"
},
{
"label": "I confirm that the information provided is accurate.",
"type": "Control",
"scope": "#/properties/taxIdentification/certify"
}
]
}
]
}
}
}
}
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, while EU residents must declare their countries of tax residence and relevant tax identification numbers.
When calling
GET /core/kyc?detailed=taxDetails, you will get a hint property which includes a JSON form 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 section.Authorizations
OAuth 2.0 authentication.
Headers
The natural language and locale that the client prefers.
Body
application/json
- Dynamic Form
- Legacy Form (deprecated)
Dynamic form input following the JSON Forms specification, enabling progressive disclosure of properties and anytime submissions to keep tax details up to date.
Response
KYC tax details process updated.
Show child attributes
Show child attributes
Status of the KYC process.
Available options:
ok, failed, running, pending, exempt The declared tax details.
Hints for the KYC process.
Show child attributes
Show child attributes
The type of the hint.
Available options:
form The definition of the structure and validation rules for this KYC process form.
It follows the JSON Schema specification with the power of JSON Forms.
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.
The uiSchema property defines the general layout and presentation of the form by means of different UI schema elements.
It follows the JSON Forms 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 liketypeto define the layout type (e.g.,Categorization) andelementsto define the child elements.Controls: Used to define the form controls. It includes properties likescopeto point to the corresponding schema property andlabelto define the control's label.Rules: Used to define conditional visibility rules for form controls. It includes properties likeeffectto define the rule effect (e.g.,SHOW) andconditionto 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.
The id of the form.
⌘I