---
title: "Update entity user"
method: PATCH
path: "/participants/entity/{participant_code}/users/{user_code}"
tags: ["Entity Participants"]
---

# Update entity user

`PATCH /participants/entity/{participant_code}/users/{user_code}`

Update one or more fields of an existing Entity user (Control Person, Beneficial Owner, or Board Member). This is a partial update endpoint - only the fields provided in the request body will be updated.

**Important notes:**

**Platform configuration:**
- Your platform must be properly configured before using this endpoint.

**PII changes and document requirements:**
- When users are updated with new identifying information (such as `first_name`, `last_name`, `date_of_birth`, or `citizenship_code`), these changes must be accompanied by supporting documentation.
- Use the Submit Documents endpoint with the appropriate document type to provide supporting documents.

**Compliance field updates:**
- Updating KYC-related fields (`sanction_screening`, `kyc`, `id_number_type`, etc.) may require re-verification depending on your platform configuration.
- Changes to identity documents or verification status may trigger additional compliance checks.

**Vendor reliance track:**
- For platforms using vendor reliance track, `sanction_screening` and `kyc` fields must be provided with vendor verification results.
- `sanction_screening_timestamp` and `kyc_timestamp` should be set to the time when the vendor completed the verification (in milliseconds since Unix epoch).

**Conditional requirements:**
- If `id_number_type` is `non_us_other`, the `non_us_other_type` field is required to describe the ID type.
- For non-US citizens or when `tax_id` is an ITIN (begins with 9), `id_number_type` and `id_number` are required.

**Response:**
Returns the complete user object with all fields, including unchanged fields and system-generated metadata.

## Path parameters

- `participant_code` string, required
- `user_code` string, required

## Headers

- `X-SCX-SIGNED` string, required
- `X-SCX-TIMESTAMP` string, required

## Request body

- PatchUserBody
  - `first_name` string — The first name of the user
  - `middle_name` string — The middle name of the user
  - `last_name` string — The last name of the user
  - `email` string — Email address of the user
  - `contact_number` string — The phone number of the user. Must be in E.164 format
  - `address_one` string — First line for the user's address. Notes: - The regular maximum length is 80 characters. - If the platform is on the vendor reliance track, the maximum length increases to 200 characters. - PO Box addresses are not accepted.
  - `address_two` string — Extra information, like an apartment or suite number. Notes: - The regular maximum length is 50 characters. - If the platform is on the vendor reliance track, the maximum length increases to 200 characters. - PO Box addresses are not accepted.
  - `city` string — City of the user
  - `postal_code` string — Postal, or zip code, of the user, in the format "min 4 characters, no leading or trailing spaces" for non-US postal code or <5digits>-<4digits> for US zip code, e.g. 77777 or 77777-7777
  - `jurisdiction_code` string — The ISO 3166-2 subdivision code that the user resides in
  - `date_of_birth` string — Birth date of the user
  - `place_of_birth` object — The place of birth of the user, as is defined on their ID (Passport, etc.)
    - `country_code` string, required — ISO 3166-1 alpha-2 Country Code
    - `place_name` string — Name of the place of birth
  - `citizenship_code` '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' | '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' | 'YE' | 'YT' | 'ZA' | 'ZM' | 'ZW' — The ISO-3166-1 alpha2 citizenship of the user, e.g. `US`.
  - `tax_id` string — The national ID of the user, e.g. a social security number. Required if `citizenship=United States` or `citizenship_code=US`. Note: if `citizenship=United States`, and `tax_id` begins with `9`, then `id_number_type` and `id_number` are also required.
  - `id_number_type` 'us_drivers_license' | 'us_passport' | 'us_passport_card' | 'us_permanent_resident_card' | 'us_border_crossing_card' | 'us_alien_card' | 'us_id_card' | 'non_us_passport' | 'non_us_other' | 'passport' | 'eu_drivers_license' | 'national_id' | 'legal_entity_identifier' | 'chamber_of_commerce_number' | 'value_added_tax_number' — The type of identification number provided. **Allowed values:** - `us_drivers_license` - US Driver's License - `us_passport` - US Passport - `us_passport_card` - US Passport Card - `us_permanent_resident_card` - US Permanent Resident Card (Green Card) - `us_border_crossing_card` - US Border Crossing Card - `us_alien_card` - US Alien Registration Card - `us_id_card` - US State-issued ID Card - `non_us_passport` - Non-US Passport - `non_us_other` - Other Non-US identification (requires `non_us_other_type` field) - `passport` - Generic passport - `eu_drivers_license` - European Union Driver's License - `national_id` - National identity card - `legal_entity_identifier` - Legal Entity Identifier (LEI) for organizations - `chamber_of_commerce_number` - Chamber of Commerce registration number - `value_added_tax_number` - VAT identification number **Conditional requirements:** - When `id_number_type` is `non_us_other`, the `non_us_other_type` field is required. **Note:** Required when citizenship is not `United States` or `tax_id` is not an SSN.
  - `id_number` string — ID number of the ID document provided. Required when citizenship is not `United States` or `tax_id` is not an SSN
  - `id_issuing_authority` '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' | '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' | 'YE' | 'YT' | 'ZA' | 'ZM' | 'ZW' — ISO-3166-1_A2 country code that issued the ID. Required if `id_number` is provided.
  - `non_us_other_type` string — This is required if you select `non_us_other` for the `id_number_type` - a freeform string to describe the ID type
  - `sanction_screening` 'pass' | 'fail' — Result of the user's sanctions screening. **Allowed values:** - `pass` - User passed sanctions screening - `fail` - User failed sanctions screening
  - `sanction_screening_timestamp` number — UNIX timestamp (in milliseconds) when the sanctions screening was performed on the user.
  - `kyc` 'pass' | 'fail' — Whether the user passed or failed KYC verification by vendor. **Allowed values:** - `pass` - KYC verification passed - `fail` - KYC verification failed
  - `kyc_timestamp` number — The UNIX timestamp (in milliseconds) when KYC was passed. This timestamp value must be from no longer than one (1) year in the past or one (1) day in the future.
  - `role` string — The role of the user

