> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dev.symbiosis.markets/llms.txt
> Use this file to discover all available pages before exploring further.

# Start or resume the caller's identity verification.

> Returns a one-time link into Persona's hosted flow. Send the browser there. An unfinished inquiry is resumed. An expired or failed one is replaced. Returns 409 once the account is under review, approved, or declined.



## OpenAPI

````yaml /openapi.yaml post /auth/kyc/inquiry
openapi: 3.1.0
info:
  title: Symbiosis API
  description: >-
    The Symbiosis REST API.


    ## Authentication


    Endpoints accept one of two credentials:


    - **Session token**: `Authorization: Bearer <token>`, from `POST
    /auth/login`.

    - **API key (HMAC)**: three headers on every request:
      - `APIKEY`: the API key id, from `POST /auth/api-keys`.
      - `X-Hmac-Timestamp`: current Unix time in milliseconds.
      - `X-Hmac-Signature`: Base64-encoded HMAC-SHA256 of
        `timestamp_ms "\n" METHOD "\n" PATH_AND_QUERY "\n" BODY`, keyed with the API key
        secret. `PATH_AND_QUERY` is the full request target including the query string.

    ## Wire formats


    Token amounts (`U256`) serialize in responses as 0x-prefixed hex strings;
    requests accept decimal strings, 0x-prefixed hex strings, or JSON numbers.
    Asset ids and addresses are 0x-prefixed hex strings. Prices are integers
    scaled by 1e6.


    ## Request ids


    Every response carries an `x-request-id` header: a server-minted UUID that
    keys our logs. Include it when reporting a problem. The server never adopts
    an id you send; an inbound `x-request-id` is logged alongside ours, so a
    request that never got a response can still be found.


    ## Identifiers and uniqueness


    For integrators mirroring this API into their own storage:


    - **Globally unique, never reused**: `user_id`, `api_key_id`, `request_id`,
    `quote_id`, `match_id`, `withdrawal_id`, `job_id`, audit event `id`. The
    ledger's `entry_id` is also strictly increasing: a safe dedupe key and
    cursor.

    - **Unique per user**: `client_withdrawal_id`, the caller-chosen idempotency
    key. Replaying the same id and terms returns the original withdrawal; the
    same id with different terms returns 409.

    - **Composite keys**: an outcome token is `(venue, asset_id)`, never
    `asset_id` alone; balances are keyed by `(user, venue, asset_id)`, with USDC
    held separately.

    - **Not unique**: a ledger `ref_id` (every entry the same record caused
    shares it) and a withdrawal's `transaction_hash` (it can change if the job
    is re-signed; key on `job_id`).
  version: 0.1.0
servers:
  - url: https://api.symbiosis.markets
security: []
tags:
  - name: auth
    description: Accounts, sessions, API keys, and websocket tickets.
  - name: custody
    description: Deposit addresses, balances, and withdrawals.
  - name: rfq
    description: Quote requests, quotes, and matching.
paths:
  /auth/kyc/inquiry:
    post:
      tags:
        - auth
      summary: Start or resume the caller's identity verification.
      description: >-
        Returns a one-time link into Persona's hosted flow. Send the browser
        there. An unfinished inquiry is resumed. An expired or failed one is
        replaced. Returns 409 once the account is under review, approved, or
        declined.
      operationId: start_kyc_inquiry
      responses:
        '200':
          description: A hosted-flow link for the caller.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KycInquiryResponse'
        '401':
          description: Invalid or missing KYC challenge.
      security:
        - KycChallengeBearer: []
components:
  schemas:
    KycInquiryResponse:
      description: A hosted-flow link for the caller.
      type: object
      properties:
        inquiry_id:
          description: The inquiry the link opens.
          type: string
        url:
          description: One-time URL on `inquiry.withpersona.com`. Send the browser there.
          type: string
      required:
        - inquiry_id
        - url
  securitySchemes:
    KycChallengeBearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        KYC challenge from `POST /auth/login`, returned instead of a session
        token until the account is approved.

````