--- updatedAt: 2026-06-02T20:06:00.000Z agentTools: projectIndex: https://docs.zerohash.com/llms.txt --- # Update entity customer **Update an entity customer** affiliated with your platform. _Your platform must be configured for this endpoint before use._ This is a **partial update** β€” send only the fields you want to change. All fields are optional **except** `submitter_email`, which identifies the caller. πŸ’‘ Use the **Examples** dropdown on the request body below to see common update scenarios (tax info, mailing address, adding people, W-8BEN-E, W-9 document generation, W-9 document upload, and more). ### Adding vs. updating associated persons - Sending `control_persons` or `beneficial_owners` here **adds new** persons to the entity β€” it does **not** modify existing ones. - To **update** a person already attached to the entity (Control Person, Beneficial Owner, or Board Member), call `PATCH /participants/entity/{participant_code}/users/{user_code}` (`PatchUserBody`) with that person’s `user_code`. - **Board members** cannot be added or changed here β€” they are only accepted at creation time via `POST /participants/entity/new`. # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "zerohash API", "description": "\n### Authentication\n\nzerohash Uses HMAC SHA-256 verification to ensure the authenticity of API requests, follow instructions by link [https://docs.zerohash.com/reference/api-authentication](https://docs.zerohash.com/reference/api-authentication)\n\nDownload zerohash OpenAPI Schema as JSON\n", "version": "1.7.0" }, "servers": [ { "url": "https://api.cert.zerohash.com", "description": "Certification API server" } ], "x-readme": { "proxy-enabled": false }, "tags": [ { "name": "Entity Participants", "description": "Create and Manage Entity Participants" } ], "paths": { "/participants/entity/{participant_code}": { "patch": { "tags": [ "Entity Participants" ], "summary": "Update entity customer", "description": "**Update an entity customer** affiliated with your platform. _Your platform must be configured for this endpoint before use._\n\nThis is a **partial update** β€” send only the fields you want to change. All fields are optional **except** `submitter_email`, which identifies the caller.\n\nπŸ’‘ Use the **Examples** dropdown on the request body below to see common update scenarios (tax info, mailing address, adding people, W-8BEN-E, W-9 document generation, W-9 document upload, and more).\n\n### Adding vs. updating associated persons\n\n- Sending `control_persons` or `beneficial_owners` here **adds new** persons to the entity β€” it does **not** modify existing ones.\n- To **update** a person already attached to the entity (Control Person, Beneficial Owner, or Board Member), call `PATCH /participants/entity/{participant_code}/users/{user_code}` (`PatchUserBody`) with that person’s `user_code`.\n- **Board members** cannot be added or changed here β€” they are only accepted at creation time via `POST /participants/entity/new`.", "parameters": [ { "$ref": "#/components/parameters/Signature" }, { "$ref": "#/components/parameters/Timestamp" }, { "$ref": "#/components/parameters/ParticipantCodePath" } ], "requestBody": { "description": "Entity fields to update. All fields are optional **except** `submitter_email`; send only what you want to change.\n\nSending `control_persons` / `beneficial_owners` **adds** new associated persons β€” use `PATCH /participants/entity/{participant_code}/users/{user_code}` (`PatchUserBody`) to update existing ones.", "content": { "application/json": { "schema": { "anyOf": [ { "title": "Update tax information", "type": "object", "description": "Update the entity **tax details** and leave everything else unchanged.\n\n- `tax_id` β€” the entity tax identifier.\n- `tax_residence` β€” primary tax residence address (requires `jurisdiction_code`).\n- `additional_tax_residences` β€” for entities with obligations in multiple jurisdictions.\n- `tin_jurisdiction_reason` β€” why the tax jurisdiction differs from the legal one.", "properties": { "submitter_email": { "type": "string", "description": "Email of the person who completed the KYC application and agreed to terms", "example": "test@example.com" }, "tax_id": { "type": "string", "description": "Tax identifier of the business (e.g. EIN in United States)", "example": "000-00-0000" }, "tax_residence": { "type": "object", "description": "Tax residence address for the entity", "required": [ "jurisdiction_code" ], "properties": { "address_one": { "type": "string", "description": "First line of tax residence address" }, "address_two": { "type": "string", "description": "Second line of tax residence address (optional)" }, "city": { "type": "string", "description": "City of tax residence" }, "jurisdiction_code": { "type": "string", "description": "Jurisdiction code in ISO-3166-2 format", "example": "PT-11" }, "postal_code": { "type": "string", "description": "Postal code of tax residence" } } }, "tin_jurisdiction_reason": { "type": "string", "enum": [ "working_abroad", "studying_abroad", "dual_residency", "business_abroad", "real_estate_abroad", "other" ], "description": "Optional. Reason for the tax residence jurisdiction differing from the legal jurisdiction. Defaults to \"unknown\" if not provided.", "example": "working_abroad" }, "additional_tax_residences": { "type": "array", "maxItems": 25, "items": { "$ref": "#/components/schemas/AdditionalTaxResidence" }, "description": "Optional. Additional tax residences when the entity has tax obligations in multiple jurisdictions. Maximum 25 items." } }, "required": [ "submitter_email" ] }, { "title": "Update mailing address", "type": "object", "description": "Update **only** the entity `mailing_address` β€” used when it differs from the permanent / registered address. No other fields are touched.", "properties": { "submitter_email": { "type": "string", "description": "Email of the person who completed the KYC application and agreed to terms", "example": "test@example.com" }, "mailing_address": { "type": "object", "description": "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.", "properties": { "address_one": { "type": "string", "description": "Primary street line of the mailing address. Required when the object is present.", "example": "10 Downing Street" }, "address_two": { "type": "string", "description": "Secondary street line (unit, suite, etc.). Optional.", "example": "Apt 2" }, "city": { "type": "string", "description": "City of the mailing address. Required when the object is present.", "example": "London" }, "state": { "type": "string", "description": "State, province, or region of the mailing address. Optional.", "example": "England" }, "postal_code": { "type": "string", "description": "Postal or ZIP code of the mailing address. Required when the object is present.", "example": "SW1A 2AA" }, "country": { "type": "string", "description": "Country of the mailing address (ISO 3166-1 alpha-2). Required when the object is present.", "example": "GB", "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", "YE", "YT", "ZA", "ZM", "ZW" ] } } } }, "required": [ "submitter_email" ] }, { "title": "Add control person(s)", "type": "object", "description": "**Adds** one or more new control persons to the entity.\n\n> ⚠️ This does **not** modify existing control persons. To edit someone already on the entity, use `PATCH /participants/entity/{participant_code}/users/{user_code}` (`PatchUserBody`).\n\nEach added person must include verification results (`sanction_screening`, `kyc` and their timestamps) and a `control_person` indicator.", "properties": { "submitter_email": { "type": "string", "description": "Email of the person who completed the KYC application and agreed to terms", "example": "test@example.com" }, "control_persons": { "type": "array", "description": "**Control persons to _add_ to the entity.** Supplying this array **adds new** control persons β€” it does **not** modify existing ones. To update a person already attached to the entity, use `PATCH /participants/entity/{participant_code}/users/{user_code}` (`PatchUserBody`) with their `user_code`.\n\nEach added person must include:\n- `control_person` β€” designation of the percent of the business they control (`0` unknown, `1` less than 10%, `2` 10% to under 25%, `3` 25% or more).\n- **Vendor reliance track only:** vendor-produced verification results β€” `kyc`, `kyc_timestamp`, `sanction_screening`, and `sanction_screening_timestamp`.", "items": { "$ref": "#/components/schemas/ControlPersonVariants" } } }, "required": [ "submitter_email" ] }, { "title": "Add beneficial owner(s)", "type": "object", "description": "**Adds** one or more new beneficial owners to the entity.\n\n> ⚠️ This does **not** modify existing beneficial owners. To edit someone already on the entity, use `PATCH /participants/entity/{participant_code}/users/{user_code}` (`PatchUserBody`).\n\nEach added owner must include verification results (`sanction_screening`, `kyc` and their timestamps) and a `beneficial_owner` ownership percentage.", "properties": { "submitter_email": { "type": "string", "description": "Email of the person who completed the KYC application and agreed to terms", "example": "test@example.com" }, "beneficial_owners": { "type": "array", "description": "**Beneficial owners to _add_ to the entity.** Supplying this array **adds new** beneficial owners β€” it does **not** modify existing ones. To update a person already attached to the entity, use `PATCH /participants/entity/{participant_code}/users/{user_code}` (`PatchUserBody`) with their `user_code`.\n\nEach added owner must include:\n- `beneficial_owner` β€” designation of the percent of the business they own (`0` unknown, `1` 10% to under 25%, `2` 25% or more).\n- **Vendor reliance track only:** vendor-produced verification results β€” `kyc`, `kyc_timestamp`, `sanction_screening`, and `sanction_screening_timestamp`.", "items": { "$ref": "#/components/schemas/BeneficialOwnerVariants" } } }, "required": [ "submitter_email" ] }, { "title": "Add control person(s) + beneficial owner(s)", "type": "object", "description": "**Adds** new control persons **and** beneficial owners in a single call. Both collections are **additive** β€” existing associated persons are untouched.\n\n> ⚠️ To update someone already on the entity, use `PATCH /participants/entity/{participant_code}/users/{user_code}` (`PatchUserBody`).", "properties": { "submitter_email": { "type": "string", "description": "Email of the person who completed the KYC application and agreed to terms", "example": "test@example.com" }, "control_persons": { "type": "array", "description": "**Control persons to _add_ to the entity.** Supplying this array **adds new** control persons β€” it does **not** modify existing ones. To update a person already attached to the entity, use `PATCH /participants/entity/{participant_code}/users/{user_code}` (`PatchUserBody`) with their `user_code`.\n\nEach added person must include:\n- `control_person` β€” designation of the percent of the business they control (`0` unknown, `1` less than 10%, `2` 10% to under 25%, `3` 25% or more).\n- **Vendor reliance track only:** vendor-produced verification results β€” `kyc`, `kyc_timestamp`, `sanction_screening`, and `sanction_screening_timestamp`.", "items": { "$ref": "#/components/schemas/ControlPersonVariants" } }, "beneficial_owners": { "type": "array", "description": "**Beneficial owners to _add_ to the entity.** Supplying this array **adds new** beneficial owners β€” it does **not** modify existing ones. To update a person already attached to the entity, use `PATCH /participants/entity/{participant_code}/users/{user_code}` (`PatchUserBody`) with their `user_code`.\n\nEach added owner must include:\n- `beneficial_owner` β€” designation of the percent of the business they own (`0` unknown, `1` 10% to under 25%, `2` 25% or more).\n- **Vendor reliance track only:** vendor-produced verification results β€” `kyc`, `kyc_timestamp`, `sanction_screening`, and `sanction_screening_timestamp`.", "items": { "$ref": "#/components/schemas/BeneficialOwnerVariants" } } }, "required": [ "submitter_email" ] }, { "title": "Add signed agreements", "type": "object", "description": "Record the agreements the entity has signed.\n\n- Each item requires `region` and `signed_timestamp` (milliseconds since Unix epoch); `type` is optional.\n- `region` is one of `worldwide`, `us`, `brazil`, `uk`, `eu`.\n- Per the **EEA tax guidelines**, EU entities record their agreement with `region: \"eu\"` and `type: \"user_agreement\"`.", "properties": { "submitter_email": { "type": "string", "description": "Email of the person who completed the KYC application and agreed to terms", "example": "test@example.com" }, "signed_agreements": { "type": "array", "description": "The agreements signed by the entity. An array of agreement objects with region, type, and timestamp.", "items": { "type": "object", "required": [ "region", "signed_timestamp" ], "properties": { "type": { "type": "string", "enum": [ "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", "virtual_accounts" ], "description": "The type of the agreement signed", "example": "zhllc_user_agreement_v1" }, "region": { "type": "string", "enum": [ "worldwide", "us", "brazil", "uk", "eu" ], "description": "The region for the signed agreement", "example": "us" }, "signed_timestamp": { "type": "number", "description": "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.", "example": 1603378501286 } } } } }, "required": [ "submitter_email" ] }, { "title": "Update W-8BEN-E tax certification (foreign entity)", "type": "object", "description": "Update the **W-8BEN-E** certification for a **foreign (non-US) entity**.\n\n**Claiming a tax treaty benefit?** Set `treaty_claim.is_eligible: true` and provide `country`, `residence_certification`, `requirements_certification`, `income_type`, `withholding_rate`, `article_paragraph`, and `limitation_on_benefits`. Set `is_eligible: false` to skip the treaty block entirely.\n\n**Certification pairing** (per the W-8 implementation guide): send `is_w_form_certified` **with** `w_form_certification`, plus `signature` **with** `signature_timestamp`.\n\n> πŸ“ Field tokens are **lowercase** β€” e.g. `tax_classification: \"corporation\"`, `income_type: \"business_profits\"`.", "properties": { "submitter_email": { "type": "string", "description": "Email of the person who completed the KYC application and agreed to terms", "example": "test@example.com" }, "w8_ben_e": { "type": "object", "description": "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.", "properties": { "tax_classification": { "type": "string", "enum": [ "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" ], "description": "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.", "example": "corporation" }, "ftin": { "type": "string", "description": "Foreign tax identification number issued by the entity's country of tax residence. Required unless `ftin_required = false`.", "example": "DE123456789" }, "ftin_required": { "type": "boolean", "description": "Whether the entity's country legally issues an FTIN. Required whenever the sub-object is present.", "example": true }, "reference_numbers": { "type": "string", "description": "Optional free-text reference numbers for the platform to connect the tax form to a specific account or financial record.", "example": "REF-002" }, "treaty_claim": { "type": "object", "description": "Treaty benefits claim block. Optional.", "properties": { "is_eligible": { "type": "boolean", "description": "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.", "example": true }, "country": { "type": "string", "description": "Entity's country of tax residence whose treaty with the US is being invoked (ISO 3166-1 alpha-2). Required when `is_eligible = true`.", "example": "DE", "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", "YE", "YT", "ZA", "ZM", "ZW" ] }, "residence_certification": { "type": "boolean", "description": "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`.", "example": true }, "income_type": { "type": "string", "enum": [ "royalties_other", "business_profits" ], "description": "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.", "example": "business_profits" }, "withholding_rate": { "type": "string", "description": "Reduced rate granted by the treaty article, as a string percentage (e.g. \"0\", \"10\", \"15\"). Required when `is_eligible = true`.", "example": "0" }, "article_paragraph": { "type": "string", "description": "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`.", "example": "Article 7" }, "additional_conditions": { "type": "boolean", "description": "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`.", "example": false }, "requirements_certification": { "type": "boolean", "description": "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`.", "example": true }, "limitation_on_benefits": { "type": "string", "enum": [ "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" ], "description": "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.", "example": "publicly_traded_corporation" }, "limitation_on_benefits_other": { "type": "string", "description": "Free-text describing the article and paragraph the entity is relying on. Required when (and only when) `limitation_on_benefits = other_article_paragraph`.", "example": "" } } } } }, "is_w_form_certified": { "type": "boolean", "description": "Indicates whether the entity is W-Form certified, required for entities onboarded to a US platform.\n\n - When `true`, the entity can be onboarded without restriction, so long as other mandatory fields are provided at time of onboarding.\n - When `false`, the entity is restricted and ineligible to transact on the platform.", "example": true }, "w_form_certification": { "type": "number", "description": "W form certification unix timestamp", "example": 1667504636159 }, "signature": { "type": "string", "description": "This field is used to capture the customer Entity `entity_name` as used on the W-form.", "example": "signature_data" }, "signature_timestamp": { "type": "number", "description": "This field captures the timestamp at which the user signed their W-form, used in conjunction with the `signature` field.", "example": 1667504636159 } }, "required": [ "submitter_email" ] }, { "title": "Update W-9 tax certification β€” document generation (US entity)", "type": "object", "description": "API-driven **W-9** for a **US entity** β€” the counterpart to W-8BEN-E for foreign entities. zerohash **generates and manages** the certified W-9 form from the fields you submit β€” **no document is uploaded** β€” so **all** of these fields must be provided at onboarding. Per the W-9 implementation guide:\n\n- Send `is_w_form_certified: true` **with** `w_form_certification` (the millisecond timestamp at which the entity certified), plus `signature` (the `entity_name` as used on the W-form) **with** `signature_timestamp`.\n- `is_not_subject_backup_withholding: true` is a **positive attestation** that the entity is not subject to backup withholding; set `false` if the entity **is** subject.\n- `payee_exemption` and `fatca_reporting_exemption` are codes or `\"NONE\"`.\n- `b_notice_receipt` flags an IRS B-Notice; `dba_name` is the trade name when different from the legal name.\n\nSee the [W-9 implementation guide](https://docs.zerohash.com/docs/w-9-implementation-guide).", "properties": { "submitter_email": { "type": "string", "description": "Email of the person who completed the KYC application and agreed to terms", "example": "test@example.com" }, "is_w_form_certified": { "type": "boolean", "description": "Indicates whether the entity is W-Form certified, required for entities onboarded to a US platform.\n\n - When `true`, the entity can be onboarded without restriction, so long as other mandatory fields are provided at time of onboarding.\n - When `false`, the entity is restricted and ineligible to transact on the platform.", "example": true }, "w_form_certification": { "type": "number", "description": "W form certification unix timestamp", "example": 1667504636159 }, "signature": { "type": "string", "description": "This field is used to capture the customer Entity `entity_name` as used on the W-form.", "example": "signature_data" }, "signature_timestamp": { "type": "number", "description": "This field captures the timestamp at which the user signed their W-form, used in conjunction with the `signature` field.", "example": 1667504636159 }, "is_not_subject_backup_withholding": { "type": "boolean", "description": "Backup withholding attestation flag. Required for customers onboarded to a US platform.\n - If the participant confirms they are **not** subject to backup withholding, this field should be set to `true`.\n - If the participant **is** subject to backup withholding, this field should be set to `false`.\nThis acts as a positive attestation that the participant confirms they are not subject to backup withholding.", "example": false }, "b_notice_receipt": { "type": "boolean", "description": "Boolean flag indicating notice receipt status", "example": true }, "payee_exemption": { "type": "string", "enum": [ "1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "NONE" ], "description": "Payee exemption field that captures enum values for any applicable payee exemption codes 1 - 13, or NONE if no exemption applies. Required for entities onboarded to a US platform.", "example": "NONE" }, "fatca_reporting_exemption": { "type": "string", "enum": [ "A", "B", "C", "D", "E", "F", "G", "H", "I", "J", "K", "L", "M", "NONE" ], "description": "FATCA reporting exemption code (A-M or NONE). Per the IRS W-9, FATCA exemption codes are letters A through M; use NONE if no exemption applies.", "example": "NONE" }, "dba_name": { "type": "string", "description": "Doing Business As (DBA) name of the entity", "example": "ABC Trading Co" } }, "required": [ "submitter_email" ] }, { "title": "Update W-9 tax certification β€” document upload (US entity)", "type": "object", "description": "Platform-collected **W-9** for a **US entity**. Your platform already collects the certified W-9 externally and **uploads the document** to zerohash via [`POST /participants/documents`](https://docs.zerohash.com/reference/post_participants-documents) with `document_type: \"form_w9\"`. You **still** send the same tax-metadata fields on this PATCH so the entity record reflects the certification. Per the W-9 implementation guide:\n\n- Send `is_w_form_certified: true` **with** `w_form_certification` (the millisecond timestamp of certification), plus `signature` (the `entity_name` as used on the W-form) **with** `signature_timestamp`.\n- `is_not_subject_backup_withholding: true` is a **positive attestation** that the entity is not subject to backup withholding; set `false` if the entity **is** subject.\n- `payee_exemption` and `fatca_reporting_exemption` are codes or `\"NONE\"`.\n- `b_notice_receipt` flags an IRS B-Notice; `dba_name` is the trade name when different from the legal name.\n\nSee the [W-9 implementation guide](https://docs.zerohash.com/docs/w-9-implementation-guide).", "properties": { "submitter_email": { "type": "string", "description": "Email of the person who completed the KYC application and agreed to terms", "example": "test@example.com" }, "is_w_form_certified": { "type": "boolean", "description": "Indicates whether the entity is W-Form certified, required for entities onboarded to a US platform.\n\n - When `true`, the entity can be onboarded without restriction, so long as other mandatory fields are provided at time of onboarding.\n - When `false`, the entity is restricted and ineligible to transact on the platform.", "example": true }, "w_form_certification": { "type": "number", "description": "W form certification unix timestamp", "example": 1667504636159 }, "signature": { "type": "string", "description": "This field is used to capture the customer Entity `entity_name` as used on the W-form.", "example": "signature_data" }, "signature_timestamp": { "type": "number", "description": "This field captures the timestamp at which the user signed their W-form, used in conjunction with the `signature` field.", "example": 1667504636159 }, "is_not_subject_backup_withholding": { "type": "boolean", "description": "Backup withholding attestation flag. Required for customers onboarded to a US platform.\n - If the participant confirms they are **not** subject to backup withholding, this field should be set to `true`.\n - If the participant **is** subject to backup withholding, this field should be set to `false`.\nThis acts as a positive attestation that the participant confirms they are not subject to backup withholding.", "example": false }, "b_notice_receipt": { "type": "boolean", "description": "Boolean flag indicating notice receipt status", "example": true }, "payee_exemption": { "type": "string", "enum": [ "1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "NONE" ], "description": "Payee exemption field that captures enum values for any applicable payee exemption codes 1 - 13, or NONE if no exemption applies. Required for entities onboarded to a US platform.", "example": "NONE" }, "fatca_reporting_exemption": { "type": "string", "enum": [ "A", "B", "C", "D", "E", "F", "G", "H", "I", "J", "K", "L", "M", "NONE" ], "description": "FATCA reporting exemption code (A-M or NONE). Per the IRS W-9, FATCA exemption codes are letters A through M; use NONE if no exemption applies.", "example": "NONE" }, "dba_name": { "type": "string", "description": "Doing Business As (DBA) name of the entity", "example": "ABC Trading Co" } }, "required": [ "submitter_email" ] }, { "title": "All accepted fields (reference)", "type": "object", "description": "Every field accepted by the entity PATCH endpoint β€” a **documentation superset** showing the full updatable surface.\n\n> ⚠️ This is **not** a single valid request: some fields are mutually exclusive, and `control_persons` / `beneficial_owners` here **add** new persons.\n\n- To update an existing associated person, use `PATCH /participants/entity/{participant_code}/users/{user_code}` (`PatchUserBody`).\n- `board_members` and `platform_updated_at` are **not** accepted on this endpoint.", "properties": { "entity_name": { "type": "string", "description": "Name of the business", "example": "Entity Name" }, "legal_name": { "type": "string", "description": "Registered legal name of the entity. This should not be a DBA or DBA equivalent", "example": "Legal Name" }, "contact_number": { "type": "string", "description": "Phone number of the business", "example": "+15557778888" }, "website": { "type": "string", "description": "Business website", "example": "company.com" }, "date_established": { "type": "string", "description": "Date the business was established. This should reflect government registration for the entity in the format `YYYY-MM-DD`", "example": "1985-09-02" }, "entity_type": { "type": "string", "enum": [ "corporation", "llc", "partnership", "sole_proprietorship", "other", "non_profit", "llc_c", "llc_s", "llc_p", "s_corporation", "c_corporation", "trust_estate", "trust" ], "description": "The type of business that is onboarding, must be one of the supported", "example": "llc" }, "address_one": { "type": "string", "description": "First line for the business's address.\n\nNotes:\n- The regular maximum length is 80 characters.\n- If the platform is on the vendor reliance track, the maximum length increases to 200 characters.\n- PO Box addresses are not accepted.", "example": "123 Main St." }, "address_two": { "type": "string", "description": "Extra information, like an apartment or suite number.\n\nNotes:\n- The regular maximum length is 50 characters.\n- If the platform is on the vendor reliance track, the maximum length increases to 200 characters.\n- PO Box addresses are not accepted.", "example": "Suite 1000" }, "city": { "type": "string", "description": "The city customer resides in", "example": "Chicago" }, "postal_code": { "type": "string", "description": "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", "example": "12345" }, "tax_id": { "type": "string", "description": "Tax identifier of the business (e.g. EIN in United States)", "example": "000-00-0000" }, "id_issuing_authority": { "type": "string", "description": "ISO-3166-1_A2 country code that issued the tax identifier (e.g. β€œUS”)", "example": "US" }, "risk_rating": { "type": "string", "enum": [ "low", "medium", "high" ], "description": "Risk assessed by the platform's vendor", "example": "low" }, "onboarding_profile": { "type": "string", "enum": [ "kyc_track", "shopper", "originator_entity", "payouts_payor_ultimate", "payouts_beneficiary" ], "description": "Onboarding profile used to determine the entity's KYC track. Optional. Defaults to 'kyc_track' when omitted.", "example": "kyc_track" }, "sanction_screening": { "type": "string", "enum": [ "pass", "fail" ], "description": "Result of the business sanctions screen\t", "example": "pass" }, "sanction_screening_timestamp": { "type": "number", "description": "The time the sanctions screen was done\t", "example": 1603378501286 }, "self_certification_timestamp": { "type": "number", "description": "The UNIX timestamp (in milliseconds) when the participant completed self-certification for DAC8 compliance. Mandatory for participants that are based in Europe.", "example": 1667504636159 }, "signed_timestamp": { "type": "number", "description": "The time at which the business accepted zerohash services agreements", "example": 1603378501286 }, "signed_agreements": { "type": "array", "description": "The agreements signed by the entity. An array of agreement objects with region, type, and timestamp.", "items": { "type": "object", "required": [ "region", "signed_timestamp" ], "properties": { "type": { "type": "string", "enum": [ "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", "virtual_accounts" ], "description": "The type of the agreement signed", "example": "zhllc_user_agreement_v1" }, "region": { "type": "string", "enum": [ "worldwide", "us", "brazil", "uk", "eu" ], "description": "The region for the signed agreement", "example": "us" }, "signed_timestamp": { "type": "number", "description": "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.", "example": 1603378501286 } } } }, "expected_annual_volume": { "type": "string", "enum": [ "unknown", "under_100k", "between_100k_and_250k", "between_250k_and_500k", "over_500k" ], "description": "Expected annual transaction volume for the entity. Required for EU entities.", "example": "over_500k" }, "submitter_email": { "type": "string", "description": "Email of the person who completed the KYC application and agreed to terms", "example": "test@example.com" }, "submitter_first_name": { "type": "string", "description": "Submitter first name", "example": "Jon" }, "submitter_last_name": { "type": "string", "description": "Submitter last name", "example": "Doe" }, "submitter_title": { "type": "string", "description": "The title or honorific of the individual submitting the form (e.g., Mr., Ms., Dr.).", "example": "Mr." }, "incorporation_address": { "type": "object", "description": "Full address where the entity is incorporated", "required": [ "jurisdiction_code" ], "properties": { "address_one": { "type": "string", "description": "First line of incorporation address" }, "address_two": { "type": "string", "description": "Second line of incorporation address (optional)" }, "city": { "type": "string", "description": "City of incorporation" }, "jurisdiction_code": { "type": "string", "description": "Jurisdiction code in ISO-3166-2 format", "example": "IT-25" }, "postal_code": { "type": "string", "description": "Postal code of incorporation address" } } }, "tax_residence": { "type": "object", "description": "Tax residence address for the entity", "required": [ "jurisdiction_code" ], "properties": { "address_one": { "type": "string", "description": "First line of tax residence address" }, "address_two": { "type": "string", "description": "Second line of tax residence address (optional)" }, "city": { "type": "string", "description": "City of tax residence" }, "jurisdiction_code": { "type": "string", "description": "Jurisdiction code in ISO-3166-2 format", "example": "PT-11" }, "postal_code": { "type": "string", "description": "Postal code of tax residence" } } }, "tin_jurisdiction_reason": { "type": "string", "enum": [ "working_abroad", "studying_abroad", "dual_residency", "business_abroad", "real_estate_abroad", "other" ], "description": "Optional. Reason for the tax residence jurisdiction differing from the legal jurisdiction. Defaults to \"unknown\" if not provided.", "example": "working_abroad" }, "tin_jurisdiction_other": { "type": "string", "description": "Optional. Free text explanation when `tin_jurisdiction_reason` is `other`", "example": "Jurisdiction does not issue TINs" }, "b_notice_receipt": { "type": "boolean", "description": "Boolean flag indicating notice receipt status", "example": true }, "is_w_form_certified": { "type": "boolean", "description": "Indicates whether the entity is W-Form certified, required for entities onboarded to a US platform.\n\n - When `true`, the entity can be onboarded without restriction, so long as other mandatory fields are provided at time of onboarding.\n - When `false`, the entity is restricted and ineligible to transact on the platform.", "example": true }, "w_form_certification": { "type": "number", "description": "W form certification unix timestamp", "example": 1667504636159 }, "physical_delivery": { "type": "boolean", "description": "Physical delivery flag", "example": false }, "signature": { "type": "string", "description": "This field is used to capture the customer Entity `entity_name` as used on the W-form.", "example": "signature_data" }, "signature_timestamp": { "type": "number", "description": "This field captures the timestamp at which the user signed their W-form, used in conjunction with the `signature` field.", "example": 1667504636159 }, "payee_exemption": { "type": "string", "enum": [ "1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "NONE" ], "description": "Payee exemption field that captures enum values for any applicable payee exemption codes 1 - 13, or NONE if no exemption applies. Required for entities onboarded to a US platform.", "example": "NONE" }, "fatca_reporting_exemption": { "type": "string", "enum": [ "A", "B", "C", "D", "E", "F", "G", "H", "I", "J", "K", "L", "M", "NONE" ], "description": "FATCA reporting exemption code (A-M or NONE). Per the IRS W-9, FATCA exemption codes are letters A through M; use NONE if no exemption applies.", "example": "NONE" }, "is_not_subject_backup_withholding": { "type": "boolean", "description": "Backup withholding attestation flag. Required for customers onboarded to a US platform.\n - If the participant confirms they are **not** subject to backup withholding, this field should be set to `true`.\n - If the participant **is** subject to backup withholding, this field should be set to `false`.\nThis acts as a positive attestation that the participant confirms they are not subject to backup withholding.", "example": false }, "dba_name": { "type": "string", "description": "Doing Business As (DBA) name of the entity", "example": "ABC Trading Co" }, "other_entity_type": { "type": "string", "description": "Other entity type description when entity_type is \"other\"", "example": "Trust" }, "w8_ben_e": { "type": "object", "description": "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.", "properties": { "tax_classification": { "type": "string", "enum": [ "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" ], "description": "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.", "example": "corporation" }, "ftin": { "type": "string", "description": "Foreign tax identification number issued by the entity's country of tax residence. Required unless `ftin_required = false`.", "example": "DE123456789" }, "ftin_required": { "type": "boolean", "description": "Whether the entity's country legally issues an FTIN. Required whenever the sub-object is present.", "example": true }, "reference_numbers": { "type": "string", "description": "Optional free-text reference numbers for the platform to connect the tax form to a specific account or financial record.", "example": "REF-002" }, "treaty_claim": { "type": "object", "description": "Treaty benefits claim block. Optional.", "properties": { "is_eligible": { "type": "boolean", "description": "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.", "example": true }, "country": { "type": "string", "description": "Entity's country of tax residence whose treaty with the US is being invoked (ISO 3166-1 alpha-2). Required when `is_eligible = true`.", "example": "DE", "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", "YE", "YT", "ZA", "ZM", "ZW" ] }, "residence_certification": { "type": "boolean", "description": "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`.", "example": true }, "income_type": { "type": "string", "enum": [ "royalties_other", "business_profits" ], "description": "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.", "example": "business_profits" }, "withholding_rate": { "type": "string", "description": "Reduced rate granted by the treaty article, as a string percentage (e.g. \"0\", \"10\", \"15\"). Required when `is_eligible = true`.", "example": "0" }, "article_paragraph": { "type": "string", "description": "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`.", "example": "Article 7" }, "additional_conditions": { "type": "boolean", "description": "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`.", "example": false }, "requirements_certification": { "type": "boolean", "description": "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`.", "example": true }, "limitation_on_benefits": { "type": "string", "enum": [ "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" ], "description": "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.", "example": "publicly_traded_corporation" }, "limitation_on_benefits_other": { "type": "string", "description": "Free-text describing the article and paragraph the entity is relying on. Required when (and only when) `limitation_on_benefits = other_article_paragraph`.", "example": "" } } } } }, "mailing_address": { "type": "object", "description": "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.", "properties": { "address_one": { "type": "string", "description": "Primary street line of the mailing address. Required when the object is present.", "example": "10 Downing Street" }, "address_two": { "type": "string", "description": "Secondary street line (unit, suite, etc.). Optional.", "example": "Apt 2" }, "city": { "type": "string", "description": "City of the mailing address. Required when the object is present.", "example": "London" }, "state": { "type": "string", "description": "State, province, or region of the mailing address. Optional.", "example": "England" }, "postal_code": { "type": "string", "description": "Postal or ZIP code of the mailing address. Required when the object is present.", "example": "SW1A 2AA" }, "country": { "type": "string", "description": "Country of the mailing address (ISO 3166-1 alpha-2). Required when the object is present.", "example": "GB", "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", "YE", "YT", "ZA", "ZM", "ZW" ] } } }, "merchant_category_code": { "type": "string", "description": "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.", "example": "5411" }, "jurisdiction_code": { "type": "string", "example": "US-IL", "description": "The ISO 3166-2 subdivision code that the entity resides in" }, "control_persons": { "type": "array", "description": "**Control persons to _add_ to the entity.** Supplying this array **adds new** control persons β€” it does **not** modify existing ones. To update a person already attached to the entity, use `PATCH /participants/entity/{participant_code}/users/{user_code}` (`PatchUserBody`) with their `user_code`.\n\nEach added person must include:\n- `control_person` β€” designation of the percent of the business they control (`0` unknown, `1` less than 10%, `2` 10% to under 25%, `3` 25% or more).\n- **Vendor reliance track only:** vendor-produced verification results β€” `kyc`, `kyc_timestamp`, `sanction_screening`, and `sanction_screening_timestamp`.", "items": { "$ref": "#/components/schemas/ControlPersonVariants" } }, "beneficial_owners": { "type": "array", "description": "**Beneficial owners to _add_ to the entity.** Supplying this array **adds new** beneficial owners β€” it does **not** modify existing ones. To update a person already attached to the entity, use `PATCH /participants/entity/{participant_code}/users/{user_code}` (`PatchUserBody`) with their `user_code`.\n\nEach added owner must include:\n- `beneficial_owner` β€” designation of the percent of the business they own (`0` unknown, `1` 10% to under 25%, `2` 25% or more).\n- **Vendor reliance track only:** vendor-produced verification results β€” `kyc`, `kyc_timestamp`, `sanction_screening`, and `sanction_screening_timestamp`.", "items": { "$ref": "#/components/schemas/BeneficialOwnerVariants" } } }, "required": [ "submitter_email" ] } ] }, "examples": { "update_tax_info": { "summary": "Update tax information", "description": "Update the entity **tax details** and leave everything else unchanged.\n\n- `tax_id` β€” the entity tax identifier.\n- `tax_residence` β€” primary tax residence address (requires `jurisdiction_code`).\n- `additional_tax_residences` β€” for entities with obligations in multiple jurisdictions.\n- `tin_jurisdiction_reason` β€” why the tax jurisdiction differs from the legal one.", "value": { "submitter_email": "submitter@example.com", "tax_id": "98-7654321", "tax_residence": { "address_one": "123 Main St.", "city": "Chicago", "postal_code": "60601", "jurisdiction_code": "US-IL" }, "tin_jurisdiction_reason": "working_abroad", "additional_tax_residences": [ { "jurisdiction_code": "GB-ENG", "tax_id": "GB123456789" } ] } }, "update_mailing_address": { "summary": "Update mailing address", "description": "Update **only** the entity `mailing_address` β€” used when it differs from the permanent / registered address. No other fields are touched.", "value": { "submitter_email": "submitter@example.com", "mailing_address": { "address_one": "10 Downing Street", "address_two": "Suite 200", "city": "London", "state": "England", "postal_code": "SW1A 2AA", "country": "GB" } } }, "add_control_persons": { "summary": "Add control person(s)", "description": "**Adds** one or more new control persons to the entity.\n\n> ⚠️ This does **not** modify existing control persons. To edit someone already on the entity, use `PATCH /participants/entity/{participant_code}/users/{user_code}` (`PatchUserBody`).\n\nEach added person must include verification results (`sanction_screening`, `kyc` and their timestamps) and a `control_person` indicator.", "value": { "submitter_email": "submitter@example.com", "control_persons": [ { "name": "Maria Garcia", "email": "maria.garcia@example.com", "address_one": "500 Lake Shore Dr.", "city": "Chicago", "postal_code": "60611", "jurisdiction_code": "US-IL", "citizenship_code": "US", "date_of_birth": "1979-03-22", "tax_id": "123456789", "control_person": 1, "sanction_screening": "pass", "sanction_screening_timestamp": 1603378501286, "kyc": "pass", "kyc_timestamp": 1603378501286 } ] } }, "add_beneficial_owners": { "summary": "Add beneficial owner(s)", "description": "**Adds** one or more new beneficial owners to the entity.\n\n> ⚠️ This does **not** modify existing beneficial owners. To edit someone already on the entity, use `PATCH /participants/entity/{participant_code}/users/{user_code}` (`PatchUserBody`).\n\nEach added owner must include verification results (`sanction_screening`, `kyc` and their timestamps) and a `beneficial_owner` ownership percentage.", "value": { "submitter_email": "submitter@example.com", "beneficial_owners": [ { "name": "David Lee", "email": "david.lee@example.com", "address_one": "77 River North Point", "city": "Chicago", "postal_code": "60654", "jurisdiction_code": "US-IL", "citizenship_code": "US", "date_of_birth": "1972-11-08", "tax_id": "123456789", "beneficial_owner": 30, "sanction_screening": "pass", "sanction_screening_timestamp": 1603378501286, "kyc": "pass", "kyc_timestamp": 1603378501286 } ] } }, "add_control_persons_and_beneficial_owners": { "summary": "Add control person(s) + beneficial owner(s)", "description": "**Adds** new control persons **and** beneficial owners in a single call. Both collections are **additive** β€” existing associated persons are untouched.\n\n> ⚠️ To update someone already on the entity, use `PATCH /participants/entity/{participant_code}/users/{user_code}` (`PatchUserBody`).", "value": { "submitter_email": "submitter@example.com", "control_persons": [ { "name": "Maria Garcia", "email": "maria.garcia@example.com", "address_one": "500 Lake Shore Dr.", "city": "Chicago", "postal_code": "60611", "jurisdiction_code": "US-IL", "citizenship_code": "US", "date_of_birth": "1979-03-22", "tax_id": "123456789", "control_person": 1, "sanction_screening": "pass", "sanction_screening_timestamp": 1603378501286, "kyc": "pass", "kyc_timestamp": 1603378501286 } ], "beneficial_owners": [ { "name": "David Lee", "email": "david.lee@example.com", "address_one": "77 River North Point", "city": "Chicago", "postal_code": "60654", "jurisdiction_code": "US-IL", "citizenship_code": "US", "date_of_birth": "1972-11-08", "tax_id": "123456789", "beneficial_owner": 30, "sanction_screening": "pass", "sanction_screening_timestamp": 1603378501286, "kyc": "pass", "kyc_timestamp": 1603378501286 } ] } }, "add_signed_agreements": { "summary": "Add signed agreements", "description": "Record the agreements the entity has signed.\n\n- Each item requires `region` and `signed_timestamp` (milliseconds since Unix epoch); `type` is optional.\n- `region` is one of `worldwide`, `us`, `brazil`, `uk`, `eu`.\n- Per the **EEA tax guidelines**, EU entities record their agreement with `region: \"eu\"` and `type: \"user_agreement\"`.", "value": { "submitter_email": "submitter@example.com", "signed_agreements": [ { "region": "us", "type": "user_agreement", "signed_timestamp": 1603378501286 }, { "region": "eu", "type": "user_agreement", "signed_timestamp": 1603378501286 } ] } }, "update_w8_ben_e": { "summary": "Update W-8BEN-E tax certification (foreign entity)", "description": "Update the **W-8BEN-E** certification for a **foreign (non-US) entity**.\n\n**Claiming a tax treaty benefit?** Set `treaty_claim.is_eligible: true` and provide `country`, `residence_certification`, `requirements_certification`, `income_type`, `withholding_rate`, `article_paragraph`, and `limitation_on_benefits`. Set `is_eligible: false` to skip the treaty block entirely.\n\n**Certification pairing** (per the W-8 implementation guide): send `is_w_form_certified` **with** `w_form_certification`, plus `signature` **with** `signature_timestamp`.\n\n> πŸ“ Field tokens are **lowercase** β€” e.g. `tax_classification: \"corporation\"`, `income_type: \"business_profits\"`.", "value": { "submitter_email": "submitter@example.com", "w8_ben_e": { "tax_classification": "corporation", "ftin": "DE123456789", "ftin_required": true, "reference_numbers": "REF-002", "treaty_claim": { "is_eligible": true, "country": "DE", "residence_certification": true, "requirements_certification": true, "income_type": "business_profits", "withholding_rate": "0", "article_paragraph": "Article 7", "limitation_on_benefits": "publicly_traded_corporation", "additional_conditions": false } }, "is_w_form_certified": true, "w_form_certification": 1603378501286, "signature": "Acme Holdings Inc.", "signature_timestamp": 1603378501286 } }, "update_w9_document_generation": { "summary": "Update W-9 tax certification β€” document generation (US entity)", "description": "API-driven **W-9** for a **US entity** β€” the counterpart to W-8BEN-E for foreign entities. zerohash **generates and manages** the certified W-9 form from the fields you submit β€” **no document is uploaded** β€” so **all** of these fields must be provided at onboarding. Per the W-9 implementation guide:\n\n- Send `is_w_form_certified: true` **with** `w_form_certification` (the millisecond timestamp at which the entity certified), plus `signature` (the `entity_name` as used on the W-form) **with** `signature_timestamp`.\n- `is_not_subject_backup_withholding: true` is a **positive attestation** that the entity is not subject to backup withholding; set `false` if the entity **is** subject.\n- `payee_exemption` and `fatca_reporting_exemption` are codes or `\"NONE\"`.\n- `b_notice_receipt` flags an IRS B-Notice; `dba_name` is the trade name when different from the legal name.\n\nSee the [W-9 implementation guide](https://docs.zerohash.com/docs/w-9-implementation-guide).", "value": { "submitter_email": "submitter@example.com", "is_w_form_certified": true, "w_form_certification": 1603378501286, "signature": "Acme Holdings Inc.", "signature_timestamp": 1603378501286, "is_not_subject_backup_withholding": true, "b_notice_receipt": false, "payee_exemption": "NONE", "fatca_reporting_exemption": "NONE", "dba_name": "Acme Trading Co" } }, "update_w9_document_upload": { "summary": "Update W-9 tax certification β€” document upload (US entity)", "description": "Platform-collected **W-9** for a **US entity**. Your platform already collects the certified W-9 externally and **uploads the document** to zerohash via [`POST /participants/documents`](https://docs.zerohash.com/reference/post_participants-documents) with `document_type: \"form_w9\"`. You **still** send the same tax-metadata fields on this PATCH so the entity record reflects the certification. Per the W-9 implementation guide:\n\n- Send `is_w_form_certified: true` **with** `w_form_certification` (the millisecond timestamp of certification), plus `signature` (the `entity_name` as used on the W-form) **with** `signature_timestamp`.\n- `is_not_subject_backup_withholding: true` is a **positive attestation** that the entity is not subject to backup withholding; set `false` if the entity **is** subject.\n- `payee_exemption` and `fatca_reporting_exemption` are codes or `\"NONE\"`.\n- `b_notice_receipt` flags an IRS B-Notice; `dba_name` is the trade name when different from the legal name.\n\nSee the [W-9 implementation guide](https://docs.zerohash.com/docs/w-9-implementation-guide).", "value": { "submitter_email": "submitter@example.com", "is_w_form_certified": true, "w_form_certification": 1603378501286, "signature": "Acme Holdings Inc.", "signature_timestamp": 1603378501286, "is_not_subject_backup_withholding": true, "b_notice_receipt": false, "payee_exemption": "NONE", "fatca_reporting_exemption": "NONE", "dba_name": "Acme Trading Co" } }, "all_accepted_fields": { "summary": "All accepted fields (reference)", "description": "Every field accepted by the entity PATCH endpoint β€” a **documentation superset** showing the full updatable surface.\n\n> ⚠️ This is **not** a single valid request: some fields are mutually exclusive, and `control_persons` / `beneficial_owners` here **add** new persons.\n\n- To update an existing associated person, use `PATCH /participants/entity/{participant_code}/users/{user_code}` (`PatchUserBody`).\n- `board_members` and `platform_updated_at` are **not** accepted on this endpoint.", "value": { "entity_name": "Entity Name", "legal_name": "Legal Name", "contact_number": "+15557778888", "website": "company.com", "date_established": "1985-09-02", "entity_type": "llc", "address_one": "123 Main St.", "address_two": "Suite 1000", "city": "Chicago", "postal_code": "12345", "tax_id": "000-00-0000", "id_issuing_authority": "US", "risk_rating": "low", "onboarding_profile": "kyc_track", "sanction_screening": "pass", "sanction_screening_timestamp": 1603378501286, "self_certification_timestamp": 1667504636159, "signed_timestamp": 1603378501286, "signed_agreements": [ { "type": "zhllc_user_agreement_v1", "region": "us", "signed_timestamp": 1603378501286 } ], "expected_annual_volume": "over_500k", "submitter_email": "submitter@example.com", "submitter_first_name": "Jon", "submitter_last_name": "Doe", "submitter_title": "Mr.", "incorporation_address": { "jurisdiction_code": "IT-25" }, "tax_residence": { "jurisdiction_code": "PT-11" }, "tin_jurisdiction_reason": "working_abroad", "tin_jurisdiction_other": "Jurisdiction does not issue TINs", "b_notice_receipt": true, "is_w_form_certified": true, "w_form_certification": 1667504636159, "physical_delivery": false, "signature": "signature_data", "signature_timestamp": 1667504636159, "payee_exemption": "NONE", "fatca_reporting_exemption": "NONE", "is_not_subject_backup_withholding": false, "dba_name": "ABC Trading Co", "other_entity_type": "Trust", "w8_ben_e": { "tax_classification": "corporation", "ftin": "DE123456789", "ftin_required": true, "reference_numbers": "REF-002", "treaty_claim": { "is_eligible": true, "country": "DE", "residence_certification": true, "income_type": "business_profits", "withholding_rate": "0", "article_paragraph": "Article 7", "additional_conditions": false, "requirements_certification": true, "limitation_on_benefits": "publicly_traded_corporation", "limitation_on_benefits_other": "" } }, "mailing_address": { "address_one": "10 Downing Street", "address_two": "Apt 2", "city": "London", "state": "England", "postal_code": "SW1A 2AA", "country": "GB" }, "merchant_category_code": "5411", "jurisdiction_code": "US-IL", "control_persons": [ { "name": "Maria Garcia", "email": "maria.garcia@example.com", "address_one": "500 Lake Shore Dr.", "city": "Chicago", "postal_code": "60611", "jurisdiction_code": "US-IL", "citizenship_code": "US", "date_of_birth": "1979-03-22", "tax_id": "123456789", "control_person": 1, "sanction_screening": "pass", "sanction_screening_timestamp": 1603378501286, "kyc": "pass", "kyc_timestamp": 1603378501286 } ], "beneficial_owners": [ { "name": "David Lee", "email": "david.lee@example.com", "address_one": "77 River North Point", "city": "Chicago", "postal_code": "60654", "jurisdiction_code": "US-IL", "citizenship_code": "US", "date_of_birth": "1972-11-08", "tax_id": "123456789", "beneficial_owner": 30, "sanction_screening": "pass", "sanction_screening_timestamp": 1603378501286, "kyc": "pass", "kyc_timestamp": 1603378501286 } ] } } } } } }, "responses": { "200": { "description": "Successfully updated entity participant. Returns the updated resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchEntityResponse" }, "example": { "message": { "entity_name": "Entity Name", "legal_name": "Legal Name", "contact_number": "+15557778888", "website": "company.com", "date_established": "1985-09-02", "entity_type": "llc", "address_one": "123 Main St.", "address_two": "Suite 1000", "city": "Chicago", "postal_code": "12345", "tax_id": "000-00-0000", "id_issuing_authority": "US", "risk_rating": "low", "onboarding_profile": "kyc_track", "sanction_screening": "pass", "sanction_screening_timestamp": 1603378501286, "self_certification_timestamp": 1667504636159, "signed_timestamp": 1603378501286, "signed_agreements": [ { "type": "zhllc_user_agreement_v1", "region": "us", "signed_timestamp": 1603378501286 } ], "expected_annual_volume": "over_500k", "submitter_email": "test@example.com", "incorporation_address": { "jurisdiction_code": "IT-25" }, "tax_residence": { "jurisdiction_code": "PT-11" }, "tin_jurisdiction_reason": "working_abroad", "b_notice_receipt": true, "is_w_form_certified": true, "w_form_certification": 1667504636159, "physical_delivery": false, "signature": "signature_data", "signature_timestamp": 1667504636159, "payee_exemption": "NONE", "fatca_reporting_exemption": "NONE", "is_not_subject_backup_withholding": false, "dba_name": "ABC Trading Co", "other_entity_type": "Trust", "w8_ben_e": { "tax_classification": "corporation", "ftin": "DE123456789", "ftin_required": true, "reference_numbers": "REF-002", "treaty_claim": { "is_eligible": true, "country": "DE", "residence_certification": true, "income_type": "business_profits", "withholding_rate": "0", "article_paragraph": "Article 7", "additional_conditions": false, "requirements_certification": true, "limitation_on_benefits": "publicly_traded_corporation", "limitation_on_benefits_other": "" } }, "mailing_address": { "address_one": "10 Downing Street", "address_two": "Apt 2", "city": "London", "state": "England", "postal_code": "SW1A 2AA", "country": "GB" }, "merchant_category_code": "5411", "merchant_category_code_category": "Grocery Stores, Supermarkets", "merchant_category_code_classification": "transferable", "jurisdiction_code": "US-IL" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Code400" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Code403" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Code404" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Code500" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Code503" } } } } } } } }, "security": [ { "apiKey": [], "apiPassphrase": [] } ], "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "description": "Your API public key. See the [Authentication guide](https://docs.zerohash.com/reference/api-authentication) for how to obtain keys.", "in": "header", "name": "X-SCX-API-KEY" }, "apiPassphrase": { "type": "apiKey", "description": "The passphrase associated with your API key, set when the key was created.", "in": "header", "name": "X-SCX-PASSPHRASE" } }, "parameters": { "Signature": { "name": "X-SCX-SIGNED", "in": "header", "description": "HMAC-SHA256 signature of the request, base64-encoded. See the [Authentication guide](https://docs.zerohash.com/reference/api-authentication) for the exact signing formula.", "required": true, "schema": { "type": "string" } }, "Timestamp": { "name": "X-SCX-TIMESTAMP", "in": "header", "description": "Current Unix timestamp in seconds. Must be within 60 seconds of server time or the request is rejected.", "required": true, "schema": { "type": "string", "example": "1678901234" } }, "ParticipantCodePath": { "name": "participant_code", "in": "path", "description": "Unique participant identifier. Always 6 uppercase alphanumeric characters.", "required": true, "schema": { "type": "string", "pattern": "^[A-Z0-9]{6}$", "example": "ABCDEF" } } }, "schemas": { "Code400": { "type": "object", "description": "Request was rejected by validation or a downstream service. `errors` is an array of human-readable messages; each entry describes a single validation failure or business-rule violation.", "required": [ "errors" ], "properties": { "errors": { "type": "array", "items": { "type": "string" }, "example": [ "body/amount must be >= 0", "body/asset is required" ] } } }, "Code403": { "type": "object", "description": "Authentication or authorization failed. `error` is always `true`; `message` explains which check failed (missing API key, bad signature, insufficient permission, etc.).", "required": [ "error", "message" ], "properties": { "error": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "This api key does not have write permission to this endpoint" } } }, "Code404": { "type": "object", "description": "The requested resource does not exist or is not visible to the caller.", "required": [ "error" ], "properties": { "error": { "type": "string", "example": "Not Found" } } }, "Code500": { "type": "object", "description": "An unexpected error occurred on the server. The request can be retried after a short delay, but the same inputs may reproduce the error.", "required": [ "error" ], "properties": { "error": { "type": "string", "example": "Internal Server Error" } } }, "Code503": { "type": "object", "description": "A downstream dependency was unavailable, timed out, or returned a retryable error. Safe to retry; the response carries a `zh-allow-retry: true` header.", "required": [ "error" ], "properties": { "error": { "type": "string", "example": "Service Unavailable" } } }, "AdditionalTaxResidence": { "type": "object", "required": [ "tax_id", "jurisdiction_code" ], "properties": { "tax_id": { "type": "string", "description": "Tax identification number for the additional tax residence" }, "jurisdiction_code": { "type": "string", "description": "The ISO 3166-2 subdivision code that the participant resides in", "example": "US-IL" } } }, "PatchEntityResponse": { "type": "object", "properties": { "message": { "type": "object", "properties": { "entity_name": { "type": "string", "description": "Name of the business", "example": "Entity Name" }, "legal_name": { "type": "string", "description": "Registered legal name of the entity. This should not be a DBA or DBA equivalent", "example": "Legal Name" }, "contact_number": { "type": "string", "description": "Phone number of the business", "example": "+15557778888" }, "website": { "type": "string", "description": "Business website", "example": "company.com" }, "date_established": { "type": "string", "description": "Date the business was established. This should reflect government registration for the entity in the format `YYYY-MM-DD`", "example": "1985-09-02" }, "entity_type": { "type": "string", "enum": [ "corporation", "llc", "partnership", "sole_proprietorship", "other", "non_profit", "llc_c", "llc_s", "llc_p", "s_corporation", "c_corporation", "trust_estate", "trust" ], "description": "The type of business that is onboarding, must be one of the supported", "example": "llc" }, "address_one": { "type": "string", "description": "First line for the business's address.\n\nNotes:\n- The regular maximum length is 80 characters.\n- If the platform is on the vendor reliance track, the maximum length increases to 200 characters.\n- PO Box addresses are not accepted.", "example": "123 Main St." }, "address_two": { "type": "string", "description": "Extra information, like an apartment or suite number.\n\nNotes:\n- The regular maximum length is 50 characters.\n- If the platform is on the vendor reliance track, the maximum length increases to 200 characters.\n- PO Box addresses are not accepted.", "example": "Suite 1000" }, "city": { "type": "string", "description": "The city customer resides in", "example": "Chicago" }, "postal_code": { "type": "string", "description": "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", "example": "12345" }, "tax_id": { "type": "string", "description": "Tax identifier of the business (e.g. EIN in United States)", "example": "000-00-0000" }, "id_issuing_authority": { "type": "string", "description": "ISO-3166-1_A2 country code that issued the tax identifier (e.g. β€œUS”)", "example": "US" }, "risk_rating": { "type": "string", "enum": [ "low", "medium", "high" ], "description": "Risk assessed by the platform's vendor", "example": "low" }, "onboarding_profile": { "type": "string", "enum": [ "kyc_track", "shopper", "originator_entity", "payouts_payor_ultimate", "payouts_beneficiary" ], "description": "Onboarding profile used to determine the entity's KYC track. Optional. Defaults to 'kyc_track' when omitted.", "example": "kyc_track" }, "sanction_screening": { "type": "string", "enum": [ "pass", "fail" ], "description": "Result of the business sanctions screen\t", "example": "pass" }, "sanction_screening_timestamp": { "type": "number", "description": "The time the sanctions screen was done\t", "example": 1603378501286 }, "self_certification_timestamp": { "type": "number", "description": "The UNIX timestamp (in milliseconds) when the participant completed self-certification for DAC8 compliance. Mandatory for participants that are based in Europe.", "example": 1667504636159 }, "signed_timestamp": { "type": "number", "description": "The time at which the business accepted zerohash services agreements", "example": 1603378501286 }, "signed_agreements": { "type": "array", "description": "The agreements signed by the entity. An array of agreement objects with region, type, and timestamp.", "items": { "type": "object", "required": [ "region", "signed_timestamp" ], "properties": { "type": { "type": "string", "enum": [ "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", "virtual_accounts" ], "description": "The type of the agreement signed", "example": "zhllc_user_agreement_v1" }, "region": { "type": "string", "enum": [ "worldwide", "us", "brazil", "uk", "eu" ], "description": "The region for the signed agreement", "example": "us" }, "signed_timestamp": { "type": "number", "description": "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.", "example": 1603378501286 } } } }, "expected_annual_volume": { "type": "string", "enum": [ "unknown", "under_100k", "between_100k_and_250k", "between_250k_and_500k", "over_500k" ], "description": "Expected annual transaction volume for the entity. Required for EU entities.", "example": "over_500k" }, "submitter_email": { "type": "string", "description": "Email of the person who completed the KYC application and agreed to terms", "example": "test@example.com" }, "incorporation_address": { "type": "object", "description": "Full address where the entity is incorporated", "required": [ "jurisdiction_code" ], "properties": { "address_one": { "type": "string", "description": "First line of incorporation address" }, "address_two": { "type": "string", "description": "Second line of incorporation address (optional)" }, "city": { "type": "string", "description": "City of incorporation" }, "jurisdiction_code": { "type": "string", "description": "Jurisdiction code in ISO-3166-2 format", "example": "IT-25" }, "postal_code": { "type": "string", "description": "Postal code of incorporation address" } } }, "tax_residence": { "type": "object", "description": "Tax residence address for the entity", "required": [ "jurisdiction_code" ], "properties": { "address_one": { "type": "string", "description": "First line of tax residence address" }, "address_two": { "type": "string", "description": "Second line of tax residence address (optional)" }, "city": { "type": "string", "description": "City of tax residence" }, "jurisdiction_code": { "type": "string", "description": "Jurisdiction code in ISO-3166-2 format", "example": "PT-11" }, "postal_code": { "type": "string", "description": "Postal code of tax residence" } } }, "tin_jurisdiction_reason": { "type": "string", "enum": [ "working_abroad", "studying_abroad", "dual_residency", "business_abroad", "real_estate_abroad", "other" ], "description": "Optional. Reason for the tax residence jurisdiction differing from the legal jurisdiction. Defaults to \"unknown\" if not provided.", "example": "working_abroad" }, "b_notice_receipt": { "type": "boolean", "description": "Boolean flag indicating notice receipt status", "example": true }, "is_w_form_certified": { "type": "boolean", "description": "Indicates whether the entity is W-Form certified, required for entities onboarded to a US platform.\n\n - When `true`, the entity can be onboarded without restriction, so long as other mandatory fields are provided at time of onboarding.\n - When `false`, the entity is restricted and ineligible to transact on the platform.", "example": true }, "w_form_certification": { "type": "number", "description": "W form certification unix timestamp", "example": 1667504636159 }, "physical_delivery": { "type": "boolean", "description": "Physical delivery flag", "example": false }, "signature": { "type": "string", "description": "This field is used to capture the customer Entity `entity_name` as used on the W-form.", "example": "signature_data" }, "signature_timestamp": { "type": "number", "description": "This field captures the timestamp at which the user signed their W-form, used in conjunction with the `signature` field.", "example": 1667504636159 }, "payee_exemption": { "type": "string", "enum": [ "1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "NONE" ], "description": "Payee exemption field that captures enum values for any applicable payee exemption codes 1 - 13, or NONE if no exemption applies. Required for entities onboarded to a US platform.", "example": "NONE" }, "fatca_reporting_exemption": { "type": "string", "enum": [ "A", "B", "C", "D", "E", "F", "G", "H", "I", "J", "K", "L", "M", "NONE" ], "description": "FATCA reporting exemption code (A-M or NONE). Per the IRS W-9, FATCA exemption codes are letters A through M; use NONE if no exemption applies.", "example": "NONE" }, "is_not_subject_backup_withholding": { "type": "boolean", "description": "Backup withholding attestation flag. Required for customers onboarded to a US platform.\n - If the participant confirms they are **not** subject to backup withholding, this field should be set to `true`.\n - If the participant **is** subject to backup withholding, this field should be set to `false`.\nThis acts as a positive attestation that the participant confirms they are not subject to backup withholding.", "example": false }, "dba_name": { "type": "string", "description": "Doing Business As (DBA) name of the entity", "example": "ABC Trading Co" }, "other_entity_type": { "type": "string", "description": "Other entity type description when entity_type is \"other\"", "example": "Trust" }, "w8_ben_e": { "type": "object", "description": "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.", "properties": { "tax_classification": { "type": "string", "enum": [ "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" ], "description": "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.", "example": "corporation" }, "ftin": { "type": "string", "description": "Foreign tax identification number issued by the entity's country of tax residence. Required unless `ftin_required = false`.", "example": "DE123456789" }, "ftin_required": { "type": "boolean", "description": "Whether the entity's country legally issues an FTIN. Required whenever the sub-object is present.", "example": true }, "reference_numbers": { "type": "string", "description": "Optional free-text reference numbers for the platform to connect the tax form to a specific account or financial record.", "example": "REF-002" }, "treaty_claim": { "type": "object", "description": "Treaty benefits claim block. Optional.", "properties": { "is_eligible": { "type": "boolean", "description": "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.", "example": true }, "country": { "type": "string", "description": "Entity's country of tax residence whose treaty with the US is being invoked (ISO 3166-1 alpha-2). Required when `is_eligible = true`.", "example": "DE", "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", "YE", "YT", "ZA", "ZM", "ZW" ] }, "residence_certification": { "type": "boolean", "description": "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`.", "example": true }, "income_type": { "type": "string", "enum": [ "royalties_other", "business_profits" ], "description": "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.", "example": "business_profits" }, "withholding_rate": { "type": "string", "description": "Reduced rate granted by the treaty article, as a string percentage (e.g. \"0\", \"10\", \"15\"). Required when `is_eligible = true`.", "example": "0" }, "article_paragraph": { "type": "string", "description": "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`.", "example": "Article 7" }, "additional_conditions": { "type": "boolean", "description": "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`.", "example": false }, "requirements_certification": { "type": "boolean", "description": "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`.", "example": true }, "limitation_on_benefits": { "type": "string", "enum": [ "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" ], "description": "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.", "example": "publicly_traded_corporation" }, "limitation_on_benefits_other": { "type": "string", "description": "Free-text describing the article and paragraph the entity is relying on. Required when (and only when) `limitation_on_benefits = other_article_paragraph`.", "example": "" } } } } }, "mailing_address": { "type": "object", "description": "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.", "properties": { "address_one": { "type": "string", "description": "Primary street line of the mailing address. Required when the object is present.", "example": "10 Downing Street" }, "address_two": { "type": "string", "description": "Secondary street line (unit, suite, etc.). Optional.", "example": "Apt 2" }, "city": { "type": "string", "description": "City of the mailing address. Required when the object is present.", "example": "London" }, "state": { "type": "string", "description": "State, province, or region of the mailing address. Optional.", "example": "England" }, "postal_code": { "type": "string", "description": "Postal or ZIP code of the mailing address. Required when the object is present.", "example": "SW1A 2AA" }, "country": { "type": "string", "description": "Country of the mailing address (ISO 3166-1 alpha-2). Required when the object is present.", "example": "GB", "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", "YE", "YT", "ZA", "ZM", "ZW" ] } } }, "merchant_category_code": { "type": "string", "description": "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.", "example": "5411" }, "merchant_category_code_category": { "type": "string", "description": "Human-readable category derived by zerohash from `merchant_category_code`. Returned in responses only; not accepted as input.", "example": "Grocery Stores, Supermarkets", "readOnly": true }, "merchant_category_code_classification": { "type": "string", "enum": [ "transferable", "nontransferable", "food_vendor" ], "description": "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.", "example": "transferable", "readOnly": true }, "jurisdiction_code": { "type": "string", "example": "US-IL", "description": "The ISO 3166-2 subdivision code that the entity resides in" }, "control_persons": { "type": "array", "items": { "$ref": "#/components/schemas/ControlPersonResponseEntity" } }, "beneficial_owners": { "type": "array", "items": { "$ref": "#/components/schemas/BeneficialOwnerResponseEntity" } } } } } }, "ControlPersonEntity": { "type": "object", "properties": { "name": { "type": "string", "description": "Full name of the control person", "example": "John Smith" }, "email": { "type": "string", "description": "Email address of control person", "example": "test@example.com" }, "address_one": { "type": "string", "description": "First line for the control person's address.\n\nNotes:\n- The regular maximum length is 80 characters.\n- If the platform is on the vendor reliance track, the maximum length increases to 200 characters.\n- PO Box addresses are not accepted.", "example": "123 Main St." }, "address_two": { "type": "string", "description": "Extra information, like an apartment or suite number.\n\nNotes:\n- The regular maximum length is 50 characters.\n- If the platform is on the vendor reliance track, the maximum length increases to 200 characters.\n- PO Box addresses are not accepted.", "example": "Suite 1000" }, "city": { "type": "string", "description": "City of the control person", "example": "Chicago" }, "postal_code": { "type": "string", "description": "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", "example": "12345" }, "jurisdiction_code": { "type": "string", "example": "US-IL", "description": "The ISO 3166-2 subdivision code that the control person resides in" }, "date_of_birth": { "type": "string", "description": "Birth date of the control person", "example": "1985-09-02" }, "phone_number": { "type": "string", "description": "The phone number of the control person", "example": "+15557778888" }, "citizenship_code": { "type": "string", "example": "US", "description": "The ISO-3166-1 alpha2 citizenship of the control person, e.g. `US`.", "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", "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" ] }, "tax_id": { "type": "string", "description": "The national ID of the control person, e.g. a social security number. Required if `citizenship=United States` or `citizenship_code=US`. \nNote: if `citizenship=United States`, and `tax_id` begins with `9`, then `id_number_type` and `id_number` are also required.", "example": "123456789" }, "id_number_type": { "type": "string", "enum": [ "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" ], "description": "The type of identification number provided.\n\n**Allowed values:**\n- `us_drivers_license` - US Driver's License\n- `us_passport` - US Passport\n- `us_passport_card` - US Passport Card\n- `us_permanent_resident_card` - US Permanent Resident Card (Green Card)\n- `us_border_crossing_card` - US Border Crossing Card\n- `us_alien_card` - US Alien Registration Card\n- `us_id_card` - US State-issued ID Card\n- `non_us_passport` - Non-US Passport\n- `non_us_other` - Other Non-US identification (requires `non_us_other_type` field)\n- `passport` - Generic passport\n- `eu_drivers_license` - European Union Driver's License\n- `national_id` - National identity card\n- `legal_entity_identifier` - Legal Entity Identifier (LEI) for organizations\n- `chamber_of_commerce_number` - Chamber of Commerce registration number\n- `value_added_tax_number` - VAT identification number\n\n**Conditional requirements:**\n- When `id_number_type` is `non_us_other`, the `non_us_other_type` field is required.\n**Note:** Required when citizenship is not `United States` or `tax_id` is not an SSN.", "example": "us_passport" }, "id_number": { "type": "string", "description": "ID number of the ID document provided. \nRequired when citizenship is not `United States` or `tax_id` is not an SSN\t", "example": "123456789" }, "id_issuing_authority": { "type": "string", "description": "ISO-3166-1_A2 country code that issued the ID. Required if `id_number` is provided.", "example": "US", "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", "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" ] }, "sanction_screening": { "type": "string", "enum": [ "pass", "fail" ], "description": "Result of the control person's sanctions screening.\n\n**Allowed values:**\n- `pass` - Control person passed sanctions screening\n- `fail` - Control person failed sanctions screening", "example": "pass" }, "sanction_screening_timestamp": { "type": "number", "description": "UNIX timestamp (in milliseconds) when the sanctions screening was performed on the control person.", "example": 1603378501286 }, "kyc": { "type": "string", "enum": [ "pass", "fail" ], "description": "Whether the control person passed or failed KYC verification by vendor.\n\n**Allowed values:**\n- `pass` - KYC verification passed\n- `fail` - KYC verification failed", "example": "pass" }, "kyc_timestamp": { "type": "number", "description": "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.", "example": 1603378501286 }, "control_person": { "type": "number", "enum": [ 0, 1, 2, 3 ], "description": "Designation of what percent of the business the control person controls.\n\n**Allowed values:**\n- `0` - Unknown\n- `1` - Less than 10%\n- `2` - Greater than or equal to 10% but less than 25%\n- `3` - Greater than or equal to 25%", "example": 1 } }, "required": [ "control_person" ], "allOf": [ { "if": { "properties": { "citizenship_code": { "const": "US" } }, "required": [ "citizenship_code" ] }, "then": { "required": [ "tax_id" ] } }, { "if": { "properties": { "citizenship_code": { "const": "US" }, "tax_id": { "type": "string", "pattern": "^9" } }, "required": [ "citizenship_code", "tax_id" ] }, "then": { "required": [ "id_number_type", "id_number" ] } }, { "if": { "properties": { "citizenship_code": { "not": { "const": "US" } } }, "required": [ "citizenship_code" ] }, "then": { "required": [ "id_number_type", "id_number" ] } } ] }, "ControlPersonVariants": { "anyOf": [ { "title": "Control person β€” US (KYB)", "type": "object", "description": "**US control person** β€” identified by `tax_id`. Send `citizenship_code: \"US\"` and the SSN/ITIN in `tax_id`.\n\n> If the `tax_id` is an ITIN beginning with `9`, `id_number_type` and `id_number` are also required.", "properties": { "name": { "type": "string", "description": "Full name of the control person", "example": "John Smith" }, "email": { "type": "string", "description": "Email address of control person", "example": "test@example.com" }, "address_one": { "type": "string", "description": "First line for the control person's address.\n\nNotes:\n- The regular maximum length is 80 characters.\n- If the platform is on the vendor reliance track, the maximum length increases to 200 characters.\n- PO Box addresses are not accepted.", "example": "123 Main St." }, "address_two": { "type": "string", "description": "Extra information, like an apartment or suite number.\n\nNotes:\n- The regular maximum length is 50 characters.\n- If the platform is on the vendor reliance track, the maximum length increases to 200 characters.\n- PO Box addresses are not accepted.", "example": "Suite 1000" }, "city": { "type": "string", "description": "City of the control person", "example": "Chicago" }, "postal_code": { "type": "string", "description": "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", "example": "12345" }, "jurisdiction_code": { "type": "string", "example": "US-IL", "description": "The ISO 3166-2 subdivision code that the control person resides in" }, "date_of_birth": { "type": "string", "description": "Birth date of the control person", "example": "1985-09-02" }, "phone_number": { "type": "string", "description": "The phone number of the control person", "example": "+15557778888" }, "citizenship_code": { "type": "string", "example": "US", "description": "The ISO-3166-1 alpha2 citizenship of the control person, e.g. `US`.", "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", "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" ] }, "tax_id": { "type": "string", "description": "The national ID of the control person, e.g. a social security number. Required if `citizenship=United States` or `citizenship_code=US`. \nNote: if `citizenship=United States`, and `tax_id` begins with `9`, then `id_number_type` and `id_number` are also required.", "example": "123456789" }, "control_person": { "type": "number", "enum": [ 0, 1, 2, 3 ], "description": "Designation of what percent of the business the control person controls.\n\n**Allowed values:**\n- `0` - Unknown\n- `1` - Less than 10%\n- `2` - Greater than or equal to 10% but less than 25%\n- `3` - Greater than or equal to 25%", "example": 1 } }, "required": [ "name", "citizenship_code", "tax_id", "control_person" ] }, { "title": "Control person β€” Non-US (KYB)", "type": "object", "description": "**Non-US control person** β€” identified by `id_number` + `id_number_type`. Send a non-`US` `citizenship_code`, the document type in `id_number_type`, the number in `id_number`, and the ISO-3166-1 alpha-2 issuing country in `id_issuing_authority`.", "properties": { "name": { "type": "string", "description": "Full name of the control person", "example": "John Smith" }, "email": { "type": "string", "description": "Email address of control person", "example": "test@example.com" }, "address_one": { "type": "string", "description": "First line for the control person's address.\n\nNotes:\n- The regular maximum length is 80 characters.\n- If the platform is on the vendor reliance track, the maximum length increases to 200 characters.\n- PO Box addresses are not accepted.", "example": "123 Main St." }, "address_two": { "type": "string", "description": "Extra information, like an apartment or suite number.\n\nNotes:\n- The regular maximum length is 50 characters.\n- If the platform is on the vendor reliance track, the maximum length increases to 200 characters.\n- PO Box addresses are not accepted.", "example": "Suite 1000" }, "city": { "type": "string", "description": "City of the control person", "example": "Chicago" }, "postal_code": { "type": "string", "description": "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", "example": "12345" }, "jurisdiction_code": { "type": "string", "example": "US-IL", "description": "The ISO 3166-2 subdivision code that the control person resides in" }, "date_of_birth": { "type": "string", "description": "Birth date of the control person", "example": "1985-09-02" }, "phone_number": { "type": "string", "description": "The phone number of the control person", "example": "+15557778888" }, "citizenship_code": { "type": "string", "example": "US", "description": "The ISO-3166-1 alpha2 citizenship of the control person, e.g. `US`.", "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", "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" ] }, "id_number_type": { "type": "string", "enum": [ "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" ], "description": "The type of identification number provided.\n\n**Allowed values:**\n- `us_drivers_license` - US Driver's License\n- `us_passport` - US Passport\n- `us_passport_card` - US Passport Card\n- `us_permanent_resident_card` - US Permanent Resident Card (Green Card)\n- `us_border_crossing_card` - US Border Crossing Card\n- `us_alien_card` - US Alien Registration Card\n- `us_id_card` - US State-issued ID Card\n- `non_us_passport` - Non-US Passport\n- `non_us_other` - Other Non-US identification (requires `non_us_other_type` field)\n- `passport` - Generic passport\n- `eu_drivers_license` - European Union Driver's License\n- `national_id` - National identity card\n- `legal_entity_identifier` - Legal Entity Identifier (LEI) for organizations\n- `chamber_of_commerce_number` - Chamber of Commerce registration number\n- `value_added_tax_number` - VAT identification number\n\n**Conditional requirements:**\n- When `id_number_type` is `non_us_other`, the `non_us_other_type` field is required.\n**Note:** Required when citizenship is not `United States` or `tax_id` is not an SSN.", "example": "us_passport" }, "id_number": { "type": "string", "description": "ID number of the ID document provided. \nRequired when citizenship is not `United States` or `tax_id` is not an SSN\t", "example": "123456789" }, "id_issuing_authority": { "type": "string", "description": "ISO-3166-1_A2 country code that issued the ID. Required if `id_number` is provided.", "example": "US", "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", "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" ] }, "control_person": { "type": "number", "enum": [ 0, 1, 2, 3 ], "description": "Designation of what percent of the business the control person controls.\n\n**Allowed values:**\n- `0` - Unknown\n- `1` - Less than 10%\n- `2` - Greater than or equal to 10% but less than 25%\n- `3` - Greater than or equal to 25%", "example": 1 } }, "required": [ "name", "citizenship_code", "id_number_type", "id_number", "control_person" ] }, { "title": "Control person β€” US (reliance)", "type": "object", "description": "**US control person** β€” identified by `tax_id`. Send `citizenship_code: \"US\"` and the SSN/ITIN in `tax_id`.\n\n> If the `tax_id` is an ITIN beginning with `9`, `id_number_type` and `id_number` are also required.\n\n**Vendor reliance track:** also send vendor-produced verification results β€” `kyc`, `kyc_timestamp`, `sanction_screening`, and `sanction_screening_timestamp`.", "properties": { "name": { "type": "string", "description": "Full name of the control person", "example": "John Smith" }, "email": { "type": "string", "description": "Email address of control person", "example": "test@example.com" }, "address_one": { "type": "string", "description": "First line for the control person's address.\n\nNotes:\n- The regular maximum length is 80 characters.\n- If the platform is on the vendor reliance track, the maximum length increases to 200 characters.\n- PO Box addresses are not accepted.", "example": "123 Main St." }, "address_two": { "type": "string", "description": "Extra information, like an apartment or suite number.\n\nNotes:\n- The regular maximum length is 50 characters.\n- If the platform is on the vendor reliance track, the maximum length increases to 200 characters.\n- PO Box addresses are not accepted.", "example": "Suite 1000" }, "city": { "type": "string", "description": "City of the control person", "example": "Chicago" }, "postal_code": { "type": "string", "description": "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", "example": "12345" }, "jurisdiction_code": { "type": "string", "example": "US-IL", "description": "The ISO 3166-2 subdivision code that the control person resides in" }, "date_of_birth": { "type": "string", "description": "Birth date of the control person", "example": "1985-09-02" }, "phone_number": { "type": "string", "description": "The phone number of the control person", "example": "+15557778888" }, "citizenship_code": { "type": "string", "example": "US", "description": "The ISO-3166-1 alpha2 citizenship of the control person, e.g. `US`.", "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", "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" ] }, "tax_id": { "type": "string", "description": "The national ID of the control person, e.g. a social security number. Required if `citizenship=United States` or `citizenship_code=US`. \nNote: if `citizenship=United States`, and `tax_id` begins with `9`, then `id_number_type` and `id_number` are also required.", "example": "123456789" }, "sanction_screening": { "type": "string", "enum": [ "pass", "fail" ], "description": "Result of the control person's sanctions screening.\n\n**Allowed values:**\n- `pass` - Control person passed sanctions screening\n- `fail` - Control person failed sanctions screening", "example": "pass" }, "sanction_screening_timestamp": { "type": "number", "description": "UNIX timestamp (in milliseconds) when the sanctions screening was performed on the control person.", "example": 1603378501286 }, "kyc": { "type": "string", "enum": [ "pass", "fail" ], "description": "Whether the control person passed or failed KYC verification by vendor.\n\n**Allowed values:**\n- `pass` - KYC verification passed\n- `fail` - KYC verification failed", "example": "pass" }, "kyc_timestamp": { "type": "number", "description": "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.", "example": 1603378501286 }, "control_person": { "type": "number", "enum": [ 0, 1, 2, 3 ], "description": "Designation of what percent of the business the control person controls.\n\n**Allowed values:**\n- `0` - Unknown\n- `1` - Less than 10%\n- `2` - Greater than or equal to 10% but less than 25%\n- `3` - Greater than or equal to 25%", "example": 1 } }, "required": [ "name", "citizenship_code", "tax_id", "control_person", "kyc", "kyc_timestamp", "sanction_screening", "sanction_screening_timestamp" ] }, { "title": "Control person β€” Non-US (reliance)", "type": "object", "description": "**Non-US control person** β€” identified by `id_number` + `id_number_type`. Send a non-`US` `citizenship_code`, the document type in `id_number_type`, the number in `id_number`, and the ISO-3166-1 alpha-2 issuing country in `id_issuing_authority`.\n\n**Vendor reliance track:** also send vendor-produced verification results β€” `kyc`, `kyc_timestamp`, `sanction_screening`, and `sanction_screening_timestamp`.", "properties": { "name": { "type": "string", "description": "Full name of the control person", "example": "John Smith" }, "email": { "type": "string", "description": "Email address of control person", "example": "test@example.com" }, "address_one": { "type": "string", "description": "First line for the control person's address.\n\nNotes:\n- The regular maximum length is 80 characters.\n- If the platform is on the vendor reliance track, the maximum length increases to 200 characters.\n- PO Box addresses are not accepted.", "example": "123 Main St." }, "address_two": { "type": "string", "description": "Extra information, like an apartment or suite number.\n\nNotes:\n- The regular maximum length is 50 characters.\n- If the platform is on the vendor reliance track, the maximum length increases to 200 characters.\n- PO Box addresses are not accepted.", "example": "Suite 1000" }, "city": { "type": "string", "description": "City of the control person", "example": "Chicago" }, "postal_code": { "type": "string", "description": "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", "example": "12345" }, "jurisdiction_code": { "type": "string", "example": "US-IL", "description": "The ISO 3166-2 subdivision code that the control person resides in" }, "date_of_birth": { "type": "string", "description": "Birth date of the control person", "example": "1985-09-02" }, "phone_number": { "type": "string", "description": "The phone number of the control person", "example": "+15557778888" }, "citizenship_code": { "type": "string", "example": "US", "description": "The ISO-3166-1 alpha2 citizenship of the control person, e.g. `US`.", "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", "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" ] }, "id_number_type": { "type": "string", "enum": [ "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" ], "description": "The type of identification number provided.\n\n**Allowed values:**\n- `us_drivers_license` - US Driver's License\n- `us_passport` - US Passport\n- `us_passport_card` - US Passport Card\n- `us_permanent_resident_card` - US Permanent Resident Card (Green Card)\n- `us_border_crossing_card` - US Border Crossing Card\n- `us_alien_card` - US Alien Registration Card\n- `us_id_card` - US State-issued ID Card\n- `non_us_passport` - Non-US Passport\n- `non_us_other` - Other Non-US identification (requires `non_us_other_type` field)\n- `passport` - Generic passport\n- `eu_drivers_license` - European Union Driver's License\n- `national_id` - National identity card\n- `legal_entity_identifier` - Legal Entity Identifier (LEI) for organizations\n- `chamber_of_commerce_number` - Chamber of Commerce registration number\n- `value_added_tax_number` - VAT identification number\n\n**Conditional requirements:**\n- When `id_number_type` is `non_us_other`, the `non_us_other_type` field is required.\n**Note:** Required when citizenship is not `United States` or `tax_id` is not an SSN.", "example": "us_passport" }, "id_number": { "type": "string", "description": "ID number of the ID document provided. \nRequired when citizenship is not `United States` or `tax_id` is not an SSN\t", "example": "123456789" }, "id_issuing_authority": { "type": "string", "description": "ISO-3166-1_A2 country code that issued the ID. Required if `id_number` is provided.", "example": "US", "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", "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" ] }, "sanction_screening": { "type": "string", "enum": [ "pass", "fail" ], "description": "Result of the control person's sanctions screening.\n\n**Allowed values:**\n- `pass` - Control person passed sanctions screening\n- `fail` - Control person failed sanctions screening", "example": "pass" }, "sanction_screening_timestamp": { "type": "number", "description": "UNIX timestamp (in milliseconds) when the sanctions screening was performed on the control person.", "example": 1603378501286 }, "kyc": { "type": "string", "enum": [ "pass", "fail" ], "description": "Whether the control person passed or failed KYC verification by vendor.\n\n**Allowed values:**\n- `pass` - KYC verification passed\n- `fail` - KYC verification failed", "example": "pass" }, "kyc_timestamp": { "type": "number", "description": "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.", "example": 1603378501286 }, "control_person": { "type": "number", "enum": [ 0, 1, 2, 3 ], "description": "Designation of what percent of the business the control person controls.\n\n**Allowed values:**\n- `0` - Unknown\n- `1` - Less than 10%\n- `2` - Greater than or equal to 10% but less than 25%\n- `3` - Greater than or equal to 25%", "example": 1 } }, "required": [ "name", "citizenship_code", "id_number_type", "id_number", "control_person", "kyc", "kyc_timestamp", "sanction_screening", "sanction_screening_timestamp" ] }, { "title": "Control person β€” All accepted fields (reference)", "description": "Every field accepted for a control person β€” a **documentation superset** showing the full surface, **not** a single valid request: the US (`tax_id`) and non-US (`id_number` / `id_number_type`) identifiers are mutually exclusive, and vendor `kyc` / `sanction_screening` results apply to the reliance track only.", "allOf": [ { "$ref": "#/components/schemas/ControlPersonEntity" } ] } ] }, "ControlPersonResponseEntity": { "type": "object", "properties": { "user_code": { "type": "string", "description": "zerohash identifier for the Control Person(s) (One code returned per person)", "example": "U-XXXXXX" }, "name": { "type": "string", "description": "Full name of the control person", "example": "John Smith" }, "email": { "type": "string", "description": "Email address of control person", "example": "test@example.com" }, "address_one": { "type": "string", "description": "First line for the control person's address.\n\nNotes:\n- The regular maximum length is 80 characters.\n- If the platform is on the vendor reliance track, the maximum length increases to 200 characters.\n- PO Box addresses are not accepted.", "example": "123 Main St." }, "address_two": { "type": "string", "description": "Extra information, like an apartment or suite number.\n\nNotes:\n- The regular maximum length is 50 characters.\n- If the platform is on the vendor reliance track, the maximum length increases to 200 characters.\n- PO Box addresses are not accepted.", "example": "Suite 1000" }, "city": { "type": "string", "description": "City of the control person", "example": "Chicago" }, "postal_code": { "type": "string", "description": "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", "example": "12345" }, "jurisdiction_code": { "type": "string", "example": "US-IL", "description": "The ISO 3166-2 subdivision code that the control person resides in" }, "date_of_birth": { "type": "string", "description": "Birth date of the control person", "example": "1985-09-02" }, "phone_number": { "type": "string", "description": "The phone number of the control person", "example": "+15557778888" }, "citizenship_code": { "type": "string", "example": "US", "description": "The ISO-3166-1 alpha2 citizenship of the control person, e.g. `US`.", "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", "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" ] }, "tax_id": { "type": "string", "description": "The national ID of the control person, e.g. a social security number. Required if `citizenship=United States` or `citizenship_code=US`. \nNote: if `citizenship=United States`, and `tax_id` begins with `9`, then `id_number_type` and `id_number` are also required.", "example": "123456789" }, "id_number_type": { "type": "string", "enum": [ "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" ], "description": "The type of identification number provided.\n\n**Allowed values:**\n- `us_drivers_license` - US Driver's License\n- `us_passport` - US Passport\n- `us_passport_card` - US Passport Card\n- `us_permanent_resident_card` - US Permanent Resident Card (Green Card)\n- `us_border_crossing_card` - US Border Crossing Card\n- `us_alien_card` - US Alien Registration Card\n- `us_id_card` - US State-issued ID Card\n- `non_us_passport` - Non-US Passport\n- `non_us_other` - Other Non-US identification (requires `non_us_other_type` field)\n- `passport` - Generic passport\n- `eu_drivers_license` - European Union Driver's License\n- `national_id` - National identity card\n- `legal_entity_identifier` - Legal Entity Identifier (LEI) for organizations\n- `chamber_of_commerce_number` - Chamber of Commerce registration number\n- `value_added_tax_number` - VAT identification number\n\n**Conditional requirements:**\n- When `id_number_type` is `non_us_other`, the `non_us_other_type` field is required.\n**Note:** Required when citizenship is not `United States` or `tax_id` is not an SSN.", "example": "us_passport" }, "id_number": { "type": "string", "description": "ID number of the ID document provided. \nRequired when citizenship is not `United States` or `tax_id` is not an SSN\t", "example": "123456789" }, "id_issuing_authority": { "type": "string", "description": "ISO-3166-1_A2 country code that issued the ID. Required if `id_number` is provided.", "example": "US" }, "sanction_screening": { "type": "string", "enum": [ "pass", "fail" ], "description": "Result of the control person's sanctions screening.\n\n**Allowed values:**\n- `pass` - Control person passed sanctions screening\n- `fail` - Control person failed sanctions screening", "example": "pass" }, "sanction_screening_timestamp": { "type": "number", "description": "UNIX timestamp (in milliseconds) when the sanctions screening was performed on the control person.", "example": 1603378501286 }, "kyc": { "type": "string", "enum": [ "pass", "fail" ], "description": "Whether the control person passed or failed KYC verification by vendor.\n\n**Allowed values:**\n- `pass` - KYC verification passed\n- `fail` - KYC verification failed", "example": "pass" }, "kyc_timestamp": { "type": "number", "description": "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.", "example": 1603378501286 }, "control_person": { "type": "number", "enum": [ 0, 1, 2, 3 ], "description": "Designation of what percent of the business the control person controls.\n\n**Allowed values:**\n- `0` - Unknown\n- `1` - Less than 10%\n- `2` - Greater than or equal to 10% but less than 25%\n- `3` - Greater than or equal to 25%", "example": 1 } } }, "BeneficialOwnerEntity": { "type": "object", "properties": { "name": { "type": "string", "description": "Full name of the beneficial owner", "example": "John Smith" }, "email": { "type": "string", "description": "Email address of the beneficial owner", "example": "test@example.com" }, "address_one": { "type": "string", "description": "First line for the beneficial owner's address.\n\nNotes:\n- The regular maximum length is 80 characters.\n\n- If the platform is on the vendor reliance track, the maximum length increases to 200 characters.\n- PO Box addresses are not accepted.", "example": "123 Main St." }, "address_two": { "type": "string", "description": "Extra information, like an apartment or suite number.\n\nNotes:\n- The regular maximum length is 50 characters.\n- If the platform is on the vendor reliance track, the maximum length increases to 200 characters.\n- PO Box addresses are not accepted.", "example": "Suite 1000" }, "city": { "type": "string", "description": "City of the beneficial owner", "example": "Chicago" }, "postal_code": { "type": "string", "description": "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", "example": "12345" }, "jurisdiction_code": { "type": "string", "example": "US-IL", "description": "The ISO 3166-2 subdivision code that the beneficial owner resides in" }, "date_of_birth": { "type": "string", "description": "Birth date of the beneficial owner", "example": "1985-09-02" }, "phone_number": { "type": "string", "description": "The phone number of the beneficial owner", "example": "+15557778888" }, "citizenship_code": { "type": "string", "example": "US", "description": "The ISO-3166-1 alpha2 citizenship of the beneficial owner, e.g. `US`.", "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", "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" ] }, "tax_id": { "type": "string", "description": "The national ID of the beneficial owner, e.g. a social security number. Required if `citizenship=United States` or `citizenship_code=US`. \nNote: if `citizenship=United States`, and `tax_id` begins with `9`, then `id_number_type` and `id_number` are also required.", "example": "123456789" }, "id_number_type": { "type": "string", "enum": [ "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" ], "description": "The type of identification number provided.\n\n**Allowed values:**\n- `us_drivers_license` - US Driver's License\n- `us_passport` - US Passport\n- `us_passport_card` - US Passport Card\n- `us_permanent_resident_card` - US Permanent Resident Card (Green Card)\n- `us_border_crossing_card` - US Border Crossing Card\n- `us_alien_card` - US Alien Registration Card\n- `us_id_card` - US State-issued ID Card\n- `non_us_passport` - Non-US Passport\n- `non_us_other` - Other Non-US identification (requires `non_us_other_type` field)\n- `passport` - Generic passport\n- `eu_drivers_license` - European Union Driver's License\n- `national_id` - National identity card\n- `legal_entity_identifier` - Legal Entity Identifier (LEI) for organizations\n- `chamber_of_commerce_number` - Chamber of Commerce registration number\n- `value_added_tax_number` - VAT identification number\n\n**Conditional requirements:**\n- When `id_number_type` is `non_us_other`, the `non_us_other_type` field is required.\n**Note:** Required when citizenship is not `United States` or `tax_id` is not an SSN.", "example": "us_passport" }, "id_number": { "type": "string", "description": "ID number of the ID document provided. \nRequired when citizenship is not `United States` or `tax_id` is not an SSN\t", "example": "123456789" }, "id_issuing_authority": { "type": "string", "description": "ISO-3166-1_A2 country code that issued the ID. Required if `id_number` is provided.", "example": "US" }, "sanction_screening": { "type": "string", "enum": [ "pass", "fail" ], "description": "Result of the beneficial owner's sanctions screening.\n\n**Allowed values:**\n- `pass` - Beneficial owner passed sanctions screening\n- `fail` - Beneficial owner failed sanctions screening", "example": "pass" }, "sanction_screening_timestamp": { "type": "number", "description": "UNIX timestamp (in milliseconds) when the sanctions screening was performed on the beneficial owner.", "example": 1603378501286 }, "kyc": { "type": "string", "enum": [ "pass", "fail" ], "description": "Whether the beneficial owner passed or failed KYC verification by vendor.\n\n**Allowed values:**\n- `pass` - KYC verification passed\n- `fail` - KYC verification failed", "example": "pass" }, "kyc_timestamp": { "type": "number", "description": "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.", "example": 1603378501286 }, "beneficial_owner": { "type": "number", "enum": [ 0, 1, 2 ], "description": "Designation of what percent of the business the beneficial owner owns.\n\n**Allowed values:**\n- `0` - Unknown\n- `1` - Greater than or equal to 10% but less than 25%\n- `2` - Greater than or equal to 25%", "example": 1 }, "role": { "type": "string", "description": "Free-text role or title the beneficial owner holds within the entity (e.g. `director`, `officer`, `partner`, `trustee`, `member`). No fixed set of values is enforced β€” send the title as it applies on your platform.", "example": "director" } }, "required": [ "beneficial_owner" ], "allOf": [ { "if": { "properties": { "citizenship_code": { "const": "US" } }, "required": [ "citizenship_code" ] }, "then": { "required": [ "tax_id" ] } }, { "if": { "properties": { "citizenship_code": { "const": "US" }, "tax_id": { "type": "string", "pattern": "^9" } }, "required": [ "citizenship_code", "tax_id" ] }, "then": { "required": [ "id_number_type", "id_number" ] } }, { "if": { "properties": { "citizenship_code": { "not": { "const": "US" } } }, "required": [ "citizenship_code" ] }, "then": { "required": [ "id_number_type", "id_number" ] } } ] }, "BeneficialOwnerVariants": { "anyOf": [ { "title": "Beneficial owner β€” US (KYB)", "type": "object", "description": "**US beneficial owner** β€” identified by `tax_id`. Send `citizenship_code: \"US\"` and the SSN/ITIN in `tax_id`.\n\n> If the `tax_id` is an ITIN beginning with `9`, `id_number_type` and `id_number` are also required.", "properties": { "name": { "type": "string", "description": "Full name of the beneficial owner", "example": "John Smith" }, "email": { "type": "string", "description": "Email address of the beneficial owner", "example": "test@example.com" }, "address_one": { "type": "string", "description": "First line for the beneficial owner's address.\n\nNotes:\n- The regular maximum length is 80 characters.\n\n- If the platform is on the vendor reliance track, the maximum length increases to 200 characters.\n- PO Box addresses are not accepted.", "example": "123 Main St." }, "address_two": { "type": "string", "description": "Extra information, like an apartment or suite number.\n\nNotes:\n- The regular maximum length is 50 characters.\n- If the platform is on the vendor reliance track, the maximum length increases to 200 characters.\n- PO Box addresses are not accepted.", "example": "Suite 1000" }, "city": { "type": "string", "description": "City of the beneficial owner", "example": "Chicago" }, "postal_code": { "type": "string", "description": "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", "example": "12345" }, "jurisdiction_code": { "type": "string", "example": "US-IL", "description": "The ISO 3166-2 subdivision code that the beneficial owner resides in" }, "date_of_birth": { "type": "string", "description": "Birth date of the beneficial owner", "example": "1985-09-02" }, "phone_number": { "type": "string", "description": "The phone number of the beneficial owner", "example": "+15557778888" }, "citizenship_code": { "type": "string", "example": "US", "description": "The ISO-3166-1 alpha2 citizenship of the beneficial owner, e.g. `US`.", "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", "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" ] }, "tax_id": { "type": "string", "description": "The national ID of the beneficial owner, e.g. a social security number. Required if `citizenship=United States` or `citizenship_code=US`. \nNote: if `citizenship=United States`, and `tax_id` begins with `9`, then `id_number_type` and `id_number` are also required.", "example": "123456789" }, "beneficial_owner": { "type": "number", "enum": [ 0, 1, 2 ], "description": "Designation of what percent of the business the beneficial owner owns.\n\n**Allowed values:**\n- `0` - Unknown\n- `1` - Greater than or equal to 10% but less than 25%\n- `2` - Greater than or equal to 25%", "example": 1 }, "role": { "type": "string", "description": "Free-text role or title the beneficial owner holds within the entity (e.g. `director`, `officer`, `partner`, `trustee`, `member`). No fixed set of values is enforced β€” send the title as it applies on your platform.", "example": "director" } }, "required": [ "name", "citizenship_code", "tax_id", "beneficial_owner" ] }, { "title": "Beneficial owner β€” Non-US (KYB)", "type": "object", "description": "**Non-US beneficial owner** β€” identified by `id_number` + `id_number_type`. Send a non-`US` `citizenship_code`, the document type in `id_number_type`, the number in `id_number`, and the ISO-3166-1 alpha-2 issuing country in `id_issuing_authority`.", "properties": { "name": { "type": "string", "description": "Full name of the beneficial owner", "example": "John Smith" }, "email": { "type": "string", "description": "Email address of the beneficial owner", "example": "test@example.com" }, "address_one": { "type": "string", "description": "First line for the beneficial owner's address.\n\nNotes:\n- The regular maximum length is 80 characters.\n\n- If the platform is on the vendor reliance track, the maximum length increases to 200 characters.\n- PO Box addresses are not accepted.", "example": "123 Main St." }, "address_two": { "type": "string", "description": "Extra information, like an apartment or suite number.\n\nNotes:\n- The regular maximum length is 50 characters.\n- If the platform is on the vendor reliance track, the maximum length increases to 200 characters.\n- PO Box addresses are not accepted.", "example": "Suite 1000" }, "city": { "type": "string", "description": "City of the beneficial owner", "example": "Chicago" }, "postal_code": { "type": "string", "description": "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", "example": "12345" }, "jurisdiction_code": { "type": "string", "example": "US-IL", "description": "The ISO 3166-2 subdivision code that the beneficial owner resides in" }, "date_of_birth": { "type": "string", "description": "Birth date of the beneficial owner", "example": "1985-09-02" }, "phone_number": { "type": "string", "description": "The phone number of the beneficial owner", "example": "+15557778888" }, "citizenship_code": { "type": "string", "example": "US", "description": "The ISO-3166-1 alpha2 citizenship of the beneficial owner, e.g. `US`.", "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", "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" ] }, "id_number_type": { "type": "string", "enum": [ "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" ], "description": "The type of identification number provided.\n\n**Allowed values:**\n- `us_drivers_license` - US Driver's License\n- `us_passport` - US Passport\n- `us_passport_card` - US Passport Card\n- `us_permanent_resident_card` - US Permanent Resident Card (Green Card)\n- `us_border_crossing_card` - US Border Crossing Card\n- `us_alien_card` - US Alien Registration Card\n- `us_id_card` - US State-issued ID Card\n- `non_us_passport` - Non-US Passport\n- `non_us_other` - Other Non-US identification (requires `non_us_other_type` field)\n- `passport` - Generic passport\n- `eu_drivers_license` - European Union Driver's License\n- `national_id` - National identity card\n- `legal_entity_identifier` - Legal Entity Identifier (LEI) for organizations\n- `chamber_of_commerce_number` - Chamber of Commerce registration number\n- `value_added_tax_number` - VAT identification number\n\n**Conditional requirements:**\n- When `id_number_type` is `non_us_other`, the `non_us_other_type` field is required.\n**Note:** Required when citizenship is not `United States` or `tax_id` is not an SSN.", "example": "us_passport" }, "id_number": { "type": "string", "description": "ID number of the ID document provided. \nRequired when citizenship is not `United States` or `tax_id` is not an SSN\t", "example": "123456789" }, "id_issuing_authority": { "type": "string", "description": "ISO-3166-1_A2 country code that issued the ID. Required if `id_number` is provided.", "example": "US" }, "beneficial_owner": { "type": "number", "enum": [ 0, 1, 2 ], "description": "Designation of what percent of the business the beneficial owner owns.\n\n**Allowed values:**\n- `0` - Unknown\n- `1` - Greater than or equal to 10% but less than 25%\n- `2` - Greater than or equal to 25%", "example": 1 }, "role": { "type": "string", "description": "Free-text role or title the beneficial owner holds within the entity (e.g. `director`, `officer`, `partner`, `trustee`, `member`). No fixed set of values is enforced β€” send the title as it applies on your platform.", "example": "director" } }, "required": [ "name", "citizenship_code", "id_number_type", "id_number", "beneficial_owner" ] }, { "title": "Beneficial owner β€” US (reliance)", "type": "object", "description": "**US beneficial owner** β€” identified by `tax_id`. Send `citizenship_code: \"US\"` and the SSN/ITIN in `tax_id`.\n\n> If the `tax_id` is an ITIN beginning with `9`, `id_number_type` and `id_number` are also required.\n\n**Vendor reliance track:** also send vendor-produced verification results β€” `kyc`, `kyc_timestamp`, `sanction_screening`, and `sanction_screening_timestamp`.", "properties": { "name": { "type": "string", "description": "Full name of the beneficial owner", "example": "John Smith" }, "email": { "type": "string", "description": "Email address of the beneficial owner", "example": "test@example.com" }, "address_one": { "type": "string", "description": "First line for the beneficial owner's address.\n\nNotes:\n- The regular maximum length is 80 characters.\n\n- If the platform is on the vendor reliance track, the maximum length increases to 200 characters.\n- PO Box addresses are not accepted.", "example": "123 Main St." }, "address_two": { "type": "string", "description": "Extra information, like an apartment or suite number.\n\nNotes:\n- The regular maximum length is 50 characters.\n- If the platform is on the vendor reliance track, the maximum length increases to 200 characters.\n- PO Box addresses are not accepted.", "example": "Suite 1000" }, "city": { "type": "string", "description": "City of the beneficial owner", "example": "Chicago" }, "postal_code": { "type": "string", "description": "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", "example": "12345" }, "jurisdiction_code": { "type": "string", "example": "US-IL", "description": "The ISO 3166-2 subdivision code that the beneficial owner resides in" }, "date_of_birth": { "type": "string", "description": "Birth date of the beneficial owner", "example": "1985-09-02" }, "phone_number": { "type": "string", "description": "The phone number of the beneficial owner", "example": "+15557778888" }, "citizenship_code": { "type": "string", "example": "US", "description": "The ISO-3166-1 alpha2 citizenship of the beneficial owner, e.g. `US`.", "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", "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" ] }, "tax_id": { "type": "string", "description": "The national ID of the beneficial owner, e.g. a social security number. Required if `citizenship=United States` or `citizenship_code=US`. \nNote: if `citizenship=United States`, and `tax_id` begins with `9`, then `id_number_type` and `id_number` are also required.", "example": "123456789" }, "sanction_screening": { "type": "string", "enum": [ "pass", "fail" ], "description": "Result of the beneficial owner's sanctions screening.\n\n**Allowed values:**\n- `pass` - Beneficial owner passed sanctions screening\n- `fail` - Beneficial owner failed sanctions screening", "example": "pass" }, "sanction_screening_timestamp": { "type": "number", "description": "UNIX timestamp (in milliseconds) when the sanctions screening was performed on the beneficial owner.", "example": 1603378501286 }, "kyc": { "type": "string", "enum": [ "pass", "fail" ], "description": "Whether the beneficial owner passed or failed KYC verification by vendor.\n\n**Allowed values:**\n- `pass` - KYC verification passed\n- `fail` - KYC verification failed", "example": "pass" }, "kyc_timestamp": { "type": "number", "description": "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.", "example": 1603378501286 }, "beneficial_owner": { "type": "number", "enum": [ 0, 1, 2 ], "description": "Designation of what percent of the business the beneficial owner owns.\n\n**Allowed values:**\n- `0` - Unknown\n- `1` - Greater than or equal to 10% but less than 25%\n- `2` - Greater than or equal to 25%", "example": 1 }, "role": { "type": "string", "description": "Free-text role or title the beneficial owner holds within the entity (e.g. `director`, `officer`, `partner`, `trustee`, `member`). No fixed set of values is enforced β€” send the title as it applies on your platform.", "example": "director" } }, "required": [ "name", "citizenship_code", "tax_id", "beneficial_owner", "kyc", "kyc_timestamp", "sanction_screening", "sanction_screening_timestamp" ] }, { "title": "Beneficial owner β€” Non-US (reliance)", "type": "object", "description": "**Non-US beneficial owner** β€” identified by `id_number` + `id_number_type`. Send a non-`US` `citizenship_code`, the document type in `id_number_type`, the number in `id_number`, and the ISO-3166-1 alpha-2 issuing country in `id_issuing_authority`.\n\n**Vendor reliance track:** also send vendor-produced verification results β€” `kyc`, `kyc_timestamp`, `sanction_screening`, and `sanction_screening_timestamp`.", "properties": { "name": { "type": "string", "description": "Full name of the beneficial owner", "example": "John Smith" }, "email": { "type": "string", "description": "Email address of the beneficial owner", "example": "test@example.com" }, "address_one": { "type": "string", "description": "First line for the beneficial owner's address.\n\nNotes:\n- The regular maximum length is 80 characters.\n\n- If the platform is on the vendor reliance track, the maximum length increases to 200 characters.\n- PO Box addresses are not accepted.", "example": "123 Main St." }, "address_two": { "type": "string", "description": "Extra information, like an apartment or suite number.\n\nNotes:\n- The regular maximum length is 50 characters.\n- If the platform is on the vendor reliance track, the maximum length increases to 200 characters.\n- PO Box addresses are not accepted.", "example": "Suite 1000" }, "city": { "type": "string", "description": "City of the beneficial owner", "example": "Chicago" }, "postal_code": { "type": "string", "description": "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", "example": "12345" }, "jurisdiction_code": { "type": "string", "example": "US-IL", "description": "The ISO 3166-2 subdivision code that the beneficial owner resides in" }, "date_of_birth": { "type": "string", "description": "Birth date of the beneficial owner", "example": "1985-09-02" }, "phone_number": { "type": "string", "description": "The phone number of the beneficial owner", "example": "+15557778888" }, "citizenship_code": { "type": "string", "example": "US", "description": "The ISO-3166-1 alpha2 citizenship of the beneficial owner, e.g. `US`.", "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", "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" ] }, "id_number_type": { "type": "string", "enum": [ "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" ], "description": "The type of identification number provided.\n\n**Allowed values:**\n- `us_drivers_license` - US Driver's License\n- `us_passport` - US Passport\n- `us_passport_card` - US Passport Card\n- `us_permanent_resident_card` - US Permanent Resident Card (Green Card)\n- `us_border_crossing_card` - US Border Crossing Card\n- `us_alien_card` - US Alien Registration Card\n- `us_id_card` - US State-issued ID Card\n- `non_us_passport` - Non-US Passport\n- `non_us_other` - Other Non-US identification (requires `non_us_other_type` field)\n- `passport` - Generic passport\n- `eu_drivers_license` - European Union Driver's License\n- `national_id` - National identity card\n- `legal_entity_identifier` - Legal Entity Identifier (LEI) for organizations\n- `chamber_of_commerce_number` - Chamber of Commerce registration number\n- `value_added_tax_number` - VAT identification number\n\n**Conditional requirements:**\n- When `id_number_type` is `non_us_other`, the `non_us_other_type` field is required.\n**Note:** Required when citizenship is not `United States` or `tax_id` is not an SSN.", "example": "us_passport" }, "id_number": { "type": "string", "description": "ID number of the ID document provided. \nRequired when citizenship is not `United States` or `tax_id` is not an SSN\t", "example": "123456789" }, "id_issuing_authority": { "type": "string", "description": "ISO-3166-1_A2 country code that issued the ID. Required if `id_number` is provided.", "example": "US" }, "sanction_screening": { "type": "string", "enum": [ "pass", "fail" ], "description": "Result of the beneficial owner's sanctions screening.\n\n**Allowed values:**\n- `pass` - Beneficial owner passed sanctions screening\n- `fail` - Beneficial owner failed sanctions screening", "example": "pass" }, "sanction_screening_timestamp": { "type": "number", "description": "UNIX timestamp (in milliseconds) when the sanctions screening was performed on the beneficial owner.", "example": 1603378501286 }, "kyc": { "type": "string", "enum": [ "pass", "fail" ], "description": "Whether the beneficial owner passed or failed KYC verification by vendor.\n\n**Allowed values:**\n- `pass` - KYC verification passed\n- `fail` - KYC verification failed", "example": "pass" }, "kyc_timestamp": { "type": "number", "description": "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.", "example": 1603378501286 }, "beneficial_owner": { "type": "number", "enum": [ 0, 1, 2 ], "description": "Designation of what percent of the business the beneficial owner owns.\n\n**Allowed values:**\n- `0` - Unknown\n- `1` - Greater than or equal to 10% but less than 25%\n- `2` - Greater than or equal to 25%", "example": 1 }, "role": { "type": "string", "description": "Free-text role or title the beneficial owner holds within the entity (e.g. `director`, `officer`, `partner`, `trustee`, `member`). No fixed set of values is enforced β€” send the title as it applies on your platform.", "example": "director" } }, "required": [ "name", "citizenship_code", "id_number_type", "id_number", "beneficial_owner", "kyc", "kyc_timestamp", "sanction_screening", "sanction_screening_timestamp" ] }, { "title": "Beneficial owner β€” All accepted fields (reference)", "description": "Every field accepted for a beneficial owner β€” a **documentation superset** showing the full surface, **not** a single valid request: the US (`tax_id`) and non-US (`id_number` / `id_number_type`) identifiers are mutually exclusive, and vendor `kyc` / `sanction_screening` results apply to the reliance track only.", "allOf": [ { "$ref": "#/components/schemas/BeneficialOwnerEntity" } ] } ] }, "BeneficialOwnerResponseEntity": { "type": "object", "properties": { "user_code": { "type": "string", "description": "zerohash identifier for the Beneficial Owner(s) (One code returned per person)", "example": "U-XXXXXX" }, "name": { "type": "string", "description": "Full name of the beneficial owner", "example": "John Smith" }, "email": { "type": "string", "description": "Email address of beneficial owner", "example": "test@example.com" }, "address_one": { "type": "string", "description": "First line for the beneficial owner's address.\n\nNotes:\n- The regular maximum length is 80 characters.\n- If the platform is on the vendor reliance track, the maximum length increases to 200 characters.\n- PO Box addresses are not accepted.", "example": "123 Main St." }, "address_two": { "type": "string", "description": "Extra information, like an apartment or suite number.\n\nNotes:\n- The regular maximum length is 50 characters.\n- If the platform is on the vendor reliance track, the maximum length increases to 200 characters.\n- PO Box addresses are not accepted.", "example": "Suite 1000" }, "city": { "type": "string", "description": "City of the beneficial owner", "example": "Chicago" }, "postal_code": { "type": "string", "description": "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", "example": "12345" }, "jurisdiction_code": { "type": "string", "example": "US-IL", "description": "The ISO 3166-2 subdivision code that the beneficial owner resides in" }, "date_of_birth": { "type": "string", "description": "Birth date of the beneficial owner", "example": "1985-09-02" }, "phone_number": { "type": "string", "description": "The phone number of the beneficial owner", "example": "+15557778888" }, "citizenship_code": { "type": "string", "example": "US", "description": "The ISO-3166-1 alpha2 citizenship of the beneficial owner, e.g. `US`.", "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", "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" ] }, "tax_id": { "type": "string", "description": "The national ID of the beneficial owner, e.g. a social security number. Required if `citizenship=United States` or `citizenship_code=US`. \nNote: if `citizenship=United States`, and `tax_id` begins with `9`, then `id_number_type` and `id_number` are also required.", "example": "123456789" }, "id_number_type": { "type": "string", "enum": [ "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" ], "description": "The type of identification number provided.\n\n**Allowed values:**\n- `us_drivers_license` - US Driver's License\n- `us_passport` - US Passport\n- `us_passport_card` - US Passport Card\n- `us_permanent_resident_card` - US Permanent Resident Card (Green Card)\n- `us_border_crossing_card` - US Border Crossing Card\n- `us_alien_card` - US Alien Registration Card\n- `us_id_card` - US State-issued ID Card\n- `non_us_passport` - Non-US Passport\n- `non_us_other` - Other Non-US identification (requires `non_us_other_type` field)\n- `passport` - Generic passport\n- `eu_drivers_license` - European Union Driver's License\n- `national_id` - National identity card\n- `legal_entity_identifier` - Legal Entity Identifier (LEI) for organizations\n- `chamber_of_commerce_number` - Chamber of Commerce registration number\n- `value_added_tax_number` - VAT identification number\n\n**Conditional requirements:**\n- When `id_number_type` is `non_us_other`, the `non_us_other_type` field is required.\n**Note:** Required when citizenship is not `United States` or `tax_id` is not an SSN.", "example": "us_passport" }, "id_number": { "type": "string", "description": "ID number of the ID document provided. \nRequired when citizenship is not `United States` or `tax_id` is not an SSN\t", "example": "123456789" }, "id_issuing_authority": { "type": "string", "description": "ISO-3166-1_A2 country code that issued the ID. Required if `id_number` is provided.", "example": "US" }, "sanction_screening": { "type": "string", "enum": [ "pass", "fail" ], "description": "Result of the beneficial owner's sanctions screening.\n\n**Allowed values:**\n- `pass` - Beneficial owner passed sanctions screening\n- `fail` - Beneficial owner failed sanctions screening", "example": "pass" }, "sanction_screening_timestamp": { "type": "number", "description": "UNIX timestamp (in milliseconds) when the sanctions screening was performed on the beneficial owner.", "example": 1603378501286 }, "kyc": { "type": "string", "enum": [ "pass", "fail" ], "description": "Whether the beneficial owner passed or failed KYC verification by vendor.\n\n**Allowed values:**\n- `pass` - KYC verification passed\n- `fail` - KYC verification failed", "example": "pass" }, "kyc_timestamp": { "type": "number", "description": "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.", "example": 1603378501286 }, "beneficial_owner": { "type": "number", "enum": [ 0, 1, 2 ], "description": "Designation of what percent of the business the beneficial owner owns.\n\n**Allowed values:**\n- `0` - Unknown\n- `1` - Greater than or equal to 10% but less than 25%\n- `2` - Greater than or equal to 25%", "example": 1 }, "role": { "type": "string", "description": "Free-text role or title the beneficial owner holds within the entity (e.g. `director`, `officer`, `partner`, `trustee`, `member`). No fixed set of values is enforced β€” send the title as it applies on your platform.", "example": "director" } } } } } } ```