Skip to main content
PATCH
/
core
/
kyc
/
processes
/
tax-details
Update tax details
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"
      ]
    }
  }
}
'
{
  "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",
                "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$"
                    },
                    "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": {
                  "dataSource": "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"
              }
            ]
          }
        ]
      }
    }
  }
}
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 dynamic 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

​
Authorization
string
header
required

OAuth 2.0 authentication.

Headers

​
Accept-Language
string

The natural language and locale that the client prefers.

Body

application/json

Dynamic form input following the JSON Forms specification, enabling progressive disclosure of properties and anytime submissions to keep tax details up to date.

​
input
object
required
​
output
object

Output of the KYC process.

Response

KYC tax details process updated.

​
taxDetails
object
required