Create entity customer

post

https://api.cert.zerohash.com/participants/entity/new

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

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Tax Documentation & Implementation Guides

Use the appropriate implementation guide based on your entity type.

Foreign Entities

W-8 Implementation Guide (API)

US-Based Entities

W-9 Implementation Guide

Additional Resources

For more information on our tax policies, see:

Crypto Tax Overview

Body Params

Entity customer profile including business information, registration details, and beneficial owners

Corporation entity onboarding, including C-Corporation and S-Corporation tax classifications.

platform_code

string

required

zerohash platform code of the submitting platform

entity_name

string

required

Name of the business

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

website

string

required

Business website

date_established

string

required

Date the business was established. This should reflect government registration for the entity in the format YYYY-MM-DD

entity_type

string

enum

required

The type of business that is onboarding. Constrained to the values valid for this variant.

Allowed:

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.

address_two

string

Extra information, like an apartment or suite number.

Notes:

The regular maximum length is 50 characters.
If the platform is on the vendor reliance track, the maximum length increases to 200 characters.
PO Box addresses are not accepted.

city

string

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

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

risk_rating

string

enum

required

Risk assessed by the platform's vendor

Allowed:

onboarding_profile

string

enum

Onboarding profile used to determine the entity's KYC track. Optional. Defaults to 'kyc_track' when omitted.

Allowed:

sanction_screening

string

enum

required

Result of the business sanctions screen

Allowed:

sanction_screening_timestamp

number

required

The time the sanctions screen was done

self_certification_timestamp

number

The UNIX timestamp (in milliseconds) when the participant completed self-certification for DAC8 compliance. Mandatory for participants that are based in Europe.

metadata

signed_timestamp

number

required

The time at which the business accepted zerohash services agreements

signed_agreements

array of objects

The agreements signed by the entity. An array of agreement objects with region, type, and timestamp.

signed_agreements

submitter_email

string

required

Email of the person who completed the KYC application and agreed to terms

submitter_first_name

string

Submitter first name

submitter_last_name

string

Submitter last name

submitter_title

string

The title or honorific of the individual submitting the form (e.g., Mr., Ms., Dr.).

control_persons

array of objects

required

control_persons*

beneficial_owners

array of objects

required

beneficial_owners*

incorporation_address

object

Full address where the entity is incorporated

tax_residence

object

Tax residence address for the entity

tin_jurisdiction_reason

string

enum

Optional. Reason for the tax residence jurisdiction differing from the legal jurisdiction. Defaults to "unknown" if not provided.

Allowed:

additional_tax_residences

array of objects

length ≤ 25

Optional. Additional tax residences when the entity has tax obligations in multiple jurisdictions. Maximum 25 items.

additional_tax_residences

tin_jurisdiction_other

string

Optional. Free text explanation when tin_jurisdiction_reason is other

b_notice_receipt

boolean

Boolean flag indicating notice receipt status

is_w_form_certified

boolean

W9 form certification flag

w_form_certification

number

W form certification unix timestamp

physical_delivery

boolean

Physical delivery flag

signature

string

This field is used to capture the customer Entity entity_name as used on the W-form.

signature_timestamp

number

This field captures the timestamp at which the user signed their W-form, used in conjunction with the signature field.

payee_exemption

string

enum

Payee exemption code (1-13 or NONE)

fatca_reporting_exemption

string

enum

FATCA reporting exemption code (1-13 or NONE)

is_not_subject_backup_withholding

boolean

Backup withholding attestation flag. Required for customers onboarded to a US platform.

If the participant confirms they are not subject to backup withholding, this field should be set to true.
If the participant is subject to backup withholding, this field should be set to false.
This acts as a positive attestation that the participant confirms they are not subject to backup withholding.

dba_name

string

Doing Business As (DBA) name of the entity

other_entity_type

string

Other entity type description when entity_type is "other"

w8_ben_e

object

Wrapper sub-object holding W-8BEN-E tax certification data for a foreign (non-US) entity customer. Inherits all shared W-8 fields plus the entity-only fields below. Optional at the wrapper level.

mailing_address

object

Root-level object on both customer and entity payloads (form-agnostic; also reused by W-9). Send only when the participant's mailing address differs from their permanent (W-8BEN) or incorporation (W-8BEN-E) address.

merchant_category_code

string

ISO 18245 four-digit Merchant Category Code (MCC) that identifies the business activity of the entity. Accepted on entity create/update; zerohash derives merchant_category_code_category and merchant_category_code_classification from this value.

jurisdiction_code

string

required

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

Headers

X-SCX-SIGNED

string

required

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

X-SCX-TIMESTAMP

string

required

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

Responses

Tax Documentation & Implementation Guides

Foreign Entities

US-Based Entities

Additional Resources

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

400Bad Request

403Forbidden

404Not Found

500Internal Server Error

503Service Unavailable