Zero Hash Query Participants API

openapi: 3.2.0
info:
  title: zerohash Query 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: Query Participants
  description: Generic Participant management endpoints
paths:
  /participants:
    get:
      tags:
      - Query Participants
      summary: List participants
      description: Returns a list of all participants to which you are associated.
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      - $ref: '#/components/parameters/ParticipantCodeQuery'
      - $ref: '#/components/parameters/PageQuery'
      - name: relationship_type
        in: query
        description: Filters for a specific `relationship_type`
        required: false
        schema:
          type: string
      - name: email
        in: query
        description: Filters for a specific `email`
        required: false
        schema:
          type: string
      - name: minors
        in: query
        description: When set to the string `"true"`, restricts results to minor participants only.
        required: false
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
      - name: entity_type
        in: query
        description: Filters entity participants by their declared entity type.
        required: false
        schema:
          type: string
          enum:
          - corporation
          - llc
          - partnership
          - sole_proprietorship
          - individual
      - name: status
        in: query
        description: Filters for a specific `status`
        required: false
        schema:
          type: string
          enum:
          - submitted
          - pending_approval
          - approved
          - rejected
          - locked
          - pending_unlock
          - pending_disable
          - disabled
          - divested
          - closed
      responses:
        '200':
          description: 'Successfully retrieved paginated list of participants with optional filters: relationship_type, email, status.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetParticipantsResponse'
        '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/{email}:
    get:
      tags:
      - Query Participants
      summary: Get participant
      description: This endpoint returns a participant associated with an email address. It provides a dedicated and lightweight alternative to using the email query parameter within the `GET /participants` endpoint for filtering participants by `email`.
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      - name: email
        in: path
        description: participant email
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successfully retrieved participant. Matching the provided email address.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetParticipantByEmailResponse'
        '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:
    get:
      tags:
      - Query Participants
      summary: Get participant limits
      description: Allows the Platform to query Customer limits, broken out by transaction type, time period and asset.
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      - $ref: '#/components/parameters/ParticipantCodePath'
      responses:
        '200':
          description: Successfully retrieved participant transaction limits including deposit, withdrawal, and trade limits by asset and time period
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetParticipantLimitsResponse'
        '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}/kyc_status:
    get:
      tags:
      - Query Participants
      summary: Get participant KYC status
      description: This endpoint returns KYC Status information attached to a participant.
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      - $ref: '#/components/parameters/ParticipantCodePath'
      responses:
        '200':
          description: Successfully retrieved participant KYC status. Including verification tier, status, and approval timestamps.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetParticipantKYCStatusResponse'
        '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:
    get:
      tags:
      - Query Participants
      summary: Get participant basic info
      description: This endpoint returns Participant basic info.
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      - $ref: '#/components/parameters/ParticipantCodePath'
      responses:
        '200':
          description: Successfully retrieved participant basic information. Including participant code, name, type, and status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetParticipantBasicInfoResponse'
        '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:
    get:
      tags:
      - Query Participants
      summary: Get participant sanction screening info
      description: This endpoint returns Participant sanction screening info.
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      - $ref: '#/components/parameters/ParticipantCodePath'
      responses:
        '200':
          description: Successfully retrieved participant sanction screening information. Including screening status, match results, and compliance verification timestamps.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetParticipantSanctionScreeningInfoResponse'
        '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:
    get:
      tags:
      - Query Participants
      summary: Get participant full info
      description: This endpoint returns Participant full info.
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      - $ref: '#/components/parameters/ParticipantCodePath'
      responses:
        '200':
          description: Successfully retrieved participant full information. Including all profile details, KYC status, limits, and account configuration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetParticipantFullInfoResponse'
        '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/document_metadata:
    get:
      tags:
      - Query Participants
      summary: Get participant document metadata
      description: Returns a list of KYC document metadata for a participant. Does not include document contents or signed URLs.
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      - $ref: '#/components/parameters/ParticipantCodePath'
      responses:
        '200':
          description: Successfully retrieved document metadata list. Returns an empty array if no documents exist for the participant.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetDocumentMetadataResponse'
        '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/documents/{document_id}/download:
    get:
      tags:
      - Query Participants
      summary: Download participant document
      description: Returns a single KYC document with a presigned S3 URL for downloading. The presigned URL expires after 15 minutes. Returns 404 if the document is not found or does not belong to the participant.
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      - $ref: '#/components/parameters/ParticipantCodePath'
      - name: document_id
        in: path
        description: Unique identifier of the document to download. Returned by `GET /participant/{participant_code}/full_info/document_metadata` on each document entry.
        required: true
        schema:
          type: string
          example: e39e7b6a908e397dac50e461eb2d284820214ca2cb3c4aa9aeb9dfc1873332a0
      responses:
        '200':
          description: Successfully retrieved document with presigned download URL. The signed_url field contains a presigned S3 URL valid for 15 minutes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetDocumentForDownloadResponse'
        '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}/status_reason:
    get:
      tags:
      - Query Participants
      summary: Get participant status reason details
      description: Returns detailed information about a participant's current status, including lock, disable, close, or divest reason codes along with compliance and KYC reasons when applicable. Availability is gated per platform; contact zerohash to enable for your platform.
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      - $ref: '#/components/parameters/ParticipantCodePath'
      responses:
        '200':
          description: Successfully retrieved participant status reason details. including the current status and the reason codes that apply for locked, disabled, closed, or divested participants.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetParticipantStatusReasonResponse'
        '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:
    GetParticipantByEmailResponse:
      type: object
      properties:
        message:
          type: object
          properties:
            participant_code:
              type: string
              description: Unique participant code associated with the customer generated by zerohash. This is the identifier that will be used in all other endpoints to refer to this customer.
              example: CUST01
            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
    ParticipantEntity:
      type: object
      properties:
        participant_code:
          type: string
          description: Unique participant code associated with the customer generated by zerohash. This is the identifier that will be used in all other endpoints to refer to this customer.
          example: CUST01
        participant_name:
          type: string
          description: Name of participant
          example: robert test
        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
        status:
          type: string
          description: The current status of the participant
          example: approved
        reason_code:
          type: string
          description: (optional) if the participant has changed statuses, the reason code will show `compliance_issue`, `user_request`, or `risk_cleared`
          example: compliance_issue
        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
        limits:
          type: array
          description: The limits permitted for the participant
          items:
            $ref: '#/components/schemas/TransactionLimit'
        updated_at:
          type: number
          minLength: 13
          maxLength: 13
          example: 1667504636159
          description: Platform updated timestamp
    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
    TransactionLimit:
      type: object
      properties:
        type:
          type: array
          description: The actions that are restricted by the limit
          items:
            type: string
          example:
          - trades
        period:
          type: number
          description: The period in hours on which the limit is applied. A period of 0 means a lifetime limit
          example: 24
        balance:
          type: string
          description: The current balance for the asset
          example: '7500'
        limit:
          type: string
          description: The limit represents the volume that is permitted over the period
          example: '3000'
        configured_limit:
          type: string
          description: The configured unencumbered limit value set for the asset
          example: '5000'
        asset:
          type: string
          description: The currency in which the limit is given
          example: USD
    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
    PaginationMeta:
      type: object
      required:
      - page
      - total_pages
      properties:
        page:
          type: number
          description: Current page number (1-indexed)
          minimum: 1
          example: 1
        page_size:
          type: number
          description: Number of items per page
          minimum: 1
          maximum: 100
          example: 15
        total_pages:
          type: number
          description: Total number of pages available
          minimum: 0
          example: 1
    GetParticipantBasicInfoResponse:
      type: object
      properties:
        message:
          type: object
          properties:
            participant_code:
              type: string
              description: Unique participant code.
              example: ABCDEF
            status:
              type: string
              description: The current status of the participant.
              example: approved
            action:
              type: string
              description: The most recent lifecycle action recorded for the participant (e.g. `update`, `approve`).
              example: update
            participant_type:
              type: string
              description: The type of participant.
              example: INDIVIDUAL
            name:
              type: string
              description: Name of the participant.
              example: Jane Doe
            email:
              type: string
              format: email
              description: Email of the participant.
              example: jane.doe@example.com
            submission_method:
              type: string
              description: Channel through which the participant was submitted (e.g. `API`, `web`).
              example: API
            signed_timestamp:
              type: number
              format: int64
              description: Unix timestamp in milliseconds indicating when the participant accepted zerohash service agreements.
              example: 1603378501286
            created_at:
              type: number
              format: int64
              description: Unix timestamp in milliseconds indicating when the participant was created.
              example: 1603378501286
            last_updated:
              type: number
              format: int64
              description: Unix timestamp in milliseconds indicating when the participant record was last updated.
              example: 1680643465352
            jurisdiction_code:
              type: string
              example: US-IL
              description: The ISO 3166-2 subdivision code that the customer resides in.
    GetParticipantLimitsResponse:
      type: object
      properties:
        message:
          type: object
          properties:
            participant_code:
              type: string
              description: Unique participant code
              example: CUST01
            as_of:
              type: number
              description: Timestamp showing the exact query time in seconds since Unix epoch
              example: 1703001600
            limits:
              type: array
              description: The limits permitted for the participant
              items:
                $ref: '#/components/schemas/TransactionLimit'
            tags:
              type: array
              items:
                type: string
              description: Tags associated with KYC Tier of Participant
              example:
              - kyc_tier_1
    GetParticipantKYCStatusResponse:
      type: object
      properties:
        message:
          type: object
          properties:
            participant_code:
              type: string
              description: Unique participant code
              example: CUST01
            idv:
              type: string
              description: Identity Verification Status
              example: pass
              enum:
              - unknown
              - pass
              - fail
              - not_applicable
            liveness_check:
              type: string
              description: Biometric Identity Verification Status
              example: pass
              enum:
              - unknown
              - pass
              - fail
              - not_applicable
            tax_id:
              type: boolean
              description: Participant has provided a Tax ID
              example: true
            edd:
              type: boolean
              description: Participant has provided information for Enhanced Due Diligence
              example: true
            edd_required:
              type: boolean
              description: Enhanced Due Diligence is required for the Participant and needs to be provided to move forward with onboarding
              example: true
            tags:
              type: array
              items:
                type: string
              description: Tags associated with KYC Tier of Participant
              example:
              - kyc_tier_1
            participant_status:
              type: string
              description: The current status of the participant
              example: approved
            kyc_attempts:
              type: number
              description: The number of KYC attempts the participant has gone through
              example: 1
            email_screening:
              type: string
              enum:
              - passed
              - failed
              - error
              description: Whether the participant passed email screening
              example: failed
    GetParticipantStatusReasonResponse:
      type: object
      properties:
        message:
          type: object
          properties:
            participant_code:
              type: string
              description: Unique participant code
              example: CUST01
            status:
              type: string
              description: The current status of the participant
              example: locked
            lock_reason:
              type: string
              description: Reason code for locked participants
              example: compliance_issue
            disable_reason:
              type: string
              description: Reason code for disabled participants
              example: user_request
            close_reason:
              type: string
              description: Reason code for closed participants
              example: compliance_issue
            divest_reason:
              type: string
              description: Reason code for divested participants
              example: user_request
            compliance_reasons:
              type: array
              items:
                type: string
              description: Array of compliance issue reason codes
              enum:
              - restricted_jurisdiction
              - abandoned_escheat
              - child_abuse_material
              - darknet_market
              - gambling
              - illicit
              - merchant
              - mixer
              - nft_marketplace
              - scam
              - terrorist_organization
              - thief
              - shielded
              - victim_of_fraud_or_illicit_activity
              - fraud
              - cash_spike_incoming
              - cash_spike_outgoing
              - structured_transactions
              - cannabis_name_match
              - potential_elder_financial_exploitation
              - other_aml_cft_illicit_activity
              - sanctions_possible_match
              - sanctions_confirmed_match
              - politically_exposed_person_foreign
              - politically_exposed_person_domestic
              - other_cdd_issue
              - other_financial_crimes
              - referral_from_platform
              - impossible_travel_rule
              - multiple_incorrect_dob_rule
              - blocklisted_pii
              - referral_from_platform_imposter_scam
              - referral_from_le
              - other
              - fincen_primary_ml_concern
              - sanctions_direct
              - sanctions_indirect
 

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