Zero Hash Entity Participants API

openapi: 3.2.0
info:
  title: zerohash Entity Participants API
  description: '

    ### Authentication


    zerohash Uses HMAC SHA-256 verification to ensure the authenticity of API requests, follow instructions by link [https://docs.zerohash.com/reference/api-authentication](https://docs.zerohash.com/reference/api-authentication)


    <a href="/zh-swagger.json">Download zerohash OpenAPI Schema as JSON</a>

    '
  version: 1.7.0
servers:
- url: https://api.cert.zerohash.com
  description: Certification API server
security:
- apiKey: []
  apiPassphrase: []
tags:
- name: Entity Participants
  description: Create and Manage Entity Participants
paths:
  /participants/entity/new:
    post:
      tags:
      - Entity Participants
      summary: Create entity customer
      description: Submits an entity customer to be affiliated with your platform. Your platform will need to be configured properly before you can use this endpoint.
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      requestBody:
        description: Entity customer profile including business information, registration details, and beneficial owners
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostEntityBody'
            examples:
              corporation:
                summary: Corporation
                description: Corporation entity (includes C-Corporation and S-Corporation classifications).
                value:
                  platform_code: PLAT01
                  entity_name: Acme Holdings
                  legal_name: Acme Holdings Inc.
                  contact_number: '15557778888'
                  website: acme.com
                  date_established: '2015-04-12'
                  entity_type: corporation
                  address_one: 123 Main St.
                  address_two: Suite 1000
                  city: Chicago
                  postal_code: '60601'
                  jurisdiction_code: US-IL
                  tax_id: 12-3456789
                  id_issuing_authority: US
                  risk_rating: low
                  sanction_screening: pass
                  sanction_screening_timestamp: 1603378501286
                  signed_timestamp: 1603378501286
                  submitter_email: submitter@example.com
                  submitter_first_name: Jon
                  submitter_last_name: Doe
                  submitter_title: Director
                  control_persons:
                  - name: John Smith
                    email: john.smith@example.com
                    address_one: 123 Main St.
                    city: Chicago
                    postal_code: '60601'
                    jurisdiction_code: US-IL
                    date_of_birth: '1985-09-02'
                    phone_number: '15557778888'
                    citizenship_code: US
                  beneficial_owners:
                  - name: Jane Doe
                    email: jane.doe@example.com
                    address_one: 123 Main St.
                    city: Chicago
                    postal_code: '60601'
                    jurisdiction_code: US-IL
                    date_of_birth: '1980-01-15'
                    phone_number: '15557778899'
                    citizenship_code: US
              llc:
                summary: LLC
                description: Limited Liability Company (includes C/S/Partnership tax classifications).
                value:
                  platform_code: PLAT01
                  entity_name: Acme Ventures
                  legal_name: Acme Ventures LLC
                  contact_number: '15557778888'
                  website: acme.com
                  date_established: '2015-04-12'
                  entity_type: llc
                  address_one: 123 Main St.
                  address_two: Suite 1000
                  city: Chicago
                  postal_code: '60601'
                  jurisdiction_code: US-IL
                  tax_id: 12-3456789
                  id_issuing_authority: US
                  risk_rating: low
                  sanction_screening: pass
                  sanction_screening_timestamp: 1603378501286
                  signed_timestamp: 1603378501286
                  submitter_email: submitter@example.com
                  submitter_first_name: Jon
                  submitter_last_name: Doe
                  submitter_title: Director
                  control_persons:
                  - name: John Smith
                    email: john.smith@example.com
                    address_one: 123 Main St.
                    city: Chicago
                    postal_code: '60601'
                    jurisdiction_code: US-IL
                    date_of_birth: '1985-09-02'
                    phone_number: '15557778888'
                    citizenship_code: US
                  beneficial_owners:
                  - name: Jane Doe
                    email: jane.doe@example.com
                    address_one: 123 Main St.
                    city: Chicago
                    postal_code: '60601'
                    jurisdiction_code: US-IL
                    date_of_birth: '1980-01-15'
                    phone_number: '15557778899'
                    citizenship_code: US
              partnership:
                summary: Partnership
                description: Partnership entity.
                value:
                  platform_code: PLAT01
                  entity_name: Acme Partners
                  legal_name: Acme Partners LP
                  contact_number: '15557778888'
                  website: acme.com
                  date_established: '2015-04-12'
                  entity_type: partnership
                  address_one: 123 Main St.
                  address_two: Suite 1000
                  city: Chicago
                  postal_code: '60601'
                  jurisdiction_code: US-IL
                  tax_id: 12-3456789
                  id_issuing_authority: US
                  risk_rating: low
                  sanction_screening: pass
                  sanction_screening_timestamp: 1603378501286
                  signed_timestamp: 1603378501286
                  submitter_email: submitter@example.com
                  submitter_first_name: Jon
                  submitter_last_name: Doe
                  submitter_title: Director
                  control_persons:
                  - name: John Smith
                    email: john.smith@example.com
                    address_one: 123 Main St.
                    city: Chicago
                    postal_code: '60601'
                    jurisdiction_code: US-IL
                    date_of_birth: '1985-09-02'
                    phone_number: '15557778888'
                    citizenship_code: US
                  beneficial_owners:
                  - name: Jane Doe
                    email: jane.doe@example.com
                    address_one: 123 Main St.
                    city: Chicago
                    postal_code: '60601'
                    jurisdiction_code: US-IL
                    date_of_birth: '1980-01-15'
                    phone_number: '15557778899'
                    citizenship_code: US
              sole_proprietorship:
                summary: Sole Proprietorship
                description: Sole proprietorship entity.
                value:
                  platform_code: PLAT01
                  entity_name: Jon's Consulting
                  legal_name: Jonathan Doe
                  contact_number: '15557778888'
                  website: acme.com
                  date_established: '2015-04-12'
                  entity_type: sole_proprietorship
                  address_one: 123 Main St.
                  address_two: Suite 1000
                  city: Chicago
                  postal_code: '60601'
                  jurisdiction_code: US-IL
                  tax_id: 12-3456789
                  id_issuing_authority: US
                  risk_rating: low
                  sanction_screening: pass
                  sanction_screening_timestamp: 1603378501286
                  signed_timestamp: 1603378501286
                  submitter_email: submitter@example.com
                  submitter_first_name: Jon
                  submitter_last_name: Doe
                  submitter_title: Director
                  control_persons:
                  - name: John Smith
                    email: john.smith@example.com
                    address_one: 123 Main St.
                    city: Chicago
                    postal_code: '60601'
                    jurisdiction_code: US-IL
                    date_of_birth: '1985-09-02'
                    phone_number: '15557778888'
                    citizenship_code: US
                  beneficial_owners:
                  - name: Jane Doe
                    email: jane.doe@example.com
                    address_one: 123 Main St.
                    city: Chicago
                    postal_code: '60601'
                    jurisdiction_code: US-IL
                    date_of_birth: '1980-01-15'
                    phone_number: '15557778899'
                    citizenship_code: US
                  dba_name: Jon's Consulting
              non_profit:
                summary: Non-Profit
                description: Non-profit / not-for-profit entity.
                value:
                  platform_code: PLAT01
                  entity_name: Acme Foundation
                  legal_name: Acme Foundation
                  contact_number: '15557778888'
                  website: acme.com
                  date_established: '2015-04-12'
                  entity_type: non_profit
                  address_one: 123 Main St.
                  address_two: Suite 1000
                  city: Chicago
                  postal_code: '60601'
                  jurisdiction_code: US-IL
                  tax_id: 12-3456789
                  id_issuing_authority: US
                  risk_rating: low
                  sanction_screening: pass
                  sanction_screening_timestamp: 1603378501286
                  signed_timestamp: 1603378501286
                  submitter_email: submitter@example.com
                  submitter_first_name: Jon
                  submitter_last_name: Doe
                  submitter_title: Director
                  control_persons:
                  - name: John Smith
                    email: john.smith@example.com
                    address_one: 123 Main St.
                    city: Chicago
                    postal_code: '60601'
                    jurisdiction_code: US-IL
                    date_of_birth: '1985-09-02'
                    phone_number: '15557778888'
                    citizenship_code: US
                  beneficial_owners:
                  - name: Jane Doe
                    email: jane.doe@example.com
                    address_one: 123 Main St.
                    city: Chicago
                    postal_code: '60601'
                    jurisdiction_code: US-IL
                    date_of_birth: '1980-01-15'
                    phone_number: '15557778899'
                    citizenship_code: US
              trust_estate:
                summary: Trust / Estate
                description: Trust or estate entity.
                value:
                  platform_code: PLAT01
                  entity_name: Acme Family Trust
                  legal_name: Acme Family Trust
                  contact_number: '15557778888'
                  website: acme.com
                  date_established: '2015-04-12'
                  entity_type: trust_estate
                  address_one: 123 Main St.
                  address_two: Suite 1000
                  city: Chicago
                  postal_code: '60601'
                  jurisdiction_code: US-IL
                  tax_id: 12-3456789
                  id_issuing_authority: US
                  risk_rating: low
                  sanction_screening: pass
                  sanction_screening_timestamp: 1603378501286
                  signed_timestamp: 1603378501286
                  submitter_email: submitter@example.com
                  submitter_first_name: Jon
                  submitter_last_name: Doe
                  submitter_title: Director
                  control_persons:
                  - name: John Smith
                    email: john.smith@example.com
                    address_one: 123 Main St.
                    city: Chicago
                    postal_code: '60601'
                    jurisdiction_code: US-IL
                    date_of_birth: '1985-09-02'
                    phone_number: '15557778888'
                    citizenship_code: US
                  beneficial_owners:
                  - name: Jane Doe
                    email: jane.doe@example.com
                    address_one: 123 Main St.
                    city: Chicago
                    postal_code: '60601'
                    jurisdiction_code: US-IL
                    date_of_birth: '1980-01-15'
                    phone_number: '15557778899'
                    citizenship_code: US
              other:
                summary: Other
                description: Any other supported entity type. Use `other_entity_type` to describe the entity.
                value:
                  platform_code: PLAT01
                  entity_name: Acme Cooperative
                  legal_name: Acme Cooperative
                  contact_number: '15557778888'
                  website: acme.com
                  date_established: '2015-04-12'
                  entity_type: other
                  address_one: 123 Main St.
                  address_two: Suite 1000
                  city: Chicago
                  postal_code: '60601'
                  jurisdiction_code: US-IL
                  tax_id: 12-3456789
                  id_issuing_authority: US
                  risk_rating: low
                  sanction_screening: pass
                  sanction_screening_timestamp: 1603378501286
                  signed_timestamp: 1603378501286
                  submitter_email: submitter@example.com
                  submitter_first_name: Jon
                  submitter_last_name: Doe
                  submitter_title: Director
                  control_persons:
                  - name: John Smith
                    email: john.smith@example.com
                    address_one: 123 Main St.
                    city: Chicago
                    postal_code: '60601'
                    jurisdiction_code: US-IL
                    date_of_birth: '1985-09-02'
                    phone_number: '15557778888'
                    citizenship_code: US
                  beneficial_owners:
                  - name: Jane Doe
                    email: jane.doe@example.com
                    address_one: 123 Main St.
                    city: Chicago
                    postal_code: '60601'
                    jurisdiction_code: US-IL
                    date_of_birth: '1980-01-15'
                    phone_number: '15557778899'
                    citizenship_code: US
                  other_entity_type: Cooperative
      responses:
        '201':
          description: Successfully created entity participant. Returns the created resource with generated IDs and timestamps.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostEntityResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code400'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code403'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code404'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code500'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code503'
  /participants/entity/{participant_code}:
    patch:
      tags:
      - Entity Participants
      summary: Update entity customer
      description: Updates an entity customer affiliated with your platform. Your platform will need to be configured properly before you can use this endpoint.
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      - $ref: '#/components/parameters/ParticipantCodePath'
      requestBody:
        description: Updated entity customer fields (all fields optional, only send fields to update)
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchEntityBody'
      responses:
        '200':
          description: Successfully updated entity participant. Returns the updated resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PatchEntityResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code400'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code403'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code404'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code500'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code503'
  /participants/entity/{participant_code}/users/{user_code}:
    patch:
      tags:
      - Entity Participants
      summary: Update entity user
      description: 'Update one or more fields of an existing Entity user (Control Person, Beneficial Owner, or Board Member). This is a partial update endpoint - only the fields provided in the request body will be updated.


        **Important notes:**


        **Platform configuration:**

        - Your platform must be properly configured before using this endpoint.


        **PII changes and document requirements:**

        - When users are updated with new identifying information (such as `first_name`, `last_name`, `date_of_birth`, or `citizenship_code`), these changes must be accompanied by supporting documentation.

        - Use the Submit Documents endpoint with the appropriate document type to provide supporting documents.


        **Compliance field updates:**

        - Updating KYC-related fields (`sanction_screening`, `kyc`, `id_number_type`, etc.) may require re-verification depending on your platform configuration.

        - Changes to identity documents or verification status may trigger additional compliance checks.


        **Vendor reliance track:**

        - For platforms using vendor reliance track, `sanction_screening` and `kyc` fields must be provided with vendor verification results.

        - `sanction_screening_timestamp` and `kyc_timestamp` should be set to the time when the vendor completed the verification (in milliseconds since Unix epoch).


        **Conditional requirements:**

        - If `id_number_type` is `non_us_other`, the `non_us_other_type` field is required to describe the ID type.

        - For non-US citizens or when `tax_id` is an ITIN (begins with 9), `id_number_type` and `id_number` are required.


        **Response:**

        Returns the complete user object with all fields, including unchanged fields and system-generated metadata.'
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      - $ref: '#/components/parameters/ParticipantCodePath'
      - name: user_code
        in: path
        description: Unique identifier related to the user
        required: true
        schema:
          type: string
      requestBody:
        description: Updated entity user fields (all fields optional, only send fields to update)
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchUserBody'
      responses:
        '200':
          description: Successfully updated entity user. Returns the updated resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PatchUserResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code400'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code403'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code404'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code500'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code503'
  /participants/entity/documents:
    post:
      tags:
      - Entity Participants
      summary: Submit entity documents
      description: 'Submits a business document on behalf of an entity, or an identity document on behalf of a control person or a beneficial owner of the entity, if you operate a platform on zerohash.


        **EU NNP onboarding.** For an entity onboarded through an EU-region platform, the required document set is `lei_certificate`, `excerpt_of_the_chamber_of_commerce`, `annual_accounts`, and `power_of_authorization` (a power of attorney or a board resolution authorising the submitter). When the entity was created with `is_complex_structure: true`, a `legal_opinion` document is additionally required before the entity can be approved. Any document without a dedicated type can be uploaded as `supporting_document` with a free-text `document_description`.'
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      requestBody:
        description: Entity document metadata including participant code, document type, user code (if applicable), and base64-encoded file data
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostEntityDocumentsBody'
      responses:
        '201':
          description: Successfully created entity document. Returns the created resource with generated IDs and timestamps.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostEntityDocumentsResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code400'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code403'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code404'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code500'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code503'
  /participant/{participant_code}/basic_info/cp_bo:
    get:
      tags:
      - Entity Participants
      summary: Get participant user basic info
      description: This endpoint returns Participant User basic info.
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      - $ref: '#/components/parameters/ParticipantCodePath'
      responses:
        '200':
          description: Successfully retrieved participant user (CPBO) basic information. Including name, role, and contact details for controlling persons and beneficial owners.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetParticipantCPBOBasicInfoResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code400'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code403'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code404'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code500'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code503'
  /participant/{participant_code}/sanction_screening_info/cp_bo:
    get:
      tags:
      - Entity Participants
      summary: Get participant user sanction screening info
      description: This endpoint returns Participant User sanction screening info.
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      - $ref: '#/components/parameters/ParticipantCodePath'
      responses:
        '200':
          description: Successfully retrieved participant user (CPBO) sanction screening information. Including screening status and compliance results for controlling persons and beneficial owners.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetParticipantCPBOSanctionScreeningInfoResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code400'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code403'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code404'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code500'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code503'
  /participant/{participant_code}/full_info/cp_bo:
    get:
      tags:
      - Entity Participants
      summary: Get participant user full info
      description: This endpoint returns Participant User full info.
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      - $ref: '#/components/parameters/ParticipantCodePath'
      responses:
        '200':
          description: Successfully retrieved participant user (CPBO) full information. Including all profile details, verification status, and compliance data for controlling persons and beneficial owners.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetParticipantCPBOFullInfoResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code400'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code403'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code404'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code500'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code503'
components:
  schemas:
    PatchEntityBody:
      type: object
      properties:
        entity_name:
          type: string
          description: Name of the business
          example: Entity Name
        legal_name:
          type: string
          description: Registered legal name of the entity. This should not be a DBA or DBA equivalent
          example: Legal Name
        contact_number:
          type: string
          description: Phone number of the business
          example: '15557778888'
        website:
          type: string
          description: Business website
          example: company.com
        date_established:
          type: string
          description: Date the business was established. This should reflect government registration for the entity in the format `YYYY-MM-DD`
          example: '1985-09-02'
        entity_type:
          type: string
          enum:
          - corporation
          - llc
          - partnership
          - sole_proprietorship
          - other
          - non_profit
          - llc_c
          - llc_s
          - llc_p
          - s_corporation
          - c_corporation
          - trust_estate
          - trust
          description: The type of business that is onboarding, must be one of the supported
          example: llc
        address_one:
          type: string
          description: '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.'
          example: 123 Main St.
        address_two:
          type: string
          description: '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.'
          example: Suite 1000
        city:
          type: string
          description: The city customer resides in
          example: Chicago
        postal_code:
          type: string
          description: 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
          example: '12345'
        tax_id:
          type: string
          description: Tax identifier of the business (e.g. EIN in United States)
          example: 000-00-0000
        id_issuing_authority:
          type: string
          description: ISO-3166-1_A2 country code that issued the tax identifier (e.g. “US”)
          example: null
        risk_rating:
          type: string
          enum:
          - low
          - medium
          - high
          description: Risk assessed by the platform's vendor
          example: null
        onboarding_profile:
          type: string
          enum:
          - kyc_track
          - shopper
          - originator_entity
          - payouts_payor_ultimate
          - payouts_beneficiary
          description: Onb

# --- truncated at 32 KB (297 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/zero-hash/refs/heads/main/openapi/zero-hash-entity-participants-api-openapi.yml