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

# Start verification

> Initiates a new verification process using a specified workflow.
The API key must have sufficient permissions to start verifications.
Metadata can be included to track custom information throughout the verification process.

### Use Cases
- Starting a new user verification process
- Creating a verification session for your application
- Configuring a verification flow with custom metadata

### Notes
- This endpoint requires an API key with verification creation permissions
- The flowId must correspond to a workflow configured in your Urtentic account
- Metadata fields are optional but recommended for tracking and correlation
- The response includes all required input fields and settings for the verification




## OpenAPI

````yaml /api-reference/openapi.yml post /verifications
openapi: 3.0.0
info:
  title: Urtentic API
  version: '1.0'
  description: >
    # Introduction

    The Urtentic API provides comprehensive identity verification and workflow
    management capabilities. 

    It enables organizations to create customized verification workflows,
    perform identity checks, 

    and manage verification processes with features including liveness
    detection, 

    location intelligence, and document verification.


    ## Authentication

    All authenticated endpoints require two headers:

    - `Authorization: Bearer {API_KEY}` - Your API key

    - `X-CLIENT-ID: {CLIENT_ID}` - Your client ID


    API credentials can be generated from your Urtentic Dashboard under Settings
    > API Keys.


    ## Webhook Notifications

    Configure webhook URLs in your Urtentic Dashboard to receive real-time
    notifications

    about verification status changes. Webhooks include the verification ID and
    current status,

    allowing your system to react to verification completions or failures.


    ## Key Features

    - User and organization management

    - Customizable verification workflows

    - Multiple verification processes (Liveness, Location, Document, Watchlist
    Check, Email)

    - Analytics and reporting

    - Webhook notifications for verification results
  contact:
    name: Urtentic Support Team
    email: support@urtentic.com
    url: https://urtentic.com/support
  termsOfService: https://urtentic.com/terms
  license:
    name: Urtentic License
    url: https://urtentic.com/license
servers:
  - url: https://api.urtentic.com/api/v1
    description: Urtentic API
security: []
tags:
  - name: Identity
    description: >
      Management of verified identity data, including retrieval and validation
      of identity information.


      Endpoints in this category allow you to:

      - Retrieve verified identity details

      - Check identity verification status

      - Update identity information

      - Link identities across verification sessions
  - name: Processes
    description: >
      Configuration and management of individual verification process types that
      can be used in workflows.


      The Urtentic platform supports these verification processes:

      - **Document Verification**: OCR and authenticity checks for identity
      documents

      - **Liveness Detection**: Confirms a person is physically present and not
      using photos/videos

      - **Location Intelligence**: Verifies geographic location and environments

      - **Email Verification**: Validates email ownership through OTP

      - **Watchlist Check**: Screens identities against compliance databases
  - name: Verification
    description: >
      Core verification operations including starting verifications, submitting
      verification data, and retrieving results.


      Key operations include:

      - Starting new verification sessions

      - Submitting identity data for verification

      - Retrieving verification results

      - Validating inputs before submission

      - Tracking verification status
  - name: Webhook
    description: >
      Configuration and management of webhook endpoints for receiving real-time
      event notifications.


      The webhook system allows you to:

      - Receive real-time notifications about verification status changes

      - Configure multiple webhook endpoints for different environments

      - Specify which events trigger notifications

      - Verify webhook signature to ensure authenticity

      - Track webhook delivery and retry failed deliveries
  - name: Workflow
    description: >
      Creation and management of verification workflows, combining multiple
      verification processes into customized sequences.


      Workflows allow you to:

      - Define multi-step verification sequences

      - Configure country-specific document requirements

      - Set custom verification rules and thresholds

      - Create specialized flows for different use cases

      - Manage verification process order and dependencies
