Sign in

v1

latestOpenAPI 3.1.02026-07-241653251.3 MB
Entity Participants

Update entity customer

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

patch/participants/entity/{participant_code}

Path parameters

participant_codestring required
Example:ABCDEF

Unique participant identifier. Always 6 uppercase alphanumeric characters.

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

entity_namestring

Name of the business

legal_namestring

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

contact_numberstring

Phone number of the business

websitestring

Business website

date_establishedstring

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

entity_type'corporation' | 'llc' | 'partnership' | 'sole_proprietorship' | 'other' | 'non_profit' | 'llc_c' | 'llc_s' | 'llc_p' | 's_corporation' | 'c_corporation' | 'trust_estate'

The type of business that is onboarding, must be one of the supported

address_onestring

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

The city customer resides in

postal_codestring

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_idstring

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

id_issuing_authoritystring

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

risk_rating'low' | 'medium' | 'high'

Risk assessed by the platform's vendor

onboarding_profile'kyc_track' | 'shopper' | 'originator_entity' | 'payouts_payor_ultimate' | 'payouts_beneficiary'

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

sanction_screening'pass' | 'fail'

Result of the business sanctions screen

sanction_screening_timestampnumber

The time the sanctions screen was done

self_certification_timestampnumber

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

signed_timestampnumber

The time at which the business accepted zerohash services agreements

submitter_emailstring required

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

submitter_first_namestring

Submitter first name

submitter_last_namestring

Submitter last name

submitter_titlestring

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

tin_jurisdiction_reason'working_abroad' | 'studying_abroad' | 'dual_residency' | 'business_abroad' | 'real_estate_abroad' | 'other'

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

tin_jurisdiction_otherstring

Optional. Free text explanation when tin_jurisdiction_reason is other

b_notice_receiptboolean

Boolean flag indicating notice receipt status

is_w_form_certifiedboolean

W9 form certification flag

w_form_certificationnumber

W form certification unix timestamp

physical_deliveryboolean

Physical delivery flag

signaturestring

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

signature_timestampnumber

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

payee_exemption'1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | '10' | '11' | '12' | '13' | 'NONE'

Payee exemption code (1-13 or NONE)

fatca_reporting_exemption'1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | '10' | '11' | '12' | '13' | 'NONE'

FATCA reporting exemption code (1-13 or NONE)

is_not_subject_backup_withholdingboolean

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_namestring

Doing Business As (DBA) name of the entity

other_entity_typestring

Other entity type description when entity_type is "other"

merchant_category_codestring

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_codestring

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

Example request

{
  "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",
  "onboarding_profile": "kyc_track",
  "sanction_screening": "pass",
  "sanction_screening_timestamp": 1603378501286,
  "self_certification_timestamp": 1667504636159,
  "signed_timestamp": 1603378501286,
  "signed_agreements": [
    {
      "type": "user_agreement",
      "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",
  "additional_tax_residences": [
    {
      "jurisdiction_code": "US-IL"
    }
  ],
  "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": "000-00-0000",
      "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": [
    {
      "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": "000-00-0000",
      "id_number_type": "us_passport",
      "id_number": "123456789",
      "sanction_screening": "pass",
      "sanction_screening_timestamp": 1603378501286,
      "kyc": "pass",
      "kyc_timestamp": 1603378501286,
      "beneficial_owner": 1
    }
  ],
  "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",
  "jurisdiction_code": "US-IL"
}

Response

Successfully updated entity participant. Returns the updated resource.

Example response

{
  "message": {
    "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",
    "onboarding_profile": "kyc_track",
    "sanction_screening": "pass",
    "sanction_screening_timestamp": 1603378501286,
    "self_certification_timestamp": 1667504636159,
    "signed_timestamp": 1603378501286,
    "signed_agreements": [
      {
        "type": "user_agreement",
        "region": "us",
        "signed_timestamp": 1603378501286
      }
    ],
    "submitter_email": "test@example.com",
    "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": "000-00-0000",
        "id_number_type": "us_passport",
        "id_number": "123456789",
        "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": "000-00-0000",
        "id_number_type": "us_passport",
        "id_number": "123456789",
        "sanction_screening": "pass",
        "sanction_screening_timestamp": 1603378501286,
        "kyc": "pass",
        "kyc_timestamp": 1603378501286,
        "beneficial_owner": 1
      }
    ]
  }
}