Zero Hash Individual Participants API

openapi: 3.2.0
info:
  title: zerohash Individual 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: Individual Participants
  description: Create and Manage Individual Participants
paths:
  /participants/customers/new:
    post:
      tags:
      - Individual Participants
      summary: Create customer
      description: 'Submits a customer to your platform.

        This endpoint is only available to certain participants leveraging zerohash for customer settlements. Please contact us for more information on enabling this endpoint.'
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      requestBody:
        description: Customer profile data including personal information, contact details, and KYC information
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostCustomersBody'
      responses:
        '201':
          description: Successfully created customer participant. Returns the created resource with generated IDs and timestamps.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostCustomersResponse'
        '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/documents:
    post:
      tags:
      - Individual Participants
      summary: Submit documents
      description: Submits a document on behalf of you or a customer if you operate a platform on zerohash.
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      requestBody:
        description: Document metadata including participant code, document type, and base64-encoded file data
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostDocumentsBody'
      responses:
        '201':
          description: Successfully created participant document. Returns the created resource with generated IDs and timestamps.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostDocumentsResponse'
        '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/customers/{participant_code}:
    patch:
      tags:
      - Individual Participants
      summary: Update customer
      description: 'Updates a customer of your platform.

        This endpoint is only available to certain participants leveraging zerohash for customer settlements. Please contact us for more information on enabling this endpoint.'
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      - $ref: '#/components/parameters/ParticipantCodePath'
      requestBody:
        description: Updated customer profile fields (all fields optional, only send fields to update)
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchCustomersBody'
      responses:
        '200':
          description: Successfully updated customer participant. Returns the updated resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PatchCustomersResponse'
        '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/customers/{participant_code}/lock:
    post:
      tags:
      - Individual Participants
      summary: Lock customer
      description: When platforms terminate a customer, they may alert zerohash through this endpoint.
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      - $ref: '#/components/parameters/ParticipantCodePath'
      requestBody:
        description: Lock reason and optional metadata for the customer termination
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LockCustomersBody'
      responses:
        '200':
          description: Successfully locked customer.
          content:
            text/plain:
              schema:
                type: string
                example: OK
        '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/beneficiaries/new:
    post:
      tags:
      - Individual Participants
      summary: Create beneficiary
      description: 'Submits a beneficiary to your platform.

        This endpoint is only available to certain participants leveraging zerohash for beneficiary services. Please contact us for more information on enabling this endpoint.'
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      - $ref: '#/components/parameters/RequestId'
      requestBody:
        description: Beneficiary profile data including personal information and contact details. When 'onboarding_profile' is 'payouts_beneficiary', either 'tax_id' or 'id_number'+'id_number_type' is required (both may be sent together).
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostBeneficiariesBody'
      responses:
        '201':
          description: Successfully created beneficiary participant. Returns the created resource with generated IDs and timestamps.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostBeneficiariesResponse'
        '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/beneficiaries/{participant_code}:
    patch:
      tags:
      - Individual Participants
      summary: Update beneficiary
      description: 'Updates a beneficiary from your platform.

        This endpoint is only available to certain participants leveraging zerohash for beneficiary services. Please contact us for more information on enabling this endpoint.'
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      - $ref: '#/components/parameters/RequestId'
      - $ref: '#/components/parameters/ParticipantCodePath'
      requestBody:
        description: Updated beneficiary fields (all fields optional, only send fields to update)
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchBeneficiariesBody'
      responses:
        '200':
          description: Successfully updated beneficiary participant. Returns the updated resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PatchBeneficiariesResponse'
        '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}/limits:
    patch:
      tags:
      - Individual Participants
      summary: Update participant limits
      description: Updates transaction limits for a participant. Allows platforms to configure custom limits by transaction type, time period, and asset. This endpoint is available when the platform is configured accordingly to use custom limits.
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      - $ref: '#/components/parameters/ParticipantCodePath'
      requestBody:
        description: Limit configuration for the participant
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchParticipantLimitsBody'
      responses:
        '200':
          description: Limits updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PatchParticipantLimitsResponse'
        '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:
    AdditionalTaxResidence:
      type: object
      required:
      - tax_id
      - jurisdiction_code
      properties:
        tax_id:
          type: string
          description: Tax identification number for the additional tax residence
        jurisdiction_code:
          type: string
          description: The ISO 3166-2 subdivision code that the participant resides in
          example: US-IL
    PostBeneficiariesResponse:
      type: object
      properties:
        message:
          type: object
          properties:
            first_name:
              type: string
              description: The first name of the customer being onboarded.
              example: John
            last_name:
              type: string
              description: The last name of the customer being onboarded.
              example: Smith
            email:
              type: string
              description: 'Customer email address, required.

                Note: zerohash will validate that the email is a correctly formatted `email`, and that the value is unique per-platform'
              example: test@example.com
            address_one:
              type: string
              description: 'First line for the customer''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 maximum length is `50` characters for platform using KYCaaS through zerohash.

                - If the platform is on the shared vendor reliance track, the maximum length increases to `200` characters.

                - PO Box addresses are not accepted.'
              example: Suite 1000
            jurisdiction_code:
              type: string
              description: The ISO 3166-2 subdivision code that the customer resides in. A full list of valid jurisdiction codes can be retrieved from the [`GET /jurisdictions/subdivisions` endpoint](https://docs.zerohash.com/reference/get_jurisdiction-subdivisions) passing a `country` parameter.
              example: US-IL
              enum:
              - US-AL
              - US-AK
              - US-AZ
              - US-AR
              - US-CA
              - US-CO
              - US-CT
              - US-DE
              - US-FL
              - US-GA
              - US-HI
              - US-ID
              - US-IL
              - US-IN
              - US-IA
              - US-KS
              - US-KY
              - US-LA
              - US-ME
              - US-MD
              - US-MA
              - US-MI
              - US-MN
              - US-MS
              - US-MO
              - US-MT
              - US-NE
              - US-NV
              - US-NH
              - US-NJ
              - US-NM
              - US-NY
              - US-NC
              - US-ND
              - US-OH
              - US-OK
              - US-OR
              - US-PA
              - US-RI
              - US-SC
              - US-SD
              - US-TN
              - US-TX
              - US-UT
              - US-VT
              - US-VA
              - US-WA
              - US-WV
              - US-WI
              - US-WY
              - US-DC
              - US-AS
              - US-GU
              - US-MP
              - US-PR
              - US-UM
              - US-VI
            city:
              type: string
              description: The city customer resides in.
              example: Chicago
            zip:
              type: string
              description: Zip code of the customer, required if `country` is `USA`, min 5 characters or `<5digits>-<4digits>`, no leading or trailing spaces", e.g. 77777 or 77777-7777.
              example: '12345'
            date_of_birth:
              type: string
              description: Date of birth of the customer in the format `YYYY-MM-DD`
              example: '1985-09-02'
            id_number_type:
              type: string
              enum:
              - us_drivers_license
              - us_passport
              - us_passport_card
              - us_permanent_resident_card
              - us_border_crossing_card
              - us_alien_card
              - us_id_card
              - non_us_passport
              - non_us_other
              - passport
              - eu_drivers_license
              - national_id
              - legal_entity_identifier
              - chamber_of_commerce_number
              - value_added_tax_number
              description: "The id number type field is required when; \n - `citizenship` is not `US`\n - `citizenship=US` and `tax_id` starts with `9` (is an ITIN, a 9-digit US ID that begins with the number 9).\nPassport, EU Drivers License, National ID are EU-specific types. EU platforms also accept us_passport, non_us_passport, non_us_other, us_drivers_license, us_id_card, us_passport_card"
              example: us_passport
            id_number:
              type: string
              description: "The ID number for the customer. \n - Required when `citizenship_code` is not `US`\n - Required when `citizenship_code : US` but `tax_id` is an ITIN (a 9-digit US ID that begins with the number `9`)."
              example: '123456789'
            citizenship_code:
              type: string
              example: US
              description: The ISO-3166-1 alpha2 citizenship of the participant, e.g. `US`.
              enum:
              - AD
              - AE
              - AF
              - AG
              - AI
              - AL
              - AM
              - AO
              - AQ
              - AR
              - AS
              - AT
              - AU
              - AW
              - AX
              - AZ
              - BA
              - BB
              - BD
              - BE
              - BF
              - BG
              - BH
              - BI
              - BJ
              - BL
              - BM
              - BN
              - BO
              - BQ
              - BR
              - BS
              - BT
              - BV
              - BW
              - BY
              - BZ
              - CA
              - CC
              - CD
              - CF
              - CG
              - CH
              - CI
              - CK
              - CL
              - CM
              - CN
              - CO
              - CR
              - CU
              - CV
              - CW
              - CX
              - CY
              - CZ
              - DE
              - DJ
              - DK
              - DM
              - DO
              - DZ
              - EC
              - EE
              - EG
              - EH
              - ER
              - ES
              - ET
              - FI
              - FJ
              - FK
              - FM
              - FO
              - FR
              - GA
              - GB
              - GD
              - GE
              - GF
              - GG
              - GH
              - GI
              - GL
              - GM
              - GN
              - GP
              - GQ
              - GR
              - GS
              - GT
              - GU
              - GW
              - GY
              - HK
              - HM
              - HN
              - HR
              - HT
              - HU
              - ID
              - IE
              - IL
              - IM
              - IN
              - IO
              - IQ
              - IR
              - IS
              - IT
              - JE
              - JM
              - JO
              - JP
              - KE
              - KG
              - KH
              - KI
              - KM
              - KN
              - KP
              - KR
              - KW
              - KY
              - KZ
              - LA
              - LB
              - LC
              - LI
              - LK
              - LR
              - LS
              - LT
              - LU
              - LV
              - LY
              - MA
              - MC
              - MD
              - ME
              - MF
              - MG
              - MH
              - MK
              - ML
              - MM
              - MN
              - MO
              - MP
              - MQ
              - MR
              - MS
              - MT
              - MU
              - MV
              - MW
              - MX
              - MY
              - MZ
              - NA
              - NC
              - NE
              - NF
              - NG
              - NI
              - NL
              - 'NO'
              - NP
              - NR
              - NU
              - NZ
              - OM
              - PA
              - PE
              - PF
              - PG
              - PH
              - PK
              - PL
              - PM
              - PN
              - PR
              - PS
              - PT
              - PW
              - PY
              - QA
              - RE
              - RO
              - RS
              - RW
              - SA
              - SB
              - SC
              - SD
              - SE
              - SG
              - SH
              - SI
              - SJ
              - SK
              - SL
              - SM
              - SN
              - SO
              - SR
              - SS
              - ST
              - SV
              - SX
              - SY
              - SZ
              - TC
              - TD
              - TF
              - TG
              - TH
              - TJ
              - TK
              - TL
              - TM
              - TN
              - TO
              - TR
              - TT
              - TV
              - TW
              - TZ
              - UA
              - UG
              - UM
              - US
              - UY
              - UZ
              - VA
              - VC
              - VE
              - VG
              - VI
              - VN
              - VU
              - WF
              - WS
              - YE
              - YT
              - ZA
              - ZM
              - ZW
            non_us_other_type:
              type: string
              description: This is required if you select `non_us_other` for the `id_number_type` - a freeform string to describe the ID type
              example: null
            id_issuing_authority:
              type: string
              description: ISO-3166-1_A2 country code that issued the ID. Required if `id_number` is provided.
              example: null
            phone_number:
              type: string
              description: The phone number of the participant
              example: '15557778888'
            platform_code:
              type: string
              example: XXXXXX
            participant_code:
              type: string
              example: XXXXXX
    PatchParticipantLimitsResponse:
      type: object
      properties:
        message:
          type: string
          description: Success message
          example: Participant limits updated successfully
    Code503:
      type: object
      description: 'A downstream dependency was unavailable, timed out, or returned a retryable error. Safe to retry; the response carries a `zh-allow-retry: true` header.'
      required:
      - error
      properties:
        error:
          type: string
          example: Service Unavailable
    Code404:
      type: object
      description: The requested resource does not exist or is not visible to the caller.
      required:
      - error
      properties:
        error:
          type: string
          example: Not Found
    PatchCustomersResponse:
      type: object
      properties:
        message:
          type: object
          description: Updated customer summary. Only a fixed subset of identity fields is returned after an update, regardless of which fields were patched.
          properties:
            first_name:
              type: string
              description: The first name of the customer being onboarded.
              example: John
            last_name:
              type: string
              description: The last name of the customer being onboarded.
              example: Smith
            country:
              type: string
              example: USA
              description: 'The ISO-3166-1 alpha3 country, e.g.`USA`, `IRL`. '
              enum:
              - AND
              - ARE
              - AFG
              - ATG
              - AIA
              - ALB
              - ARM
              - AGO
              - ATA
              - ARG
              - ASM
              - AUT
              - AUS
              - ABW
              - ALA
              - AZE
              - BIH
              - BRB
              - BGD
              - BEL
              - BFA
              - BGR
              - BHR
              - BDI
              - BEN
              - BLM
              - BMU
              - BRN
              - BOL
              - BES
              - BRA
              - BHS
              - BTN
              - BVT
              - BWA
              - BLR
              - BLZ
              - CAN
              - CCK
              - COD
              - CAF
              - COG
              - CHE
              - CIV
              - COK
              - CHL
              - CMR
              - CHN
              - COL
              - CRI
              - CUB
              - CPV
              - CUW
              - CXR
              - CYP
              - CZE
              - DEU
              - DJI
              - DNK
              - DMA
              - DOM
              - DZA
              - ECU
              - EST
              - EGY
              - ESH
              - ERI
              - ESP
              - ETH
              - FIN
              - FJI
              - FLK
              - FSM
              - FRO
              - FRA
              - GAB
              - GBR
              - GRD
              - GEO
              - GUF
              - GGY
              - GHA
              - GIB
              - GRL
              - GMB
              - GIN
              - GLP
              - GNQ
              - GRC
              - SGS
              - GTM
              - GUM
              - GNB
              - GUY
              - HKG
              - HMD
              - HND
              - HRV
              - HTI
              - HUN
              - IDN
              - IRL
              - ISR
              - IMN
              - IND
              - IOT
              - IRQ
              - IRN
              - ISL
              - ITA
              - JEY
              - JAM
              - JOR
              - JPN
              - KEN
              - KGZ
              - KHM
              - KIR
              - COM
              - KNA
              - PRK
              - KOR
              - KWT
              - CYM
              - KAZ
              - LAO
              - LBN
              - LCA
              - LIE
              - LKA
              - LBR
              - LSO
              - LTU
              - LUX
              - LVA
              - LBY
              - MAR
              - MCO
              - MDA
              - MNE
              - MAF
              - MDG
              - MHL
              - MKD
              - MLI
              - MMR
              - MNG
              - MAC
              - MNP
              - MTQ
              - MRT
              - MSR
              - MLT
              - MUS
              - MDV
              - MWI
              - MEX
              - MYS
              - MOZ
              - NAM
              - NCL
              - NER
              - NFK
              - NGA
              - NIC
              - NLD
              - NOR
              - NPL
              - NRU
              - NIU
              - NZL
              - OMN
              - PAN
              - PER
              - PYF
              - PNG
              - PHL
              - PAK
              - POL
              - SPM
              - PCN
              - PRI
              - PSE
              - PRT
              - PLW
              - PRY
              - QAT
              - REU
              - ROU
              - SRB
              - RUS
              - RWA
              - SAU
              - SLB
              - SYC
              - SDN
              - SWE
              - SGP
              - SHN
              - SVN
              - SJM
              - SVK
              - SLE
              - SMR
              - SEN
              - SOM
              - SUR
              - SSD
              - STP
              - SLV
              - SXM
              - SYR
              - SWZ
              - TCA
              - TCD
              - ATF
              - TGO
              - THA
              - TJK
              - TKL
              - TLS
              - TKM
              - TUN
              - TON
              - TUR
              - TTO
              - TUV
              - TWN
              - TZA
              - UKR
              - UGA
              - UMI
              - USA
              - URY
              - UZB
              - VAT
              - VCT
              - VEN
              - VGB
              - VIR
              - VNM
              - VUT
              - WLF
              - WSM
              - YEM
              - MYT
              - ZAF
              - ZMB
              - ZWE
            jurisdiction_code:
              type: string
              description: The ISO 3166-2 subdivision code that the customer resides in. A full list of valid jurisdiction codes can be retrieved from the [`GET /jurisdictions/subdivisions` endpoint](https://docs.zerohash.com/reference/get_jurisdiction-subdivisions) passing a `country` parameter.
              example: US-IL
              enum:
              - US-AL
              - US-AK
              - US-AZ
              - US-AR
              - US-CA
              - US-CO
              - US-CT
              - US-DE
              - US-FL
              - US-GA
              - US-HI
              - US-ID
              - US-IL
              - US-IN
              - US-IA
              - US-KS
              - US-KY
              - US-LA
              - US-ME
              - US-MD
              - US-MA
              - US-MI
              - US-

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