paths:
  /verifications:
    post:
      tags:
        - Verification
      summary: Start verification
      description: >
        Initiates a new verification process using a specified workflow.

        The API key must have sufficient permissions to start verifications.

        Metadata can be included to track custom information throughout the
        verification process.


        ### Use Cases

        - Starting a new user verification process

        - Creating a verification session for your application

        - Configuring a verification flow with custom metadata


        ### Notes

        - This endpoint requires an API key with verification creation
        permissions

        - The flowId must correspond to a workflow configured in your Urtentic
        account

        - Metadata fields are optional but recommended for tracking and
        correlation

        - The response includes all required input fields and settings for the
        verification
      operationId: post-verification
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerificationRequest'
            examples:
              request:
                value:
                  flowId: 40f85c69-b27a-46e8-9115-691401acb5df
                  metadata:
                    email: user@example.com
                    reference: USER123
                    customerId: CUST-456
                    deviceId: D-789012
      responses:
        '200':
          description: Verification started successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StartVerificationResponse'
              examples:
                response:
                  value:
                    metadata:
                      email: user@example.com
                      reference: USER123
                    flowId: 40f85c69-b27a-46e8-9115-691401acb5df
                    identityId: 32a5b2d6-7c9e-4815-a599-fd03d6b34c53
                    verificationId: 85c94e71-6e3f-4a19-b15c-781d8a876542
                    ipAddress: 192.168.1.1
                    inputs:
                      - fieldName: SELFIE_VIDEO
                        description: A short video of your face for liveness detection
                        group: 1
                        fieldType: FILE
                        optional: false
                      - fieldName: DOCUMENT_TYPE
                        description: Select your ID document type
                        group: 2
                        fieldType: DROPDOWN
                        data:
                          options:
                            - PASSPORT
                            - DRIVERS_LICENSE
                            - NATIONAL_ID
                        optional: false
                    settings:
                      - id: 123
                        createdAt: '2023-06-15T14:30:00Z'
                        updatedAt: '2023-06-15T14:30:00Z'
                        value: 'true'
                        fieldName: GALLERY_RESTRICTION
                        type: BOOLEAN
        '400':
          description: Invalid workflow ID or metadata
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
              examples:
                invalid_workflow:
                  value:
                    error: INVALID_WORKFLOW
                    message: The specified workflow ID is invalid or not found
        '401':
          description: Invalid API key
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
              examples:
                invalid_api_key:
                  value:
                    error: INVALID_API_KEY
                    message: The provided API key is invalid or expired
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
              examples:
                insufficient_permissions:
                  value:
                    error: INSUFFICIENT_PERMISSIONS
                    message: >-
                      Your API key does not have permission to create
                      verifications
      security:
        - apiKeyAuth: []
