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

# Initialize a verification session

> Initialize a session before the user verifies and get back a hosted verification link with a queued-up session. Redirect the user to the returned `url`; they come back to the redirect URL configured on the verification with `?vyt=<token>&vyc=<0|1>`, which you confirm server-side at `GET /v3/confirmations/{token}`.

Accepts a **publishable key** (browser) or a **secret key** (server). `email`, `phone`, `external_id`, `verification_id`, and `verification_external_id` require a secret key. See each parameter below for what it does and when it's required.



## OpenAPI

````yaml /v3/openapi.json post /v3/initialize
openapi: 3.1.0
info:
  title: VerifyYou API
  description: >-
    The VerifyYou developer API. Start a verification from the browser with your
    publishable key, then confirm the result server-side with your secret key.
    Authenticate every request with `Authorization: Bearer <key>`.
  version: 0.1.0
servers:
  - url: https://trust.verifyyou.com
    description: Production
security: []
tags:
  - name: Verification Flow
    description: Start a hosted verification and get the URL to redirect the user to.
  - name: Confirmations
    description: Confirm a verification token, and lock it against replay (secret key).
  - name: API Keys
    description: Check whether a publishable or secret key is valid.
paths:
  /v3/initialize:
    post:
      tags:
        - Verification Flow
      summary: Initialize a verification session
      description: >-
        Initialize a session before the user verifies and get back a hosted
        verification link with a queued-up session. Redirect the user to the
        returned `url`; they come back to the redirect URL configured on the
        verification with `?vyt=<token>&vyc=<0|1>`, which you confirm
        server-side at `GET /v3/confirmations/{token}`.


        Accepts a **publishable key** (browser) or a **secret key** (server).
        `email`, `phone`, `external_id`, `verification_id`, and
        `verification_external_id` require a secret key. See each parameter
        below for what it does and when it's required.
      operationId: external-initialize
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InitializeRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InitializeResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - HTTPBearer: []
components:
  schemas:
    InitializeRequest:
      properties:
        verification_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Verification Id
          description: >-
            Secret key only. Target a verification directly instead of running
            the company's default verification.
        verification_external_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Verification External Id
          description: >-
            Secret key only. Target a verification by your own external id for
            it (set when the verification was created), as an alternative to
            `verification_id`.
          examples:
            - signup-flow
        email:
          anyOf:
            - type: string
            - type: 'null'
          title: Email
          description: >-
            Secret key only. Attach a stable identity to the verification. Fails
            if that identity is already in use.
          examples:
            - user@example.com
        phone:
          anyOf:
            - type: string
            - type: 'null'
          title: Phone
          description: >-
            Secret key only. Attach a stable identity to the verification. Fails
            if that identity is already in use.
        external_id:
          anyOf:
            - type: string
            - type: 'null'
          title: External Id
          description: >-
            Secret key only. Link this verification to your own user or record
            id.
          examples:
            - user_123
        external_tracker:
          anyOf:
            - type: string
            - type: 'null'
          title: External Tracker
          description: >-
            Non-PII label echoed back in the flow webhook payload. Use it to
            correlate funnel events with your own analytics.
        pass_params:
          anyOf:
            - additionalProperties:
                type: string
              type: object
            - type: 'null'
          title: Pass Params
          description: >-
            Extra query params to carry through the flow and append to the
            return URL. Reserved `vy*` keys are ignored.
      type: object
      title: InitializeRequest
    InitializeResponse:
      properties:
        url:
          type: string
          title: Url
          description: >-
            Hosted verification link with a queued-up session. Redirect the user
            here.
          examples:
            - https://app.verifyyou.com/v/abc123
        session_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Session Id
          description: >-
            The minted session id. Pass it to the SDK's vycheck({ session }) to
            run the flow in an embed instead of redirecting to url.
      type: object
      required:
        - url
      title: InitializeResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer

````