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

# Initiate a user's verification

> Start the user's verification session and return the id to poll. Idempotent per phone.



## OpenAPI

````yaml /api-reference/openapi.json post /verifications
openapi: 3.1.0
info:
  title: Verify with Privue
  description: >-
    Verify your users' identity and business details through Privue's hosted
    flow.


    **Authentication.** Every request takes your API key as a bearer token:
    `Authorization: Bearer <your-key>`.


    **Flow.**


    1. `POST /verifications` with the user's phone. We start their verification
    session and return a `verification_id`.

    2. Redirect the user to `https://verify.privue.ai/<your-slug>` to complete
    the steps.

    3. Poll `GET /verifications/{verification_id}` for status and step progress,
    and `GET /verifications/{verification_id}/data` for the collected result.

    4. Optionally `POST /verifications/{verification_id}/cancel` to end a
    verification early.


    **Identifiers.** `verification_id` is ours and names the verification on
    every read. `reference_id` is your own optional correlation id - stored and
    echoed back, never used as a key.


    **Timestamps.** Timestamps are in IST.


    **Polling.** Reads are free and safe to poll as often as you need.
  version: 0.1.0
servers:
  - url: https://api.verify.privue.ai
    description: Production
security: []
paths:
  /verifications:
    post:
      tags:
        - Verifications
      summary: Initiate a user's verification
      description: >-
        Start the user's verification session and return the id to poll.
        Idempotent per phone.
      operationId: create_verification_verifications_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateVerificationRequest'
        required: true
      responses:
        '201':
          description: >-
            The provisioned verification_id and the verification's initial
            status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateVerificationResponse'
              example:
                verification_id: 3f2504e0-4f89-41d3-9a0c-0305e82c3301
                reference_id: ord_991
                status: created
        '400':
          description: return_url is not on the client's registered allowlist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: Return URL is not on this client's allowlist.
        '401':
          description: Missing, malformed, or rejected API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: API key is missing, malformed, or rejected.
        '403':
          description: The API key is valid but not enrolled as a verification client.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: No active verification client for this API key.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - HTTPBearer: []
components:
  schemas:
    CreateVerificationRequest:
      properties:
        mobile:
          type: string
          pattern: ^(?:\+91)?[6-9]\d{9}$
          title: Mobile
          description: The user's phone; we start their verification session from it
        return_url:
          type: string
          title: Return Url
          description: >-
            Where the user is sent afterwards. Must match the client's
            registered allowlist
        reference_id:
          anyOf:
            - type: string
              maxLength: 128
            - type: 'null'
          title: Reference Id
          description: The client's own id for the entity, echoed back on reads
      type: object
      required:
        - mobile
        - return_url
      title: CreateVerificationRequest
      description: What a client sends to start a user's verification.
    CreateVerificationResponse:
      properties:
        verification_id:
          type: string
          format: uuid
          title: Verification Id
          description: Our id for this verification; use it as the key on every read
        reference_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Reference Id
          description: Your correlation id, echoed back; null if you sent none
        status:
          $ref: '#/components/schemas/VerificationStatus'
          description: Lifecycle status; created for a fresh verification
      type: object
      required:
        - verification_id
        - reference_id
        - status
      title: CreateVerificationResponse
      description: >-
        The verification session we started.


        Redirect the user to `verify.privue.ai/<your-slug>`, then poll with this
        id.
    ErrorResponse:
      properties:
        detail:
          type: string
          title: Detail
          description: A human-readable explanation of what went wrong
      type: object
      required:
        - detail
      title: ErrorResponse
      description: >-
        Every error on this API returns this shape. Branch on the HTTP status,
        not the message text.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    VerificationStatus:
      type: string
      enum:
        - created
        - in-progress
        - completed
        - cancelled
        - expired
      title: VerificationStatus
      description: >-
        Lifecycle of one user's verification.


        There is no expiry state: a verification is a durable record keyed on
        the user, and the user

        returns to their verification session whenever they choose, so nothing
        lapses on a clock.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer

````