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

# Update entity customer

`PATCH /participants/entity/{participant_code}`

Updates an entity customer affiliated with your platform. Your platform will need to be configured properly before you can use this endpoint.

## Path parameters

- `participant_code` string, required

## Headers

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

## Request body

- PatchEntityBody
  - `entity_name` string — Name of the business
  - `legal_name` string — Registered legal name of the entity. This should not be a DBA or DBA equivalent
  - `contact_number` string — Phone number of the business
  - `website` string — Business website
  - `date_established` string — Date the business was established. This should reflect government registration for the entity in the format `YYYY-MM-DD`
  - `entity_type` 'corporation' | 'llc' | 'partnership' | 'sole_proprietorship' | 'other' | 'non_profit' | 'llc_c' | 'llc_s' | 'llc_p' | 's_corporation' | 'c_corporation' | 'trust_estate' — The type of business that is onboarding, must be one of the supported
  - `address_one` string — First line for the business'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 — The city customer resides in
  - `postal_code` string — Postal, or zip code, of the business, 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
  - `tax_id` string — Tax identifier of the business (e.g. EIN in United States)
  - `id_issuing_authority` string — ISO-3166-1_A2 country code that issued the tax identifier (e.g. “US”)
  - `risk_rating` 'low' | 'medium' | 'high' — Risk assessed by the platform's vendor
  - `onboarding_profile` 'kyc_track' | 'shopper' | 'originator_entity' | 'payouts_payor_ultimate' | 'payouts_beneficiary' — Onboarding profile used to determine the entity's KYC track. Optional. Defaults to 'kyc_track' when omitted.
  - `sanction_screening` 'pass' | 'fail' — Result of the business sanctions screen
  - `sanction_screening_timestamp` number — The time the sanctions screen was done
  - `self_certification_timestamp` number — The UNIX timestamp (in milliseconds) when the participant completed self-certification for DAC8 compliance. Mandatory for participants that are based in Europe.
  - `signed_timestamp` number — The time at which the business accepted zerohash services agreements
  - `signed_agreements` object[] — The agreements signed by the entity. An array of agreement objects with region, type, and timestamp.
    - `type` 'fund_auto_convert' | 'payment_services_terms' | 'account_link' | 'account_funding_payouts' | 'account_funding_general' | 'account_funding_pay' | 'crypto_payouts_service_terms' | 'staking' | 'trust_agreement' | 'zhllc_user_agreement_v1' | 'zhllc_privacy_policy_v1' | 'zhllc_regulatory_disclosures_v1' | 'auth_user_services_agreement_v1' | 'zhllc_payment_sender_terms_v1' | 'zhllc_third_party_disclosures_v1' | 'connect_privacy_policy_v1' — The type of the agreement signed
    - `region` 'worldwide' | 'us' | 'brazil' | 'uk' | 'eu', required — The region for the signed agreement
    - `signed_timestamp` number, required — The UNIX timestamp (in milliseconds) when the Agreement was accepted by the entity. This timestamp value must be from no longer than one (1) year in the past or one (1) day in the future.
  - `submitter_email` string, required — Email of the person who completed the KYC application and agreed to terms
  - `submitter_first_name` string — Submitter first name
  - `submitter_last_name` string — Submitter last name
  - `submitter_title` string — The title or honorific of the individual submitting the form (e.g., Mr., Ms., Dr.).
  - `incorporation_address` object — Full address where the entity is incorporated
    - `address_one` string — First line of incorporation address
    - `address_two` string — Second line of incorporation address (optional)
    - `city` string — City of incorporation
    - `jurisdiction_code` string, required — Jurisdiction code in ISO-3166-2 format
    - `postal_code` string — Postal code of incorporation address
  - `tax_residence` object — Tax residence address for the entity
    - `address_one` string — First line of tax residence address
    - `address_two` string — Second line of tax residence address (optional)
    - `city` string — City of tax residence
    - `jurisdiction_code` string, required — Jurisdiction code in ISO-3166-2 format
    - `postal_code` string — Postal code of tax residence
  - `tin_jurisdiction_reason` 'working_abroad' | 'studying_abroad' | 'dual_residency' | 'business_abroad' | 'real_estate_abroad' | 'other' — Optional. Reason for the tax residence jurisdiction differing from the legal jurisdiction. Defaults to "unknown" if not provided.
  - `additional_tax_residences` AdditionalTaxResidence[] — Optional. Additional tax residences when the entity has tax obligations in multiple jurisdictions. Maximum 25 items.
    - `tax_id` string, required — Tax identification number for the additional tax residence
    - `jurisdiction_code` string, required — The ISO 3166-2 subdivision code that the participant resides in
  - `tin_jurisdiction_other` string — Optional. Free text explanation when `tin_jurisdiction_reason` is `other`
  - `control_persons` ControlPersonEntity[]
    - `name` string — Full name of the control person
    - `email` string — Email address of control person
    - `address_one` string — First line for the control person'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 control person
    - `postal_code` string — Postal, or zip code, of the control person, 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 control person resides in
    - `date_of_birth` string — Birth date of the control person
    - `phone_number` string — The phone number of the control person
    - `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 control person, e.g. `US`.
    - `tax_id` string — The national ID of the control person, 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.
    - `sanction_screening` 'pass' | 'fail' — Result of the control person's sanctions screening. **Allowed values:** - `pass` - Control person passed sanctions screening - `fail` - Control person failed sanctions screening
    - `sanction_screening_timestamp` number — UNIX timestamp (in milliseconds) when the sanctions screening was performed on the control person.
    - `kyc` 'pass' | 'fail' — Whether the control person 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.
    - `control_person` 0 | 1 | 2 | 3 — Designation of what percent of the business the control person controls. **Allowed values:** - `0` - Unknown - `1` - Less than 10% - `2` - Greater than or equal to 10% but less than 25% - `3` - Greater than or equal to 25%
  - `beneficial_owners` BeneficialOwnerEntity[]
    - `name` string — Full name of the beneficial owner
    - `email` string — Email address of the beneficial owner
    - `address_one` string — First line for the beneficial owner'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 beneficial owner
    - `postal_code` string — Postal, or zip code, of the beneficial owner, 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 beneficial owner resides in
    - `date_of_birth` string — Birth date of the beneficial owner
    - `phone_number` string — The phone number of the beneficial owner
    - `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 beneficial owner, e.g. `US`.
    - `tax_id` string — The national ID of the beneficial owner, 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.
    - `sanction_screening` 'pass' | 'fail' — Result of the beneficial owner's sanctions screening. **Allowed values:** - `pass` - Beneficial owner passed sanctions screening - `fail` - Beneficial owner failed sanctions screening
    - `sanction_screening_timestamp` number — UNIX timestamp (in milliseconds) when the sanctions screening was performed on the beneficial owner.
    - `kyc` 'pass' | 'fail' — Whether the beneficial owner 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.
    - `beneficial_owner` 0 | 1 | 2 — Designation of what percent of the business the beneficial owner owns. **Allowed values:** - `0` - Unknown - `1` - Greater than or equal to 10% but less than 25% - `2` - Greater than or equal to 25%
    - `role` string — The role of the beneficial owner
  - `b_notice_receipt` boolean — Boolean flag indicating notice receipt status
  - `is_w_form_certified` boolean — W9 form certification flag
  - `w_form_certification` number — W form certification unix timestamp
  - `physical_delivery` boolean — Physical delivery flag
  - `signature` string — This field is used to capture the customer Entity `entity_name` as used on the W-form.
  - `signature_timestamp` number — This field captures the timestamp at which the user signed their W-form, used in conjunction with the `signature` field.
  - `payee_exemption` '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | '10' | '11' | '12' | '13' | 'NONE' — Payee exemption code (1-13 or NONE)
  - `fatca_reporting_exemption` '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | '10' | '11' | '12' | '13' | 'NONE' — FATCA reporting exemption code (1-13 or NONE)
  - `is_not_subject_backup_withholding` boolean — Backup withholding attestation flag. Required for customers onboarded to a US platform. - If the participant confirms they are **not** subject to backup withholding, this field should be set to `true`. - If the participant **is** subject to backup withholding, this field should be set to `false`. This acts as a positive attestation that the participant confirms they are not subject to backup withholding.
  - `dba_name` string — Doing Business As (DBA) name of the entity
  - `other_entity_type` string — Other entity type description when entity_type is "other"
  - `w8_ben_e` object — Wrapper sub-object holding W-8BEN-E tax certification data for a foreign (non-US) entity customer. Inherits all shared W-8 fields plus the entity-only fields below. Optional at the wrapper level.
    - `tax_classification` 'individual' | 'corporation' | 'partnership' | 'simple_trust' | 'complex_trust' | 'grantor_trust' | 'estate' | 'central_bank_of_issue' | 'foreign_government_controlled_entity' | 'foreign_government_integral_part' | 'tax_exempt_organization' | 'private_foundation' | 'international_organization' — Entity's IRS tax classification (e.g. corporation, partnership, trust variants, estate, tax-exempt organization). Required for W-8 form generation when `w8_ben_e` is present. Accepted string tokens listed in enum; legacy numeric values still accepted for backward compatibility.
    - `ftin` string — Foreign tax identification number issued by the entity's country of tax residence. Required unless `ftin_required = false`.
    - `ftin_required` boolean — Whether the entity's country legally issues an FTIN. Required whenever the sub-object is present.
    - `reference_numbers` string — Optional free-text reference numbers for the platform to connect the tax form to a specific account or financial record.
    - `treaty_claim` object — Treaty benefits claim block. Optional.
      - `is_eligible` boolean — Whether the entity is claiming reduced US withholding under a tax treaty. If `false` or omitted, the rest of the treaty block is ignored and no W-8 form is generated.
      - `country` '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' | 'YE' | 'YT' | 'ZA' | 'ZM' | 'ZW' — Entity's country of tax residence whose treaty with the US is being invoked (ISO 3166-1 alpha-2). Required when `is_eligible = true`.
      - `residence_certification` boolean — Entity's on-form attestation that it is a tax resident of `country`. Must be `true` to claim treaty benefits. Required when `is_eligible = true`.
      - `income_type` 'royalties_other' | 'business_profits' — Category of US-source income the claim applies to: `business_profits` covers trading gains and similar active income; `royalties_other` covers royalties and other passive income. Required when `is_eligible = true`. Accepted string tokens listed in enum; legacy numeric values still accepted for backward compatibility.
      - `withholding_rate` string — Reduced rate granted by the treaty article, as a string percentage (e.g. "0", "10", "15"). Required when `is_eligible = true`.
      - `article_paragraph` string — Treaty article and paragraph authorizing the rate (e.g. "Article 7, paragraph 1"). Free text but should match the actual treaty section. Required when `is_eligible = true`.
      - `additional_conditions` boolean — Whether the entity asserts that extra conditions in the treaty article are met. Send `true` only if the entity has affirmatively confirmed. Required when `is_eligible = true`.
      - `requirements_certification` boolean — Entity's on-form attestation that it derives the relevant income and meets all qualifying tests of the treaty provision. Must be `true` when an entity is claiming treaty benefits in order to generate a W-8 form. Required when `is_eligible = true`.
      - `limitation_on_benefits` 'government' | 'tax_exempt_pension' | 'other_tax_exempt_organization' | 'publicly_traded_corporation' | 'subsidiary' | 'company_meets_erosion_test' | 'company_meets_derivative_test' | 'company_meets_business_test' | 'favorable_determination' | 'no_lob_article' | 'other_article_paragraph' — Which Limitation on Benefits (LOB) clause the entity qualifies under. Required when `is_eligible = true`. Accepted string tokens listed in enum; legacy numeric values still accepted for backward compatibility.
      - `limitation_on_benefits_other` string — Free-text describing the article and paragraph the entity is relying on. Required when (and only when) `limitation_on_benefits = other_article_paragraph`.
  - `mailing_address` object — Root-level object on both customer and entity payloads (form-agnostic; also reused by W-9). Send only when the participant's mailing address differs from their permanent (W-8BEN) or incorporation (W-8BEN-E) address.
    - `address_one` string — Primary street line of the mailing address. Required when the object is present.
    - `address_two` string — Secondary street line (unit, suite, etc.). Optional.
    - `city` string — City of the mailing address. Required when the object is present.
    - `state` string — State, province, or region of the mailing address. Optional.
    - `postal_code` string — Postal or ZIP code of the mailing address. Required when the object is present.
    - `country` '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' | 'YE' | 'YT' | 'ZA' | 'ZM' | 'ZW' — Country of the mailing address (ISO 3166-1 alpha-2). Required when the object is present.
  - `merchant_category_code` string — ISO 18245 four-digit Merchant Category Code (MCC) that identifies the business activity of the entity. Accepted on entity create/update; zerohash derives `merchant_category_code_category` and `merchant_category_code_classification` from this value.
  - `jurisdiction_code` string — The ISO 3166-2 subdivision code that the entity resides in

