ZEzerohash
Individual Participants

Create customer

Changed on

Submit an individual participant to the zerohash ecosystem. This is the single entry point for onboarding a natural-person customer — regardless of how they will use the platform (trading, settlement, shoppers, payouts, and so on). zerohash runs the required identity, KYC, and compliance screening on the submitted profile and returns a participant_code that identifies the customer across all other endpoints.

Available only to platforms leveraging zerohash for customer onboarding. Contact us for more information on enabling it.

The variants below are sample requests, not rigid schemas. They illustrate common onboarding flows so you can start from the closest match — but the exact fields you send depend on your platform configuration, region, and participant type. Many platforms have their own flow and combine fields drawn from the Customer - All accepted fields variant, which lists the full superset of everything this endpoint accepts. Treat the samples as a starting point rather than an exhaustive or one-size-fits-all list.

💡 Use the Examples dropdown on the request body to load a ready-made payload for a flow, then add or remove fields to fit your integration.

post/participants/customers/new

Request

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

Example request

{
  "first_name": "John",
  "middle_name": "Middle",
  "last_name": "Smith",
  "email": "test@example.com",
  "phone_number": "+15557778888",
  "place_of_birth": {
    "country_code": "NL",
    "place_name": "Amsterdam"
  },
  "date_of_birth": "1985-09-02",
  "address_one": "123 Main St.",
  "address_two": "Suite 1000",
  "city": "Chicago",
  "postal_code": "12345",
  "tax_id": "123456789",
  "id_number": "123456789",
  "id_issuing_date": "2020-12-16",
  "id_expiration_date": "2026-12-25",
  "signed_timestamp": 1603378501286,
  "sanction_screening_timestamp": 1603378501286,
  "jurisdiction_code": "DE-BE",
  "kyc": "pass",
  "kyc_timestamp": 1603378501286,
  "sanction_screening": "pass",
  "idv": "pass",
  "liveness_check": "pass",
  "employment_status": "full_time",
  "industry": "adult_entertainment",
  "source_of_funds": "salary",
  "salary": "under_3500",
  "savings_and_investments": "under_10000",
  "tx_equivalent_annual_volume": "25k_to_100k",
  "tx_frequency_of_use": "up_to_12",
  "tx_type_of_service": [
    "buy_crypto",
    "sell_crypto"
  ],
  "tx_relationship_term_with_service": "long_term",
  "tx_relationship_term_with_service_other_explanation": "some free form explanation here in case of other type of tx_relationship_term_with_service",
  "signed_agreements": [
    {
      "type": "user_agreement",
      "region": "eu",
      "signed_timestamp": 1603378501286
    }
  ],
  "self_certification_timestamp": 1667504636159,
  "tax_residence": {
    "jurisdiction_code": "PT-11"
  },
  "tin_jurisdiction_reason": "working_abroad",
  "proof_of_address_coordinates": {
    "latitude": "N 51d 30.000000m 40.190000",
    "longitude": "W 0d 4.100000m 59.940000"
  },
  "metadata": {}
}

Response

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

Example response

