Accounts5

Assets2

Awards2

CLOB14

Convert and Withdraw3

Customer Accounts (MTA)14

Deposits16

Entity Participants8

Fund3

Index1

Individual Participants7

Liquidity4

Market Data6

Movements1

Participant Jurisdictions3

Payins5

Payments12

Payouts2

Positions3

Proof of Reserves3

Public1

Query Participants10

Rewards1

SDK Authorization2

Staking10

Trade Strategy16

Trades4

Transfers3

Travel Rule3

Virtual Accounts6

Withdrawals14

Entity Participants

Update entity customer

Changed on Nov 3, 2026

Update an entity customer affiliated with your platform. Your platform must be configured for this endpoint before use.

This is a partial update — send only the fields you want to change. All fields are optional. submitter_email is the email of the person or service making the change, used for audit. If omitted, the platform email is used.

💡 Use the Examples dropdown on the request body below to see common update scenarios (tax info, mailing address, adding people, W-8BEN-E, W-9 document generation, W-9 document upload, and more).

Adding vs. updating associated persons

Sending control_persons or beneficial_owners here adds new persons to the entity — it does not modify existing ones.
To update a person already attached to the entity (Control Person, Beneficial Owner, or Board Member), call PATCH /participants/entity/{participant_code}/users/{user_code} (PatchUserBody) with that person’s user_code.
Board members cannot be added or changed here — they are only accepted at creation time via POST /participants/entity/new.

patch/participants/entity/{participant_code}

Request

Base URL
https://api.cert.zerohash.com
URL
https://api.cert.zerohash.com/participants/entity/{participant_code}
Auth
API key in header X-SCX-API-KEY and API key in header X-SCX-PASSPHRASE

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

Example request

{
  "submitter_email": "updater@example.com",
  "tax_id": "000-00-0000",
  "tax_residence": {
    "jurisdiction_code": "PT-11"
  },
  "tin_jurisdiction_reason": "working_abroad",
  "additional_tax_residences": [
    {
      "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",
    "id_issuing_authority": "US",
    "risk_rating": "low",
    "onboarding_profile": "kyc_track",
    "sanction_screening": "pass",
    "sanction_screening_timestamp": 1603378501286,
    "self_certification_timestamp": 1667504636159,
    "signed_timestamp": 1603378501286,
    "signed_agreements": [
      {
        "type": "zhllc_user_agreement_v1",
        "region": "us",
        "signed_timestamp": 1603378501286
      }
    ],
    "expected_annual_volume": "over_500k",
    "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": "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"
      }
    ]
  }
}

Changes

Nov 3, 202647cf70ae701c Revision changes
- breaking
  the request's body type changed from object to no type
- warning
  removed the request property
- warning
  removed the request property
- warning
  removed the request property
- warning
  removed the request property
- warning
  removed the request property
- warning
  removed the request property
- warning
  removed the request property
- warning
  removed the request property
- warning
  removed the request property
- warning
  removed the request property
- warning
  removed the request property
- warning
  removed the request property
- warning
  removed the request property
- warning
  removed the request property
- warning
  removed the request property
- warning
  removed the request property
- warning
  removed the request property
- warning
  removed the request property
- warning
  removed the request property
- warning
  removed the request property
- warning
  removed the request property
- warning
  removed the request property
- warning
  removed the request property
- warning
  removed the request property
- warning
  removed the request property
- warning
  removed the request property
- warning
  removed the request property
- warning
  removed the request property
- warning
  removed the request property
- warning
  removed the request property
- warning
  removed the request property
- warning
  removed the request property
- warning
  removed the request property
- warning
  removed the request property
- warning
  removed the request property
- warning
  removed the request property
- warning
  removed the request property
- warning
  removed the request property
- warning
  removed the request property
- warning
  removed the request property
- warning
  removed the request property
- warning
  removed the request property
- warning
  removed the request property
- warning
  removed the request property
- warning
  removed the request property
- 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: Update tax information subschema #2: Update mailing address subschema #3: Add control person(s) subschema #4: Add beneficial owner(s) subschema #5: Add control person(s) + beneficial owner(s) subschema #6: Add signed agreements subschema #7: Update W-8BEN-E tax certification (foreign entity) subschema #8: Update W-9 tax certification — document generation (US entity) subschema #9: Update W-9 tax certification — document upload (US entity) subschema #10: Update mailing address without submitter_email subschema #11: All accepted fields (reference) 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

Operation history