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:
    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
    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
              - other_high_risk_entity_exposure
              - market_abuse_manipulation
              - ach_return_unauthorized_transaction
              - ach_return_insufficient_funds
              - ach_return_other
              - gsc_pep
              - gsc_adverse_media
              - deceased
              - discontinued_customer
              - edd_required
              - kyc_refresh
              example:
              - fraud
              - sanctions_confirmed_match
            notes:
              type: string
              description: Additional notes about the participant status
              example: Participant flagged for suspicious activity
            case_number:
              type: string
              description: Case number associated with the participant status
              example: CASE-2024-001
            kyc_reasons:
              type: array
              items:
                type: string
              description: Array of KYC-related reason codes
              example:
              - identity_verification_failed
    GetParticipantFullInfoResponse:
      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: approved
            action:
              type: string
              description: The action taken
              example: approved
            action_reason:
              type: string
              description: If the participant has changed statuses, the reason code will give more details like `compliance_issue`, `user_request`, or `risk_cleared`
              example: compliance_issue
            user_email:
              type: string
              description: Identifier of the user who last acted on this participant. Typically an email address, but may be any opaque user identifier.
              example: ops-user-1234
            participant_type:
              type: string
              description: The type of participant.
              example: INDIVIDUAL
            name:
              type: string
              description: Full display name of the participant.
              example: Jane Doe
            first_name:
              type: string
              description: First name of the participant.
              example: Jane
            last_name:
              type: string
              description: Last name of the participant.
              example: Doe
            email:
              type: string
              format: email
              description: Email of the participant.
              example: jane.doe@example.com
            contact_number:
              type: string
              description: Phone number of the business.
              example: '15557778888'
            website:
              type: string
              description: Website of the business.
              example: www.test.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 regular maximum length is 50 characters.

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

                - PO Box addresses are not accepted.'
              example: Suite 1000
            city:
              type: string
              description: The city minor resides in
              example: Chicago
            postal_code:
              type: string
              description: Postal, or zip code, of the business, in the format "min 4 characters, no leading or trailing spaces" for non-US postal code or <5digits>-<4digits> for US zip code, e.g. 77777 or 77777-7777
              example: '12345'
            date_established:
              type: string
              description: Date the business was established. This should reflect government registration for the entity in the format `YYYY-MM-DD`
              example: '1985-09-02'
            legal_name:
              type: string
              description: Registered legal name of the entity. This should not be a DBA or DBA equivalent
              example: Legal Name
            entity_type:
              type: string
              enum:
              - corporation
              - llc
              - partnership
              - sole_proprietorship
              - other
              - non_profit
              - public_or_semi_public_administrative
              - trust
              - cooperation
              - company_with_limited_liability
              - llc_c
              - llc_s
              - llc_p
              - s_corporation
              - c_corporation
              - trust_estate
              description: The type of business that is onboarding, must be one of the supported
              example: partnership
            state_or_province_of_organization:
              type: string
              example: IL
            date_of_birth:
              type: string
              description: Date of birth of the participant
              example: '1985-09-02'
            submission_method:
              type: string
              description: The method of submission
              example: web
            signed_timestamp:
              type: number
              description: The time at which the business accepted zerohash services agreements
              example: 1603378501286
            created_at:
              type: number
              description: Creation timestamp
              example: 1603378501286
            last_updated:
              type: number
              description: Last update timestamp
              example: 1680643465352
            platform_updated_at:
              type: number
              description: Platform updated timestamp
              example: 1603378501286
            kyc_timestamp:
              type: number
              description: The timestamp at which the KYC was completed
              example: 1603378501286
            sanction_screening_timestamp:
              type: number
              description: "The time the sanctions screen was done\t"
              example: 1603378501286
            kyc_participant_track:
              type: string
              description: KYC track the participant was onboarded under (e.g. `vendor reliance`).
              example: vendor reliance
            jurisdiction_updated_at:
              type: number
              format: int64
              description: Unix timestamp in milliseconds indicating when the jurisdiction was last updated.
              example: 1731354732292
            kyc_tier:
              type: string
              description: The KYC tier currently held by the participant (e.g. `FULL`, `LIGHT`).
              example: FULL
            subdomain:
              type: string
              description: Registered subdomain of the entity.
              example: subdomain
            jurisdiction_code:
              type: string
              example: US-IL
              description: The ISO 3166-2 subdivision code that the customer resides in
            id_number:
              type: string
              description: The ID number for the customer
              example: '123456789'
            id_number_type:
              type: string
              enum:
              - ssn
              - ein
              - 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
              - legal_entity_identifier
              - chamber_of_commerce_number
              - value_added_tax_number
              - national_id
              description: 'The type of ID number that is provided, must be one of the supported types. '
              example: us_border_crossing_card
            non_us_other_type:
              type: string
              description: A freeform string to describe the ID type that does not fit into the other predefined categories of ID types.
              example: null
            id_issuing_authority:
              type: string
              description: ISO-3166-1_A2 country code that issued the ID
              example: null
            non_us_entity_tax_id:
              type: string
              description: The tax identifier for a non-US entity
              example: null
            tax_id:
              type: string
              description: The national ID of the participant, e.g. a social security number.
              example: 000-00-0000
            kyc:
              type: string
              enum:
              - pass
              - fail
              description: Whether the participant passed or failed KYC by vendor.
              example: pass
            onboarding_profile:
              type: string
              enum:
              - kyc_track
              - shopper
              - originator_entity
              - payouts_payor_ultimate
              - payouts_beneficiary
              description: Onboarding profile used to determine the participant's KYC track. Defaults to 'kyc_track' when omitted.
              example: kyc_track
            merchant_category_code:
              type: string
              description: ISO 18245 four-digit Merchant Category Code (MCC) that identifies the business activity of the entity. Accepted on entity create/update; zerohash derives `merchant_category_code_category` and `merchant_category_code_classification` from this value.
              example: '5411'
            merchant_category_code_category:
              type: string
              description: Human-readable category derived by zerohash from `merchant_category_code`. Returned in responses only; not accepted as input.
              ex

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