ZEzerohash
Entity Participants

Create entity customer

Changed on

Submit an entity (business) participant to the zerohash ecosystem. Use this to onboard a legal entity — corporation, LLC, partnership, sole proprietorship, non-profit, trust/estate, and so on — along with its control persons and beneficial owners. zerohash runs the required business verification (KYB), identity, and compliance screening and returns a participant_code that identifies the entity across all other endpoints.

Your platform must be configured for this endpoint before use. Contact us for more information.

The variants below are sample requests, not rigid schemas. They illustrate common entity types and regions so you can start from the closest match — the exact fields you send depend on your platform configuration, region, and entity type. See the all-accepted-fields reference for the full superset this endpoint accepts.

💡 Use the Examples dropdown on the request body to load a ready-made payload for an entity type.

post/participants/entity/new

Request

  • Base URL
    https://api.cert.zerohash.com
  • URL
    https://api.cert.zerohash.com/participants/entity/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.

Request body

OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR
OR

Example request

{
  "platform_code": "PLAT01",
  "entity_name": "Entity Name",
  "legal_name": "Legal Name",
  "contact_number": "+15557778888",
  "website": "company.com",
  "date_established": "1985-09-02",
  "entity_type": "corporation",
  "address_one": "123 Main St.",
  "address_two": "Suite 1000",
  "city": "Chicago",
  "postal_code": "12345",
  "tax_id": "000-00-0000",
  "id_issuing_authority": "US",
  "onboarding_profile": "kyc_track",
  "self_certification_timestamp": 1667504636159,
  "metadata": {},
  "signed_timestamp": 1603378501286,
  "signed_agreements": [
    {
      "type": "zhllc_user_agreement_v1",
      "region": "us",
      "signed_timestamp": 1603378501286
    }
  ],
  "submitter_email": "test@example.com",
  "submitter_first_name": "Jon",
  "submitter_last_name": "Doe",
  "submitter_title": "Mr.",
  "control_persons": [
    {
      "name": "John Smith",
      "email": "test@example.com",
      "address_one": "123 Main St.",
      "address_two": "Suite 1000",
      "city": "Chicago",
      "postal_code": "12345",
      "jurisdiction_code": "US-IL",
      "date_of_birth": "1985-09-02",
      "phone_number": "+15557778888",
      "citizenship_code": "US",
      "tax_id": "123456789",
      "control_person": 1
    }
  ],
  "beneficial_owners": [
    {
      "name": "John Smith",
      "email": "test@example.com",
      "address_one": "123 Main St.",
      "address_two": "Suite 1000",
      "city": "Chicago",
      "postal_code": "12345",
      "jurisdiction_code": "US-IL",
      "date_of_birth": "1985-09-02",
      "phone_number": "+15557778888",
      "citizenship_code": "US",
      "tax_id": "123456789",
      "beneficial_owner": 1,
      "role": "director"
    }
  ],
  "incorporation_address": {
    "jurisdiction_code": "IT-25"
  },
  "tax_residence": {
    "jurisdiction_code": "PT-11"
  },
  "tin_jurisdiction_reason": "working_abroad",
  "additional_tax_residences": [
    {
      "jurisdiction_code": "US-IL"
    }
  ],
  "tin_jurisdiction_other": "Jurisdiction does not issue TINs",
  "b_notice_receipt": true,
  "is_w_form_certified": true,
  "w_form_certification": 1667504636159,
  "signature": "signature_data",
  "signature_timestamp": 1667504636159,
  "payee_exemption": "NONE",
  "fatca_reporting_exemption": "NONE",
  "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",
      "requirements_certification": true,
      "limitation_on_benefits": "publicly_traded_corporation"
    }
  },
  "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",
  "chamber_of_commerce_number": "KVK-12345678",
  "activity_locations": [
    "DE",
    "NL",
    "FR"
  ],
  "entity_source_of_funds": "operating_revenues",
  "entity_source_of_funds_description": "Revenue from proprietary trading algorithms",
  "entity_sub_type": "trust_llc",
  "declaration_no_effective_control": true,
  "declaration_no_effective_control_at": 1603378501286,
  "declaration_no_foreseeable_changes": true,
  "declaration_no_foreseeable_changes_at": 1603378501286,
  "reason_for_business_relationship": "Digital asset custody and trading services for institutional clients",
  "board_members": [
    {
      "first_name": "John",
      "middle_name": "A",
      "last_name": "Smith",
      "name": "John Smith",
      "email": "test@example.com",
      "address_one": "123 Main St.",
      "address_two": "Suite 1000",
      "city": "Chicago",
      "postal_code": "12345",
      "jurisdiction_code": "US-IL",
      "date_of_birth": "1985-09-02",
      "place_of_birth_name": "Chicago",
      "place_of_birth_country_code": "US",
      "citizenship_code": "US",
      "tax_id": "123456789",
      "id_number_type": "us_passport",
      "id_number": "123456789",
      "id_issuing_authority": "US"
    }
  ],
  "expected_annual_volume": "over_500k",
  "id_number_type": "non_us_other",
  "id_number": "549300TRWGQX5XMHYZ82",
  "non_us_other_type": "Handelsregister",
  "jurisdiction_code": "US-IL"
}

Response

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

Example response