{
  "message": {
    "first_name": "John",
    "middle_name": "Middle",
    "last_name": "Smith",
    "former_name": "Whale",
    "email": "test@example.com",
    "phone_number": "+15557778888",
    "address_one": "123 Main St.",
    "address_two": "Suite 1000",
    "country": "USA",
    "city": "Chicago",
    "zip": "12345",
    "postal_code": "12345",
    "jurisdiction_code": "US-IL",
    "citizenship_code": "US",
    "date_of_birth": "1985-09-02",
    "tax_id": "123456789",
    "id_number_type": "us_passport",
    "id_number": "123456789",
    "signed_timestamp": 1603378501286,
    "metadata": {},
    "kyc": "pass",
    "kyc_timestamp": 1603378501286,
    "onboarding_profile": "kyc_track",
    "onboarded_location": "US-FL",
    "sanction_screening": "pass",
    "sanction_screening_timestamp": 1603378501286,
    "idv": "pass",
    "liveness_check": "pass",
    "employment_status": "full_time",
    "industry": "adult_entertainment",
    "source_of_funds": "salary",
    "signed_agreements": [
      {
        "type": "user_agreement",
        "region": "us",
        "signed_timestamp": 1603378501286
      }
    ],
    "salary": "under_3500",
    "savings_and_investments": "under_10000",
    "investor_category": "restricted",
    "distribution_channel": "XYZ",
    "ip_address": "10.132.5.50",
    "place_of_birth": {
      "country_code": "NL",
      "place_name": "Amsterdam"
    },
    "id_expiration_date": "2026-12-25",
    "id_issuing_date": "2020-12-16",
    "tx_equivalent_annual_volume": "25k_to_100k",
    "tx_frequency_of_use": "up_to_12",
    "tx_type_of_service": [
      "buy_crypto",
      "sell_crypto"
    ],
    "tx_relationship_term_with_service": "long_term",
    "tx_relationship_term_with_service_other_explanation": "some free form explanation here in case of other type of tx_relationship_term_with_service",
    "gender": "male",
    "purpose_of_transactions": "payments_personal",
    "purpose_of_transactions_other_explanation": "some free form explanation here in case of other type of purpose_of_transactions",
    "expected_monthly_transaction_count": "between_11_and_100",
    "expected_usd_equivalent_daily_volume": "between_1001_and_10000",
    "gross_annual_salary_amount": "10000",
    "self_certification_timestamp": 1667504636159,
    "tax_residence": {
      "jurisdiction_code": "PT-11"
    },
    "tin_jurisdiction_reason": "working_abroad",
    "additional_tax_residences": [
      {
        "jurisdiction_code": "US-IL"
      }
    ],
    "proof_of_address_coordinates": {
      "latitude": "51.511164",
      "longitude": "-0.083317"
    },
    "is_w_form_certified": true,
    "w_form_certification": 1667504636159,
    "signature": "John Doe",
    "signature_timestamp": 1667504636159,
    "payee_exemption": "NONE",
    "fatca_reporting_exemption": "NONE",
    "is_not_subject_backup_withholding": true,
    "platform_code": "XXXXXX",
    "participant_code": "XXXXXX",
    "status": "approved"
  }
}

Changes

  • 47cf70ae701cRevision changes
    • breaking

      removed subschema #1: EU Customer subschema #2: US Customer - Reliance subschema #3: Non-US Citizen Customer - Reliance subschema #4: Partially Onboarded Participant subschema #5: Customer - All accepted fields from the request body oneOf list

    • breaking

      added subschema #3: Non-US Customer - Reliance subschema #4: EU Customer - Reliance to the response property oneOf list for the response status

    • 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 virtual_accounts 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: EU Customer - Reliance subschema #2: US Customer - Reliance subschema #3: Non-US Customer - Reliance subschema #4: Perishable Shopper tier 1 subschema #5: Transferable Shopper tier 1 subschema #6: Transferable Shopper tier 2 subschema #7: Transferable Shopper tier 3 subschema #8: Transferable Shopper tier 4 subschema #9: Non-Transferable Shopper tier 1 subschema #10: Non-Transferable Shopper tier 2 subschema #11: Non-Transferable Shopper tier 3 subschema #12: Non-Transferable Shopper tier 4 subschema #13: Customer - All accepted fields to the request body anyOf list

    • info

      response property message/oneOf[subschema #1: Customer - All accepted fields]/b_notice_receipt deprecated

    • info

      response property message/oneOf[subschema #1: Customer - All accepted fields]/fatca_reporting_exemption deprecated

    • info

      response property message/oneOf[subschema #1: Customer - All accepted fields]/is_w_form_certified deprecated

    • info

      response property message/oneOf[subschema #1: Customer - All accepted fields]/payee_exemption deprecated

    • info

      response property message/oneOf[subschema #1: Customer - All accepted fields]/signature deprecated

    • info

      response property message/oneOf[subschema #1: Customer - All accepted fields]/w_form_certification deprecated

    • 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

    • info

      removed subschema #3: Non-US Citizen Customer - Reliance subschema #4: EU Customer from the response property oneOf list for the response status