# Update tax residencies Records the tax residencies for the user identified by `user_id`, replacing any previously submitted set. See the User tax onboarding guide ([TOL](https://docs.upvest.co/products/tol/guides/users/users_tax_onboarding) / [BYOL](https://docs.upvest.co/products/byol/guides/users/users_tax_onboarding)) for tax residency requirements. Endpoint: POST /users/{user_id}/tax_residencies Version: 1.136.0 Security: oauth-client-credentials ## Path parameters: - `user_id` (string, required) The unique identifier of the user. Universally Unique Identifier (UUID). ## Header parameters: - `idempotency-key` (string, required) A UUID to be used as an idempotency key. This prevents a duplicate request from being replayed. https://docs.upvest.co/documentation/concepts/api_concepts/idempotency - `upvest-client-id` (string, required) Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID). - `Authorization` (string, required) Bearer (access) token from the OAuth flow with correct scopes. https://datatracker.ietf.org/doc/html/rfc6750 - `signature` (string, required) https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header - `signature-input` (string, required) https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he - `upvest-api-version` (string) Upvest API version (Note: Do not include quotation marks) ## Request fields (application/json): - `tax_residencies` (array, required) Tax residencies to record for the user. Must contain at least one entry - `tax_residencies.country` (string, required) Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). Enum: "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" - `tax_residencies.tax_identifier_number` (string, required) Tax identification number (TIN) issued to the user by the tax authorities of the given country - `tax_residencies.missing_tin_reason` (string, required) Reason why TIN is missing * TIN_NOT_YET_ASSIGNED - Indicates that the tax identification number has not yet been assigned by the tax authorities. A common example is, that a user has moved to a country and thus became taxable, but that the tax authorities have not yet assigned the TIN to this user. * COUNTRY_HAS_NO_TIN - Indicates that the specific country does not provide a TIN. * OTHER_REASONS - Applies in case of other reasons - i.e. when a user does not have the TIN at hand. Note this may cause additional inquiries by our customer service team. Enum: "TIN_NOT_YET_ASSIGNED", "COUNTRY_HAS_NO_TIN", "OTHER_REASONS" ## Response 200 fields (application/json): - `created_at` (string, required) Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html) - `updated_at` (string, required) Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html) - `tax_residencies` (array, required) Tax residencies contained in this record - `tax_residencies.country` (string, required) Accepted country code. [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). Enum: "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YE", "YT", "ZA", "ZM", "ZW" - `tax_residencies.tax_identifier_number` (string, required) Tax identification number (TIN) issued to the user by the tax authorities of the given country - `tax_residencies.missing_tin_reason` (string, required) Reason why TIN is missing * TIN_NOT_YET_ASSIGNED - Indicates that the tax identification number has not yet been assigned by the tax authorities. A common example is, that a user has moved to a country and thus became taxable, but that the tax authorities have not yet assigned the TIN to this user. * COUNTRY_HAS_NO_TIN - Indicates that the specific country does not provide a TIN. * OTHER_REASONS - Applies in case of other reasons - i.e. when a user does not have the TIN at hand. Note this may cause additional inquiries by our customer service team. Enum: "TIN_NOT_YET_ASSIGNED", "COUNTRY_HAS_NO_TIN", "OTHER_REASONS" - `status` (string, required) Tax residency status * PENDING - It indicates that the tax residency records are not yet processed by Upvest. * ACTIVE - It indicates that tax residency records are processed, and the tax residency record is the one in use. Enum: "PENDING", "ACTIVE" ## Response 400 fields (application/problem+json): - `type` (string, required) URL to a document describing the error condition. - `status` (integer, required) Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers. - `title` (string) A short, human-readable title for the general error type; the title should not change for given types. - `detail` (string) A human-readable description of the specific error. - `instance` (string) This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response. - `request_id` (string) Correlation ID for the original request. ## Response 401 fields (application/problem+json): - `type` (string, required) URL to a document describing the error condition. - `status` (integer, required) Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers. - `title` (string) A short, human-readable title for the general error type; the title should not change for given types. - `detail` (string) A human-readable description of the specific error. - `instance` (string) This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response. - `request_id` (string) Correlation ID for the original request. ## Response 403 fields (application/problem+json): - `type` (string, required) URL to a document describing the error condition. - `status` (integer, required) Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers. - `title` (string) A short, human-readable title for the general error type; the title should not change for given types. - `detail` (string) A human-readable description of the specific error. - `instance` (string) This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response. - `request_id` (string) Correlation ID for the original request. ## Response 404 fields (application/problem+json): - `type` (string, required) URL to a document describing the error condition. - `status` (integer, required) Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers. - `title` (string) A short, human-readable title for the general error type; the title should not change for given types. - `detail` (string) A human-readable description of the specific error. - `instance` (string) This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response. - `request_id` (string) Correlation ID for the original request. ## Response 406 fields (application/problem+json): - `type` (string, required) URL to a document describing the error condition. - `status` (integer, required) Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers. - `title` (string) A short, human-readable title for the general error type; the title should not change for given types. - `detail` (string) A human-readable description of the specific error. - `instance` (string) This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response. - `request_id` (string) Correlation ID for the original request. ## Response 429 fields (application/problem+json): - `type` (string, required) URL to a document describing the error condition. - `status` (integer, required) Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers. - `title` (string) A short, human-readable title for the general error type; the title should not change for given types. - `detail` (string) A human-readable description of the specific error. - `instance` (string) This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response. - `request_id` (string) Correlation ID for the original request. ## Response 500 fields (application/problem+json): - `type` (string, required) URL to a document describing the error condition. - `status` (integer, required) Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers. - `title` (string) A short, human-readable title for the general error type; the title should not change for given types. - `detail` (string) A human-readable description of the specific error. - `instance` (string) This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response. - `request_id` (string) Correlation ID for the original request. ## Response 503 fields (application/problem+json): - `type` (string, required) URL to a document describing the error condition. - `status` (integer, required) Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers. - `title` (string) A short, human-readable title for the general error type; the title should not change for given types. - `detail` (string) A human-readable description of the specific error. - `instance` (string) This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response. - `request_id` (string) Correlation ID for the original request. ## Response 504 fields (application/problem+json): - `type` (string, required) URL to a document describing the error condition. - `status` (integer, required) Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers. - `title` (string) A short, human-readable title for the general error type; the title should not change for given types. - `detail` (string) A human-readable description of the specific error. - `instance` (string) This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response. - `request_id` (string) Correlation ID for the original request.