components:
  schemas:
    VerificationRequest:
      type: object
      description: >
        Request to start a new verification process. This initiates a
        verification

        workflow for a user and returns the verification configuration.
      required:
        - flowId
      properties:
        flowId:
          type: string
          format: uuid
          description: ID of the workflow to be executed
          example: 40f85c69-b27a-46e8-9115-691401acb5df
        metadata:
          type: object
          description: >
            Additional data to be associated with the verification. This
            information

            is stored with the verification record and can be used for tracking,

            correlation, or custom business logic.


            Common metadata fields:

            - reference: Your internal reference ID

            - email: User's email address

            - userId: Your system's user identifier

            - deviceId: Device identifier

            - ipAddress: User's IP address (automatically captured if not
            provided)

            - redirectUrl: URL to redirect users after verification (if using
            redirect flows)
          example:
            email: user@example.com
            reference: USER123
            customerId: CUST-456
            deviceId: D-789012
          additionalProperties: true
      x-stoplight:
        id: kjb8e3th3etyy
      example:
        flowId: 40f85c69-b27a-46e8-9115-691401acb5df
        metadata:
          email: user@example.com
          reference: USER123
          customerId: CUST-456
          deviceId: D-789012
    StartVerificationResponse:
      type: object
      description: |
        Response returned when starting a new verification. This contains
        all the information needed to guide the user through the verification
        process.
      properties:
        metadata:
          type: object
          description: Additional metadata associated with the verification
          additionalProperties:
            type: string
          example:
            email: user@example.com
            reference: USER123
        flowId:
          type: string
          format: uuid
          description: Unique identifier of the workflow being used
          example: 40f85c69-b27a-46e8-9115-691401acb5df
        identityId:
          type: string
          format: uuid
          description: Unique identifier for the identity being verified
          example: 32a5b2d6-7c9e-4815-a599-fd03d6b34c53
        verificationId:
          type: string
          format: uuid
          description: Unique identifier for this verification attempt
          example: 85c94e71-6e3f-4a19-b15c-781d8a876542
        ipAddress:
          type: string
          description: IP address from which the verification was initiated
          example: 192.168.1.1
        inputs:
          type: array
          description: List of required input fields for the verification
          items:
            $ref: '#/components/schemas/Field'
          example:
            - fieldName: SELFIE_VIDEO
              description: A short video of your face for liveness detection
              group: 1
              fieldType: FILE
              optional: false
            - fieldName: DOCUMENT_TYPE
              description: Select your ID document type
              group: 2
              fieldType: DROPDOWN
              data:
                options:
                  - PASSPORT
                  - DRIVERS_LICENSE
                  - NATIONAL_ID
              optional: false
        settings:
          type: array
          description: List of configuration settings for the verification
          items:
            $ref: '#/components/schemas/FieldValue'
          example:
            - id: 123
              createdAt: '2023-06-15T14:30:00Z'
              updatedAt: '2023-06-15T14:30:00Z'
              value: 'true'
              fieldName: GALLERY_RESTRICTION
              type: BOOLEAN
      x-stoplight:
        id: dis8te1fnhnbh
    Field:
      type: object
      description: |
        Defines an input field required for verification. These fields
        represent the data that must be collected from the user during
        the verification process.
      required:
        - fieldName
        - fieldType
      properties:
        fieldName:
          type: string
          description: |
            Name of the field. Common field names include:
            - SELFIE_VIDEO: Video capture for liveness detection
            - DOCUMENT_TYPE: Type of identification document
            - FRONT_IMAGE: Front image of document
            - BACK_IMAGE: Back image of document (if applicable)
            - EMAIL_ADDRESS: Email address for verification
            - OTP_CODE: One-time password for email verification
          example: SELFIE_VIDEO
        description:
          type: string
          description: Human-readable description of the field
          example: A short video of your face for liveness detection
        group:
          type: integer
          description: |
            Group number for organizing related fields. Fields in the same
            group are typically displayed together in the verification UI.
          example: 1
        fieldType:
          type: string
          description: |
            Type of the field. Available types:
            - FILE: File upload field
            - TEXT: Text input field
            - NUMBER: Numeric input field
            - DROPDOWN: Dropdown selection field
            - RADIO: Radio button selection
            - CHECKBOX: Checkbox field
            - DATE: Date input field
          example: FILE
        data:
          type: object
          description: |
            Additional data associated with the field, such as
            options for dropdown fields or validation rules.
          example:
            options:
              - PASSPORT
              - DRIVERS_LICENSE
              - NATIONAL_ID
        optional:
          type: boolean
          description: Whether this field is optional
          default: false
          example: false
      x-stoplight:
        id: bx35scssyyd06
    FieldValue:
      type: object
      description: >
        Configuration value for a verification field. These configurations
        control 

        validation rules, appearance, and behavior for different verification
        processes.
      properties:
        id:
          type: integer
          format: int64
          description: Unique identifier for the field value
          example: 12345
        createdAt:
          type: string
          format: date-time
          description: When the field value was created
          example: '2023-06-15T14:30:00Z'
        updatedAt:
          type: string
          format: date-time
          description: When the field value was last updated
          example: '2023-06-15T14:30:00Z'
        deletedAt:
          type: string
          format: date-time
          description: When the field value was deleted (if applicable)
          example: '2023-06-15T14:30:00Z'
        value:
          type: string
          description: Value of the field
          example: 'true'
        fileName:
          type: string
          description: Name of associated file (if applicable)
          example: passport_front.jpg
        fieldName:
          type: string
          enum:
            - SELFIE_VIDEO
            - DEVICE_DATA
            - BIOMETRICS
            - LOCATION_RESTRICTION
            - RESTRICT_VPN
            - RESTRICT_IP_GEOLOCATION
            - HIGH_ACCURACY_CHECK
            - GALLERY_RESTRICTION
            - RESTRICT_SCREENSHOT
            - RESTRICT_AGE
            - DUPLICATE_DETECTION
            - FACEMATCH_THRESHOLD
            - DOCUMENT_TYPES
            - FRONT_IMAGE
            - DOCUMENT_TYPE
            - DOCUMENT_PHOTO
            - BACK_IMAGE
            - EMAIL_ADDRESS
            - OTP_CODE
            - EMAIL_COMPANY_NAME
            - EMAIL_RISK_THRESHOLD
          description: |
            Name of the configuration field. Available fields:

            **Liveness Detection**
            - SELFIE_VIDEO: Video capture for liveness detection
            - BIOMETRICS: Biometric data extraction settings

            **Environment Checks**
            - DEVICE_DATA: Device information collection
            - LOCATION_RESTRICTION: Geographic restrictions
            - RESTRICT_VPN: Whether to block VPN usage
            - RESTRICT_IP_GEOLOCATION: IP-based geolocation rules
            - HIGH_ACCURACY_CHECK: Enhanced accuracy for location checks

            **Security Features**
            - GALLERY_RESTRICTION: Prevent using photos from gallery
            - RESTRICT_SCREENSHOT: Block screenshots during verification
            - RESTRICT_AGE: Age verification thresholds
            - DUPLICATE_DETECTION: Settings for detecting duplicate submissions
            - FACEMATCH_THRESHOLD: Minimum confidence score for face matching

            **Document Verification**
            - DOCUMENT_TYPES: Allowed document types
            - FRONT_IMAGE: Front image of document
            - DOCUMENT_TYPE: Type of identification document
            - DOCUMENT_PHOTO: Photo extracted from document
            - BACK_IMAGE: Back image of document

            **Email Verification**
            - EMAIL_ADDRESS: Email to verify
            - OTP_CODE: One-time password code
            - EMAIL_COMPANY_NAME: Company name for email communications
            - EMAIL_RISK_THRESHOLD: Risk threshold for email verification
          example: SELFIE_VIDEO
        type:
          type: string
          description: Type of the field value (e.g., BOOLEAN, STRING, NUMBER)
          example: BOOLEAN
        country:
          type: string
          maxLength: 3
          description: ISO 3166-1 alpha-3 country code (if applicable)
          example: USA
        page:
          type: string
          enum:
            - FRONT
            - BACK
            - NONE
          default: NONE
          description: |
            Page association for the field:
            - FRONT: Front page/side of document
            - BACK: Back page/side of document
            - NONE: Not page-specific
          example: FRONT
        data:
          type: array
          description: Additional field data options
          items:
            $ref: '#/components/schemas/FieldData'
          example:
            - value: 'true'
              label: Enable Restriction
              description: Prevent using the device gallery during verification
    FieldData:
      type: object
      description: |
        Data item for field configuration. These are used to provide options
        for dropdown fields, radio buttons, and other input types.
      required:
        - value
        - label
        - description
      properties:
        value:
          type: string
          description: Value of the data item
          example: PASSPORT
        label:
          type: string
          description: Human-readable label
          example: International Passport
        description:
          type: string
          description: Detailed description of the data item
          example: Standard international travel document with photo identification

````