{
  "message": {
    "platform_code": "PLAT01",
    "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,
    "metadata": {},
    "signed_timestamp": 1603378501286,
    "signed_agreements": [
      {
        "type": "zhllc_user_agreement_v1",
        "region": "us",
        "signed_timestamp": 1603378501286
      }
    ],
    "submitter_email": "test@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",
    "b_notice_receipt": true,
    "is_w_form_certified": true,
    "w_form_certification": 1667504636159,
    "signature": "signature_data",
    "signature_timestamp": 1667504636159,
    "payee_exemption": "NONE",
    "fatca_reporting_exemption": "NONE",
    "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",
        "requirements_certification": true,
        "limitation_on_benefits": "publicly_traded_corporation"
      }
    },
    "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",
    "control_persons": [
      {
        "user_code": "U-XXXXXX",
        "name": "John Smith",
        "email": "test@example.com",
        "address_one": "123 Main St.",
        "address_two": "Suite 1000",
        "city": "Chicago",
        "postal_code": "12345",
        "jurisdiction_code": "US-IL",
        "date_of_birth": "1985-09-02",
        "phone_number": "+15557778888",
        "citizenship_code": "US",
        "tax_id": "123456789",
        "id_number_type": "us_passport",
        "id_number": "123456789",
        "id_issuing_authority": "US",
        "sanction_screening": "pass",
        "sanction_screening_timestamp": 1603378501286,
        "kyc": "pass",
        "kyc_timestamp": 1603378501286,
        "control_person": 1
      }
    ],
    "beneficial_owners": [
      {
        "user_code": "U-XXXXXX",
        "name": "John Smith",
        "email": "test@example.com",
        "address_one": "123 Main St.",
        "address_two": "Suite 1000",
        "city": "Chicago",
        "postal_code": "12345",
        "jurisdiction_code": "US-IL",
        "date_of_birth": "1985-09-02",
        "phone_number": "+15557778888",
        "citizenship_code": "US",
        "tax_id": "123456789",
        "id_number_type": "us_passport",
        "id_number": "123456789",
        "id_issuing_authority": "US",
        "sanction_screening": "pass",
        "sanction_screening_timestamp": 1603378501286,
        "kyc": "pass",
        "kyc_timestamp": 1603378501286,
        "beneficial_owner": 1,
        "role": "director"
      }
    ],
    "participant_code": "XXXXXX",
    "status": "approved"
  }
}

Changes

  • 47cf70ae701cRevision changes
    • breaking

      removed subschema #1: Corporation subschema #2: LLC subschema #3: Partnership subschema #4: Sole Proprietorship subschema #5: Non-Profit subschema #6: Trust / Estate subschema #7: Other subschema #8: Entity - All accepted fields from the request body oneOf list

    • warning

      added the new A enum value to the / response property for the response status

    • warning

      added the new B enum value to the / response property for the response status

    • warning

      added the new C enum value to the / response property for the response status

    • warning

      added the new D enum value to the / response property for the response status

    • warning

      added the new E enum value to the / response property for the response status

    • warning

      added the new F enum value to the / response property for the response status

    • warning

      added the new G enum value to the / response property for the response status

    • warning

      added the new H enum value to the / response property for the response status

    • warning

      added the new I enum value to the / response property for the response status

    • warning

      added the new J enum value to the / response property for the response status

    • warning

      added the new K enum value to the / response property for the response status

    • warning

      added the new L enum value to the / response property for the response status

    • warning

      added the new M enum value to the / response property for the response status

    • warning

      added the new trust enum value to the / response property for the response status

    • warning

      added the new virtual_accounts enum value to the /// response property for the response status

    • info

      added subschema #1: US - Corporation subschema #2: US - LLC subschema #3: US - Partnership subschema #4: US - Sole Proprietorship subschema #5: US - Non-Profit subschema #6: US - Trust / Estate subschema #7: US - Other subschema #8: US - Corporation - Shared Vendor Reliance subschema #9: US - LLC - Shared Vendor Reliance subschema #10: US - Partnership - Shared Vendor Reliance subschema #11: US - Sole Proprietorship - Shared Vendor Reliance subschema #12: US - Non-Profit - Shared Vendor Reliance subschema #13: US - Trust / Estate - Shared Vendor Reliance subschema #14: US - Other - Shared Vendor Reliance subschema #15: EU - Corporation subschema #16: EU - LLC subschema #17: EU - Partnership subschema #18: EU - Sole Proprietorship subschema #19: EU - Non-Profit subschema #20: EU - Trust / Estate subschema #21: EU - Other subschema #22: Entity - All accepted fields to the request body anyOf list

    • info

      added the optional property / to the response with the status

    • info

      removed the 1 enum value from the / response property for the response status

    • info

      removed the 10 enum value from the / response property for the response status

    • info

      removed the 11 enum value from the / response property for the response status

    • info

      removed the 12 enum value from the / response property for the response status

    • info

      removed the 13 enum value from the / response property for the response status

    • info

      removed the 2 enum value from the / response property for the response status

    • info

      removed the 3 enum value from the / response property for the response status

    • info

      removed the 4 enum value from the / response property for the response status

    • info

      removed the 5 enum value from the / response property for the response status

    • info

      removed the 6 enum value from the / response property for the response status

    • info

      removed the 7 enum value from the / response property for the response status

    • info

      removed the 8 enum value from the / response property for the response status

    • info

      removed the 9 enum value from the / response property for the response status