## Response `200`

Successfully updated entity user. Returns the updated resource.

- PatchUserResponse
  - `participant_code` string — The identifier of the participant making the request
  - `user_code` string — zerohash identifier for the User (One code returned per person)
  - `email` string — Email address of user
  - `contact_number` string — The phone number of the user. Must be in E.164 format
  - `name` string — Full name of the user
  - `first_name` string — The first name of the user
  - `middle_name` string — The middle name of the user
  - `last_name` string — The last name of the user
  - `address_one` string — First line for the user's address. Notes: - The regular maximum length is 80 characters. - If the platform is on the vendor reliance track, the maximum length increases to 200 characters. - PO Box addresses are not accepted.
  - `address_two` string — Extra information, like an apartment or suite number. Notes: - The regular maximum length is 50 characters. - If the platform is on the vendor reliance track, the maximum length increases to 200 characters. - PO Box addresses are not accepted.
  - `city` string — City of the user
  - `postal_code` string — Postal, or zip code, of the user, in the format "min 4 characters, no leading or trailing spaces" for non-US postal code or <5digits>-<4digits> for US zip code, e.g. 77777 or 77777-7777
  - `jurisdiction_code` string — The ISO 3166-2 subdivision code that the user resides in
  - `date_of_birth` string — Birth date of the user
  - `place_of_birth` object — The place of birth of the user, as is defined on their ID (Passport, etc.)
    - `country_code` string, required — ISO 3166-1 alpha-2 Country Code
    - `place_name` string — Name of the place of birth
  - `citizenship_code` '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' | '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' | 'YE' | 'YT' | 'ZA' | 'ZM' | 'ZW' — The ISO-3166-1 alpha2 citizenship of the user, e.g. `US`.
  - `tax_id` string — The national ID of the user, e.g. a social security number. Required if `citizenship=United States` or `citizenship_code=US`. Note: if `citizenship=United States`, and `tax_id` begins with `9`, then `id_number_type` and `id_number` are also required.
  - `id_number_type` 'us_drivers_license' | 'us_passport' | 'us_passport_card' | 'us_permanent_resident_card' | 'us_border_crossing_card' | 'us_alien_card' | 'us_id_card' | 'non_us_passport' | 'non_us_other' | 'passport' | 'eu_drivers_license' | 'national_id' | 'legal_entity_identifier' | 'chamber_of_commerce_number' | 'value_added_tax_number' — The type of identification number provided. **Allowed values:** - `us_drivers_license` - US Driver's License - `us_passport` - US Passport - `us_passport_card` - US Passport Card - `us_permanent_resident_card` - US Permanent Resident Card (Green Card) - `us_border_crossing_card` - US Border Crossing Card - `us_alien_card` - US Alien Registration Card - `us_id_card` - US State-issued ID Card - `non_us_passport` - Non-US Passport - `non_us_other` - Other Non-US identification (requires `non_us_other_type` field) - `passport` - Generic passport - `eu_drivers_license` - European Union Driver's License - `national_id` - National identity card - `legal_entity_identifier` - Legal Entity Identifier (LEI) for organizations - `chamber_of_commerce_number` - Chamber of Commerce registration number - `value_added_tax_number` - VAT identification number **Conditional requirements:** - When `id_number_type` is `non_us_other`, the `non_us_other_type` field is required. **Note:** Required when citizenship is not `United States` or `tax_id` is not an SSN.
  - `id_number` string — ID number of the ID document provided. Required when citizenship is not `United States` or `tax_id` is not an SSN
  - `id_issuing_authority` string — ISO-3166-1_A2 country code that issued the ID. Required if `id_number` is provided.
  - `non_us_other_type` string — A freeform string to describe the ID type
  - `sanction_screening` 'pass' | 'fail' — Result of the user's sanctions screening. **Allowed values:** - `pass` - User passed sanctions screening - `fail` - User failed sanctions screening
  - `sanction_screening_timestamp` number — UNIX timestamp (in milliseconds) when the sanctions screening was performed on the user.
  - `kyc` 'pass' | 'fail' — Whether the user passed or failed KYC verification by vendor. **Allowed values:** - `pass` - KYC verification passed - `fail` - KYC verification failed
  - `kyc_timestamp` number — The UNIX timestamp (in milliseconds) when KYC was passed. This timestamp value must be from no longer than one (1) year in the past or one (1) day in the future.
  - `role` string — The role of the user
  - `platform_updated_at` number — UNIX timestamp (in milliseconds) when the platform last updated the user's information.

## Other responses

- `400` — Bad Request
- `403` — Forbidden
- `404` — Not Found
- `500` — Internal Server Error
- `503` — Service Unavailable

---

[API](https://skmtc.net/zerohash/apis/zerohash-api.md) · [All operations](https://skmtc.net/zerohash/apis/zerohash-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/zerohash/zerohash-api/revisions/8b647d934363/schema)