Core API
- Concepts
- Authentication
- Countries
- Users
- KYC
- 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
- Webhooks
- Capabilities
- Terms of Service
- Files
- Assets
- Accounts
- External Accounts
- Transactions
- Webhooks
Widgets API
- Payment
Update tax details
Update the tax details process for a user.
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": {
"formId": "7a0f4229-e3de-4dfd-8f91-9b1308b2dc33",
"answers": {
"tax-identification": {
"tin": "123456780",
"w9-certify-all": true,
"w9-signature": "John Doe"
}
}
}
}'
{
"taxDetails": {
"status": "pending",
"input": {
"formId": "bbe3b6cd-a5a8-4e86-84b3-be83292de2ef",
"answers": {
"tax-details": {
"continue": true
}
}
},
"hint": {
"type": "form",
"formId": "bbe3b6cd-a5a8-4e86-84b3-be83292de2ef",
"schema": {
"properties": {
"tax-details": {
"type": "object",
"title": "Tax Details",
"properties": {
"continue": {
"type": "boolean",
"title": "Continue",
"const": true
}
},
"unevaluatedProperties": false,
"required": [
"continue"
]
},
"tax-identification": {
"type": "object",
"title": "Taxpayer Identification and Certification",
"description": "We'll ask you to provide your Social Security number (SSN) or Taxpayer Identification Number (TIN) and certify that your information is correct by submitting a W-9 Form. This will allow our partner, TaxBit, to issue your tax forms each year.<br><br>Why is this needed? As a regulated financial institution, Uphold is legally required to collect and verify your SSN/TIN so the U.S. Internal Revenue Service (IRS) can properly assess taxes that may be due.",
"properties": {
"tin": {
"type": "string",
"pattern": "^\\S.*\\S$|^\\S$",
"title": "What's your SSN/TIN number?"
},
"w9-certify-all": {
"type": "boolean",
"title": "Certify to all.",
"description": "<h4>W-9 Form</h4><p>Please certify the information below is correct.</p><p>Under the penalty of perjury, I certify that:</p><ul><li>The Social Security number (SSN) previously provided is correct.</li><li>I am not subject to backup withholding because:<ul><li>I am exempt from backup withholding, or</li><li>I have not been notified by the Internal Revenue Service (IRS) that I am subject to backup withholding as a result of a failure to report all interest or dividends, or</li><li>the IRS has notified me that I am no longer subject to backup withholding.</li></ul></li><li>I am a U.S. citizen or other U.S. person.</li><li>The FATCA code entered on this form (if any) indicating that I am exempt from FATCA reporting is correct.</li><li>The IRS does not require my consent to any provision of this document other than the certifications required to prevent backup withholding.</li></ul>",
"const": true
},
"w9-signature": {
"type": "string",
"title": "Full legal name",
"description": "<b>E-Signature</b><p>I acknowledge that by typing my name below, as per the E-Sign Act, I am providing an e-signature that is the legal equivalent to my manual signature.</p>",
"pattern": "(?:\\w+[ ]+){1,}\\w+"
}
},
"unevaluatedProperties": false,
"required": [
"tin",
"w9-certify-all",
"w9-signature"
]
}
},
"type": "object"
},
"uiSchema": {
"type": "Categorization",
"elements": [
{
"type": "Category",
"label": "Tax Details",
"elements": [
{
"type": "Control",
"scope": "#/properties/tax-details/properties/continue"
}
]
},
{
"type": "Category",
"label": "Taxpayer Identification and Certification",
"elements": [
{
"scope": "#/properties/tax-identification/properties/tin",
"type": "Control"
},
{
"scope": "#/properties/tax-identification/properties/w9-certify-all",
"type": "Control"
},
{
"scope": "#/properties/tax-identification/properties/w9-signature",
"type": "Control"
}
]
}
]
}
}
}
}
The tax-details is a form based KYC process composed of questions used to collect the user tax information, such as its TIN and to details necessary for us to submit the W9 Form.
This KYC process status will be exempt
for all non-US tax payers users, that is, users that are not residing in US
nor have US
citizenship.
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.
Please read more about forms in the Introduction page.
Authorizations
OAuth 2.0 authentication.
Headers
The natural language and locale that the client prefers.
Body
Input of the KYC process.
The id of the form.
The answers
property follows the JSON Forms specification for data objects and has two key behaviors:
- Partial or Complete Answers Submission:
- It accepts the answers to the questions of the current step (identified by UI Schema 'Category'). This allows the submission of the responses incrementally, either answering all questions in the current step or just a subset of them.
- Form Reset by Answering Previous Questions:
- It also allows for a form reset by accepting one or more answers from a previous step (identified by UI Schema 'Category'). This enables the modification of previous answers, ensuring that the form is flexible and can handle dynamic user interactions.
The KYC process starts its evaluation once the last question has been answered, ensuring that all necessary information has been provided before proceeding with the assessment.
Response
Status of the KYC process.
ok
, failed
, running
, pending
, exempt
Output of the KYC process.
The output result of the KYC process.
approved
, none
, rejected
The date and time of the verification.
Hints for the KYC process.
The type of the hint.
form
The id of the 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 liketype
to define the layout type (e.g.,Categorization
) andelements
to define the child elements.Controls
: Used to define the form controls. It includes properties likescope
to point to the corresponding schema property andlabel
to define the control's label.Rules
: Used to define conditional visibility rules for form controls. It includes properties likeeffect
to define the rule effect (e.g.,SHOW
) andcondition
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.
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": {
"formId": "7a0f4229-e3de-4dfd-8f91-9b1308b2dc33",
"answers": {
"tax-identification": {
"tin": "123456780",
"w9-certify-all": true,
"w9-signature": "John Doe"
}
}
}
}'
{
"taxDetails": {
"status": "pending",
"input": {
"formId": "bbe3b6cd-a5a8-4e86-84b3-be83292de2ef",
"answers": {
"tax-details": {
"continue": true
}
}
},
"hint": {
"type": "form",
"formId": "bbe3b6cd-a5a8-4e86-84b3-be83292de2ef",
"schema": {
"properties": {
"tax-details": {
"type": "object",
"title": "Tax Details",
"properties": {
"continue": {
"type": "boolean",
"title": "Continue",
"const": true
}
},
"unevaluatedProperties": false,
"required": [
"continue"
]
},
"tax-identification": {
"type": "object",
"title": "Taxpayer Identification and Certification",
"description": "We'll ask you to provide your Social Security number (SSN) or Taxpayer Identification Number (TIN) and certify that your information is correct by submitting a W-9 Form. This will allow our partner, TaxBit, to issue your tax forms each year.<br><br>Why is this needed? As a regulated financial institution, Uphold is legally required to collect and verify your SSN/TIN so the U.S. Internal Revenue Service (IRS) can properly assess taxes that may be due.",
"properties": {
"tin": {
"type": "string",
"pattern": "^\\S.*\\S$|^\\S$",
"title": "What's your SSN/TIN number?"
},
"w9-certify-all": {
"type": "boolean",
"title": "Certify to all.",
"description": "<h4>W-9 Form</h4><p>Please certify the information below is correct.</p><p>Under the penalty of perjury, I certify that:</p><ul><li>The Social Security number (SSN) previously provided is correct.</li><li>I am not subject to backup withholding because:<ul><li>I am exempt from backup withholding, or</li><li>I have not been notified by the Internal Revenue Service (IRS) that I am subject to backup withholding as a result of a failure to report all interest or dividends, or</li><li>the IRS has notified me that I am no longer subject to backup withholding.</li></ul></li><li>I am a U.S. citizen or other U.S. person.</li><li>The FATCA code entered on this form (if any) indicating that I am exempt from FATCA reporting is correct.</li><li>The IRS does not require my consent to any provision of this document other than the certifications required to prevent backup withholding.</li></ul>",
"const": true
},
"w9-signature": {
"type": "string",
"title": "Full legal name",
"description": "<b>E-Signature</b><p>I acknowledge that by typing my name below, as per the E-Sign Act, I am providing an e-signature that is the legal equivalent to my manual signature.</p>",
"pattern": "(?:\\w+[ ]+){1,}\\w+"
}
},
"unevaluatedProperties": false,
"required": [
"tin",
"w9-certify-all",
"w9-signature"
]
}
},
"type": "object"
},
"uiSchema": {
"type": "Categorization",
"elements": [
{
"type": "Category",
"label": "Tax Details",
"elements": [
{
"type": "Control",
"scope": "#/properties/tax-details/properties/continue"
}
]
},
{
"type": "Category",
"label": "Taxpayer Identification and Certification",
"elements": [
{
"scope": "#/properties/tax-identification/properties/tin",
"type": "Control"
},
{
"scope": "#/properties/tax-identification/properties/w9-certify-all",
"type": "Control"
},
{
"scope": "#/properties/tax-identification/properties/w9-signature",
"type": "Control"
}
]
}
]
}
}
}
}