## Response `200`

Successfully updated entity participant. Returns the updated resource.

- PatchEntityResponse
  - `message` object
    - `entity_name` string — Name of the business
    - `legal_name` string — Registered legal name of the entity. This should not be a DBA or DBA equivalent
    - `contact_number` string — Phone number of the business
    - `website` string — Business website
    - `date_established` string — Date the business was established. This should reflect government registration for the entity in the format `YYYY-MM-DD`
    - `entity_type` 'corporation' | 'llc' | 'partnership' | 'sole_proprietorship' | 'other' | 'non_profit' | 'llc_c' | 'llc_s' | 'llc_p' | 's_corporation' | 'c_corporation' | 'trust_estate' — The type of business that is onboarding, must be one of the supported
    - `address_one` string — First line for the business'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 — The city customer resides in
    - `postal_code` string — Postal, or zip code, of the business, 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
    - `tax_id` string — Tax identifier of the business (e.g. EIN in United States)
    - `id_issuing_authority` string — ISO-3166-1_A2 country code that issued the tax identifier (e.g. “US”)
    - `risk_rating` 'low' | 'medium' | 'high' — Risk assessed by the platform's vendor
    - `onboarding_profile` 'kyc_track' | 'shopper' | 'originator_entity' | 'payouts_payor_ultimate' | 'payouts_beneficiary' — Onboarding profile used to determine the entity's KYC track. Optional. Defaults to 'kyc_track' when omitted.
    - `sanction_screening` 'pass' | 'fail' — Result of the business sanctions screen
    - `sanction_screening_timestamp` number — The time the sanctions screen was done
    - `self_certification_timestamp` number — The UNIX timestamp (in milliseconds) when the participant completed self-certification for DAC8 compliance. Mandatory for participants that are based in Europe.
    - `signed_timestamp` number — The time at which the business accepted zerohash services agreements
    - `signed_agreements` object[] — The agreements signed by the entity. An array of agreement objects with region, type, and timestamp.
      - `type` 'fund_auto_convert' | 'payment_services_terms' | 'account_link' | 'account_funding_payouts' | 'account_funding_general' | 'account_funding_pay' | 'crypto_payouts_service_terms' | 'staking' | 'trust_agreement' | 'zhllc_user_agreement_v1' | 'zhllc_privacy_policy_v1' | 'zhllc_regulatory_disclosures_v1' | 'auth_user_services_agreement_v1' | 'zhllc_payment_sender_terms_v1' | 'zhllc_third_party_disclosures_v1' | 'connect_privacy_policy_v1' — The type of the agreement signed
      - `region` 'worldwide' | 'us' | 'brazil' | 'uk' | 'eu', required — The region for the signed agreement
      - `signed_timestamp` number, required — The UNIX timestamp (in milliseconds) when the Agreement was accepted by the entity. This timestamp value must be from no longer than one (1) year in the past or one (1) day in the future.
    - `submitter_email` string — Email of the person who completed the KYC application and agreed to terms
    - `incorporation_address` object — Full address where the entity is incorporated
      - `address_one` string — First line of incorporation address
      - `address_two` string — Second line of incorporation address (optional)
      - `city` string — City of incorporation
      - `jurisdiction_code` string, required — Jurisdiction code in ISO-3166-2 format
      - `postal_code` string — Postal code of incorporation address
    - `tax_residence` object — Tax residence address for the entity
      - `address_one` string — First line of tax residence address
      - `address_two` string — Second line of tax residence address (optional)
      - `city` string — City of tax residence
      - `jurisdiction_code` string, required — Jurisdiction code in ISO-3166-2 format
      - `postal_code` string — Postal code of tax residence
    - `tin_jurisdiction_reason` 'working_abroad' | 'studying_abroad' | 'dual_residency' | 'business_abroad' | 'real_estate_abroad' | 'other' — Optional. Reason for the tax residence jurisdiction differing from the legal jurisdiction. Defaults to "unknown" if not provided.
    - `b_notice_receipt` boolean — Boolean flag indicating notice receipt status
    - `is_w_form_certified` boolean — W9 form certification flag
    - `w_form_certification` number — W form certification unix timestamp
    - `physical_delivery` boolean — Physical delivery flag
    - `signature` string — This field is used to capture the customer Entity `entity_name` as used on the W-form.
    - `signature_timestamp` number — This field captures the timestamp at which the user signed their W-form, used in conjunction with the `signature` field.
    - `payee_exemption` '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | '10' | '11' | '12' | '13' | 'NONE' — Payee exemption code (1-13 or NONE)
    - `fatca_reporting_exemption` '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | '10' | '11' | '12' | '13' | 'NONE' — FATCA reporting exemption code (1-13 or NONE)
    - `is_not_subject_backup_withholding` boolean — Backup withholding attestation flag. Required for customers onboarded to a US platform. - If the participant confirms they are **not** subject to backup withholding, this field should be set to `true`. - If the participant **is** subject to backup withholding, this field should be set to `false`. This acts as a positive attestation that the participant confirms they are not subject to backup withholding.
    - `dba_name` string — Doing Business As (DBA) name of the entity
    - `other_entity_type` string — Other entity type description when entity_type is "other"
    - `w8_ben_e` object — Wrapper sub-object holding W-8BEN-E tax certification data for a foreign (non-US) entity customer. Inherits all shared W-8 fields plus the entity-only fields below. Optional at the wrapper level.
      - `tax_classification` 'individual' | 'corporation' | 'partnership' | 'simple_trust' | 'complex_trust' | 'grantor_trust' | 'estate' | 'central_bank_of_issue' | 'foreign_government_controlled_entity' | 'foreign_government_integral_part' | 'tax_exempt_organization' | 'private_foundation' | 'international_organization' — Entity's IRS tax classification (e.g. corporation, partnership, trust variants, estate, tax-exempt organization). Required for W-8 form generation when `w8_ben_e` is present. Accepted string tokens listed in enum; legacy numeric values still accepted for backward compatibility.
      - `ftin` string — Foreign tax identification number issued by the entity's country of tax residence. Required unless `ftin_required = false`.
      - `ftin_required` boolean — Whether the entity's country legally issues an FTIN. Required whenever the sub-object is present.
      - `reference_numbers` string — Optional free-text reference numbers for the platform to connect the tax form to a specific account or financial record.
      - `treaty_claim` object — Treaty benefits claim block. Optional.
        - `is_eligible` boolean — Whether the entity is claiming reduced US withholding under a tax treaty. If `false` or omitted, the rest of the treaty block is ignored and no W-8 form is generated.
        - `country` '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' | 'YE' | 'YT' | 'ZA' | 'ZM' | 'ZW' — Entity's country of tax residence whose treaty with the US is being invoked (ISO 3166-1 alpha-2). Required when `is_eligible = true`.
        - `residence_certification` boolean — Entity's on-form attestation that it is a tax resident of `country`. Must be `true` to claim treaty benefits. Required when `is_eligible = true`.
        - `income_type` 'royalties_other' | 'business_profits' — Category of US-source income the claim applies to: `business_profits` covers trading gains and similar active income; `royalties_other` covers royalties and other passive income. Required when `is_eligible = true`. Accepted string tokens listed in enum; legacy numeric values still accepted for backward compatibility.
        - `withholding_rate` string — Reduced rate granted by the treaty article, as a string percentage (e.g. "0", "10", "15"). Required when `is_eligible = true`.
        - `article_paragraph` string — Treaty article and paragraph authorizing the rate (e.g. "Article 7, paragraph 1"). Free text but should match the actual treaty section. Required when `is_eligible = true`.
        - `additional_conditions` boolean — Whether the entity asserts that extra conditions in the treaty article are met. Send `true` only if the entity has affirmatively confirmed. Required when `is_eligible = true`.
        - `requirements_certification` boolean — Entity's on-form attestation that it derives the relevant income and meets all qualifying tests of the treaty provision. Must be `true` when an entity is claiming treaty benefits in order to generate a W-8 form. Required when `is_eligible = true`.
        - `limitation_on_benefits` 'government' | 'tax_exempt_pension' | 'other_tax_exempt_organization' | 'publicly_traded_corporation' | 'subsidiary' | 'company_meets_erosion_test' | 'company_meets_derivative_test' | 'company_meets_business_test' | 'favorable_determination' | 'no_lob_article' | 'other_article_paragraph' — Which Limitation on Benefits (LOB) clause the entity qualifies under. Required when `is_eligible = true`. Accepted string tokens listed in enum; legacy numeric values still accepted for backward compatibility.
        - `limitation_on_benefits_other` string — Free-text describing the article and paragraph the entity is relying on. Required when (and only when) `limitation_on_benefits = other_article_paragraph`.
    - `mailing_address` object — Root-level object on both customer and entity payloads (form-agnostic; also reused by W-9). Send only when the participant's mailing address differs from their permanent (W-8BEN) or incorporation (W-8BEN-E) address.
      - `address_one` string — Primary street line of the mailing address. Required when the object is present.
      - `address_two` string — Secondary street line (unit, suite, etc.). Optional.
      - `city` string — City of the mailing address. Required when the object is present.
      - `state` string — State, province, or region of the mailing address. Optional.
      - `postal_code` string — Postal or ZIP code of the mailing address. Required when the object is present.
      - `country` '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' | 'YE' | 'YT' | 'ZA' | 'ZM' | 'ZW' — Country of the mailing address (ISO 3166-1 alpha-2). Required when the object is present.
    - `merchant_category_code` string — ISO 18245 four-digit Merchant Category Code (MCC) that identifies the business activity of the entity. Accepted on entity create/update; zerohash derives `merchant_category_code_category` and `merchant_category_code_classification` from this value.
    - `merchant_category_code_category` string — Human-readable category derived by zerohash from `merchant_category_code`. Returned in responses only; not accepted as input.
    - `merchant_category_code_classification` 'transferable' | 'nontransferable' | 'food_vendor' — Classification derived by zerohash from `merchant_category_code`, used to determine how the merchant is treated for downstream payment flows. Returned in responses only; not accepted as input.
    - `jurisdiction_code` string — The ISO 3166-2 subdivision code that the entity resides in
    - `control_persons` ControlPersonResponseEntity[]
      - `user_code` string — zerohash identifier for the Control Person(s) (One code returned per person)
      - `name` string — Full name of the control person
      - `email` string — Email address of control person
      - `address_one` string — First line for the control person'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 control person
      - `postal_code` string — Postal, or zip code, of the control person, 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 control person resides in
      - `date_of_birth` string — Birth date of the control person
      - `phone_number` string — The phone number of the control person
      - `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 control person, e.g. `US`.
      - `tax_id` string — The national ID of the control person, 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.
      - `sanction_screening` 'pass' | 'fail' — Result of the control person's sanctions screening. **Allowed values:** - `pass` - Control person passed sanctions screening - `fail` - Control person failed sanctions screening
      - `sanction_screening_timestamp` number — UNIX timestamp (in milliseconds) when the sanctions screening was performed on the control person.
      - `kyc` 'pass' | 'fail' — Whether the control person 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.
      - `control_person` 0 | 1 | 2 | 3 — Designation of what percent of the business the control person controls. **Allowed values:** - `0` - Unknown - `1` - Less than 10% - `2` - Greater than or equal to 10% but less than 25% - `3` - Greater than or equal to 25%
    - `beneficial_owners` BeneficialOwnerResponseEntity[]
      - `user_code` string — zerohash identifier for the Beneficial Owner(s) (One code returned per person)
      - `name` string — Full name of the beneficial owner
      - `email` string — Email address of beneficial owner
      - `address_one` string — First line for the beneficial owner'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 beneficial owner
      - `postal_code` string — Postal, or zip code, of the beneficial owner, 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 beneficial owner resides in
      - `date_of_birth` string — Birth date of the beneficial owner
      - `phone_number` string — The phone number of the beneficial owner
      - `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 beneficial owner, e.g. `US`.
      - `tax_id` string — The national ID of the beneficial owner, 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.
      - `sanction_screening` 'pass' | 'fail' — Result of the beneficial owner's sanctions screening. **Allowed values:** - `pass` - Beneficial owner passed sanctions screening - `fail` - Beneficial owner failed sanctions screening
      - `sanction_screening_timestamp` number — UNIX timestamp (in milliseconds) when the sanctions screening was performed on the beneficial owner.
      - `kyc` 'pass' | 'fail' — Whether the beneficial owner 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.
      - `beneficial_owner` 0 | 1 | 2 — Designation of what percent of the business the beneficial owner owns. **Allowed values:** - `0` - Unknown - `1` - Greater than or equal to 10% but less than 25% - `2` - Greater than or equal to 25%
      - `role` string — The role of the beneficial owner

## 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)