--- updatedAt: 2026-09-08T17:34:00.000Z agentTools: projectIndex: https://docs.zerohash.com/llms.txt --- # Create entity beneficiary Submit a **non-natural-person (business) beneficiary** to the zerohash ecosystem, a legal entity that receives payouts through your platform. zerohash runs the required business and returns a `participant_code` used to reference the beneficiary across all other endpoints. _Available only to platforms leveraging zerohash for beneficiary services. Contact us for more information on enabling it._ # 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-beneficiaries/new": { "post": { "tags": [ "Entity Participants" ], "summary": "Create entity beneficiary", "description": "Submit a **non-natural-person (business) beneficiary** to the zerohash ecosystem, a legal entity that receives payouts through your platform. zerohash runs the required business and returns a `participant_code` used to reference the beneficiary across all other endpoints.\n\n_Available only to platforms leveraging zerohash for beneficiary services. Contact us for more information on enabling it._", "parameters": [ { "$ref": "#/components/parameters/Signature" }, { "$ref": "#/components/parameters/Timestamp" }, { "$ref": "#/components/parameters/RequestId" } ], "requestBody": { "description": "Entity beneficiary profile data including business information and registration details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostEntityBeneficiariesBody" } } } }, "responses": { "201": { "description": "Successfully created entity beneficiary participant. Returns the created resource with generated IDs and timestamps.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostEntityBeneficiariesResponse" } } } }, "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" } }, "RequestId": { "name": "X-Request-Id", "in": "header", "description": "Optional client-supplied request ID used for tracing and idempotency. Must be a [UUID v4](https://www.uuidtools.com/uuid-versions-explained#version-4). When omitted, zerohash generates one and returns it in the response `X-Request-Id` header.", "required": false, "schema": { "type": "string", "format": "uuid" } } }, "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" } } }, "PostEntityBeneficiariesBody": { "type": "object", "properties": { "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" }, "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." }, "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" }, "jurisdiction_code": { "type": "string", "example": "US-IL", "description": "The ISO 3166-2 subdivision code that the customer resides in" }, "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" }, "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" }, "email": { "type": "string", "example": "test@example.com" }, "id_number": { "type": "string", "description": "The identification number of the entity (e.g. LEI, VAT number, chamber of commerce number).", "example": "549300TRWGQX5XMHYZ82" }, "id_number_type": { "type": "string", "enum": [ "ein", "legal_entity_identifier", "chamber_of_commerce_number", "value_added_tax_number", "non_us_other" ], "description": "The type of identification provided for the entity. Entity-valid types only: ein (US), legal_entity_identifier / chamber_of_commerce_number / value_added_tax_number (EU), or non_us_other (other non-US jurisdictions). non_us_other_type is required when non_us_other.", "example": "non_us_other" }, "non_us_other_type": { "type": "string", "description": "Free-form description of the non-US entity ID type. Required when id_number_type is non_us_other.", "example": "Handelsregister" }, "doing_business_as_name": { "type": "string", "description": "The entity's trade name, if it operates under one different from legal_name.", "example": "Acme Trading" }, "country_of_incorporation": { "type": "string", "description": "ISO 3166-1 alpha-2 country code where the entity was incorporated.", "example": "FR" }, "date_of_incorporation": { "type": "string", "description": "Date the entity was incorporated, in YYYY-MM-DD format.", "example": "1985-09-02" }, "company_registration_number": { "type": "string", "description": "The entity's registration number with its jurisdiction's company/business registry.", "example": "12345679" } }, "required": [ "legal_name", "contact_number", "address_one", "city", "postal_code", "jurisdiction_code", "tax_id", "id_issuing_authority" ], "example": { "legal_name": "Legal Name", "contact_number": "+15557778888", "address_one": "123 Main St.", "city": "Chicago", "postal_code": "12345", "jurisdiction_code": "US-IL", "tax_id": "000-00-0000", "id_issuing_authority": "US" } }, "PostEntityBeneficiariesResponse": { "type": "object", "properties": { "message": { "type": "object", "properties": { "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" }, "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." }, "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" }, "jurisdiction_code": { "type": "string", "example": "US-IL", "description": "The ISO 3166-2 subdivision code that the customer resides in" }, "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" }, "email": { "type": "string", "example": "test@example.com" }, "platform_code": { "type": "string", "example": "XXXXXX" }, "participant_code": { "type": "string", "example": "XXXXXX" }, "status": { "type": "string", "example": "approved" }, "doing_business_as_name": { "type": "string", "description": "The entity's trade name, if it operates under one different from legal_name.", "example": "Acme Trading" }, "country_of_incorporation": { "type": "string", "description": "ISO 3166-1 alpha-2 country code where the entity was incorporated.", "example": "FR" }, "date_of_incorporation": { "type": "string", "description": "Date the entity was incorporated, in YYYY-MM-DD format.", "example": "1985-09-02" }, "company_registration_number": { "type": "string", "description": "The entity's registration number with its jurisdiction's company/business registry.", "example": "12345679" } } } } } } } } ```