ZEzerohash
Entity Participants

Create entity beneficiary

Changed on

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.

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

Headers

X-SCX-SIGNEDstring required

HMAC-SHA256 signature of the request, base64-encoded. See the Authentication guide for the exact signing formula.

X-SCX-TIMESTAMPstring required
Example:1678901234

Current Unix timestamp in seconds. Must be within 60 seconds of server time or the request is rejected.

X-Request-Idstring uuid

Optional client-supplied request ID used for tracing and idempotency. Must be a UUID v4. When omitted, zerohash generates one and returns it in the response X-Request-Id header.

Request body

legal_namestring required

Registered legal name of the entity. This should not be a DBA or DBA equivalent

contact_numberstring required

Phone number of the business

address_onestring 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.
citystring required

The city customer resides in

postal_codestring 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_codestring required

The ISO 3166-2 subdivision code that the customer resides in

tax_idstring required

Tax identifier of the business (e.g. EIN in United States)

id_issuing_authoritystring required

ISO-3166-1_A2 country code that issued the tax identifier (e.g. “US”)

address_twostring

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.
emailstring
id_numberstring

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_typestring

Free-form description of the non-US entity ID type. Required when id_number_type is non_us_other.

doing_business_as_namestring

The entity's trade name, if it operates under one different from legal_name.

country_of_incorporationstring

ISO 3166-1 alpha-2 country code where the entity was incorporated.

date_of_incorporationstring

Date the entity was incorporated, in YYYY-MM-DD format.

company_registration_numberstring

The entity's registration number with its jurisdiction's company/business registry.

Example request

{
  "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"
}

Response

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

Example response

{
  "message": {
    "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",
    "email": "test@example.com",
    "platform_code": "XXXXXX",
    "participant_code": "XXXXXX",
    "status": "approved",
    "doing_business_as_name": "Acme Trading",
    "country_of_incorporation": "FR",
    "date_of_incorporation": "1985-09-02",
    "company_registration_number": "12345679"
  }
}

Changes