---
title: "Create entity beneficiary"
method: POST
path: "/participants/entity-beneficiaries/new"
tags: ["Entity Participants"]
---

# Create entity beneficiary

`POST /participants/entity-beneficiaries/new`

## Request

- Base URL: `https://api.cert.zerohash.com`
- URL: `https://api.cert.zerohash.com/participants/entity-beneficiaries/new`
- Auth: API key in header `X-SCX-API-KEY` and API key in header `X-SCX-PASSPHRASE`

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._

## Headers

- `X-SCX-SIGNED` string, required
- `X-SCX-TIMESTAMP` string, required
- `X-Request-Id` string, uuid

## Request body

- PostEntityBeneficiariesBody
  - `legal_name` string, required: Registered legal name of the entity. This should not be a DBA or DBA equivalent
  - `contact_number` string, required: Phone number of the business
  - `address_one` string, required: First line for the business's address. Notes: - The regular maximum length is 80 characters. - If the platform is on the vendor reliance track, the maximum length increases to 200 characters. - PO Box addresses are not accepted.
  - `city` string, required: The city customer resides in
  - `postal_code` string, required: 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
  - `jurisdiction_code` string, required: The ISO 3166-2 subdivision code that the customer resides in
  - `tax_id` string, required: Tax identifier of the business (e.g. EIN in United States)
  - `id_issuing_authority` string, required: ISO-3166-1_A2 country code that issued the tax identifier (e.g. “US”)
  - `address_two` string: Extra information, like an apartment or suite number. Notes: - The regular maximum length is 50 characters. - If the platform is on the vendor reliance track, the maximum length increases to 200 characters. - PO Box addresses are not accepted.
  - `email` string
  - `id_number` string: The identification number of the entity (e.g. LEI, VAT number, chamber of commerce number).
  - `id_number_type` 'ein' | 'legal_entity_identifier' | 'chamber_of_commerce_number' | 'value_added_tax_number' | 'non_us_other': 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.
  - `non_us_other_type` string: Free-form description of the non-US entity ID type. Required when id_number_type is non_us_other.
  - `doing_business_as_name` string: The entity's trade name, if it operates under one different from legal_name.
  - `country_of_incorporation` string: ISO 3166-1 alpha-2 country code where the entity was incorporated.
  - `date_of_incorporation` string: Date the entity was incorporated, in YYYY-MM-DD format.
  - `company_registration_number` string: The entity's registration number with its jurisdiction's company/business registry.

## Response `201`

Successfully created entity beneficiary participant. Returns the created resource with generated IDs and timestamps.

- PostEntityBeneficiariesResponse
  - `message` object
    - `legal_name` string: Registered legal name of the entity. This should not be a DBA or DBA equivalent
    - `contact_number` string: Phone number of the business
    - `address_one` string: First line for the business's address. Notes: - The regular maximum length is 80 characters. - If the platform is on the vendor reliance track, the maximum length increases to 200 characters. - PO Box addresses are not accepted.
    - `city` string: The city customer resides in
    - `postal_code` string: Postal, or zip code, of the business, in the format "min 4 characters, no leading or trailing spaces" for non-US postal code or <5digits>-<4digits> for US zip code, e.g. 77777 or 77777-7777
    - `jurisdiction_code` string: The ISO 3166-2 subdivision code that the customer resides in
    - `tax_id` string: Tax identifier of the business (e.g. EIN in United States)
    - `id_issuing_authority` string: ISO-3166-1_A2 country code that issued the tax identifier (e.g. “US”)
    - `email` string
    - `platform_code` string
    - `participant_code` string
    - `status` string
    - `doing_business_as_name` string: The entity's trade name, if it operates under one different from legal_name.
    - `country_of_incorporation` string: ISO 3166-1 alpha-2 country code where the entity was incorporated.
    - `date_of_incorporation` string: Date the entity was incorporated, in YYYY-MM-DD format.
    - `company_registration_number` string: The entity's registration number with its jurisdiction's company/business registry.

## Other responses

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

## Changes

- **2026-11-03** `47cf70ae701c`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/zerohash/apis/zerohash-api/changes/participants/entity-beneficiaries/new/post.md)

---

[API](https://skmtc.dev/zerohash/apis/zerohash-api.md) - [All operations](https://skmtc.dev/zerohash/apis/zerohash-api/llms.txt) - [OpenAPI document](https://skmtc.dev/zerohash/apis/zerohash-api/revisions/47cf70ae701c?raw)