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:
    PatchBeneficiariesBody:
      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
        phone_number:
          type: string
          description: The phone number of the participant
          example: '15557778888'
        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
        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'
        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
        date_of_birth:
          type: string
          description: Date of birth of the customer in the format `YYYY-MM-DD`
          example: '1985-09-02'
        tax_id:
          type: string
          description: "The national ID of the participant, e.g. a social security number.\n - Required when `citizenship_code` is `US`.\n - Optional when `citizenship_code` is not `US`, but if provided, must be accompanied by a valid `id_number` and `id_number_type`.\n - If the tax ID provided is a US ITIN (a 9-digit US ID that begins with the number `9`), then `id_number_type` will be required."
          example: 000-00-0000
        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
      required:
      - first_name
      - last_name
      - jurisdiction_code
      - city
      - zip
    Code400:
      type: object
      description: Request was rejected by validation or a downstream service. `errors` is an array of human-readable messages; each entry describes a single validation failure or business-rule violation.
      required:
      - errors
      properties:
        errors:
          type: array
          items:
            type: string
          example:
          - body/amount must be >= 0
          - body/asset is required
    PostCustomersResponse:
      type: object
      properties:
        message:
          oneOf:
          - title: Customer - All accepted fields
            type: object
            properties:
              first_name:
                type: string
                description: The first name of the customer being onboarded.
                example: John
              middle_name:
                type: string
                description: The middle name of the customer being onboarded.
                example: Middle
              last_name:
                type: string
                description: The last name of the customer being onboarded.
                example: Smith
              former_name:
                type: string
                description: The former name of the customer being onboarded.
                example: Whale
              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
              phone_number:
                type: string
                description: The phone number of the participant
                example: '15557778888'
              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
              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
              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'
              postal_code:
                type: string
                description: Same as `zip`. Postal code of the customer, in the format "min 4 characters, no leading or trailing spaces".
                example: '12345'
                minLength: 4
              jurisdiction_code:
                

# --- 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