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

# Verify a document, and optionally a selfie, synchronously

> Send an `Idempotency-Key` header to make retries safe: the same key returns the original result with `Idempotent-Replayed: true`. Test keys (`vn_test_`) run the full pipeline and never store images.



## OpenAPI

````yaml /openapi.json post /v1/verify
openapi: 3.1.0
info:
  title: VerifNer API
  version: 1.0.0
  description: >-
    Identity verification for Nigerien passports and national identity cards.
    One call, a reasoned verdict: five checks with evidence, a score, VERIFIED
    at 0.90 and above, REVIEW from 0.60, REJECTED below.
servers:
  - url: https://api.verifner.com
security:
  - apiKey: []
tags:
  - name: Verify
    description: Server-to-server verification with the secret key.
  - name: Sessions
    description: >-
      Browser flows: your server opens a session, the web SDK uploads with a
      client token.
  - name: Webhooks
    description: verification.completed, signed with HMAC-SHA256, retried with backoff.
paths:
  /v1/verify:
    post:
      tags:
        - Verify
      summary: Verify a document, and optionally a selfie, synchronously
      description: >-
        Send an `Idempotency-Key` header to make retries safe: the same key
        returns the original result with `Idempotent-Replayed: true`. Test keys
        (`vn_test_`) run the full pipeline and never store images.
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          schema:
            type: string
            maxLength: 255
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - front
              properties:
                front:
                  type: string
                  format: binary
                  description: >-
                    Document front (passport data page). JPEG, PNG or WebP, up
                    to 12 MB.
                back:
                  type: string
                  format: binary
                  description: CNI back. Omit for a passport.
                selfie:
                  type: string
                  format: binary
                  description: Live photo of the holder. Omit to skip the face check.
          application/json:
            schema:
              type: object
              required:
                - front
              properties:
                front:
                  type: string
                  description: base64
                back:
                  type: string
                selfie:
                  type: string
      responses:
        '200':
          description: Replayed from the idempotency key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationResult'
        '201':
          description: Verdict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationResult'
        '400':
          description: Malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing, malformed or revoked key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: '`unreadable` (blurred front), `not_an_image`, or `extraction_failed`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: 'Rate limit: 120 requests per minute per key'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    VerificationResult:
      $schema: http://json-schema.org/draft-07/schema#
      type: object
      properties:
        id:
          type: string
          pattern: ^vrf_[a-z0-9]{6,}$
        status:
          type: string
          enum:
            - VERIFIED
            - REVIEW
            - REJECTED
        verdict:
          type: string
          enum:
            - verified
            - review
            - rejected
        score:
          type: number
          minimum: 0
          maximum: 1
        document_type:
          type: string
          enum:
            - passport
            - cni
            - unknown
        document:
          type: object
          properties:
            type:
              type: string
              enum:
                - passport
                - cni
                - unknown
            country:
              type:
                - string
                - 'null'
            fields:
              anyOf:
                - type: object
                  propertyNames:
                    type: string
                  additionalProperties: {}
                - type: 'null'
            mrz:
              type: object
              properties:
                lines:
                  type: array
                  items:
                    type: string
                valid:
                  type: boolean
              required:
                - lines
                - valid
              additionalProperties: false
            legibility:
              type:
                - number
                - 'null'
          required:
            - type
          additionalProperties: false
        fields:
          anyOf:
            - type: object
              propertyNames:
                type: string
              additionalProperties: {}
            - type: 'null'
        face_match:
          anyOf:
            - type: object
              properties:
                similarity:
                  type:
                    - number
                    - 'null'
                matched:
                  type: boolean
                faces_in_document:
                  type: number
                faces_in_selfie:
                  type: number
              required:
                - similarity
                - matched
              additionalProperties: false
            - type: 'null'
        checks:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
                enum:
                  - mrz_checksum
                  - expiry
                  - viz_mrz_consistency
                  - tamper
                  - face_match
              status:
                type: string
                enum:
                  - pass
                  - warn
                  - fail
                  - skipped
              score:
                anyOf:
                  - type: number
                    minimum: 0
                    maximum: 1
                  - type: 'null'
              evidence:
                type: object
                properties:
                  fr:
                    type: string
                  en:
                    type: string
                required:
                  - fr
                  - en
                additionalProperties: false
            required:
              - name
              - status
              - score
              - evidence
            additionalProperties: false
        timings:
          type: object
          propertyNames:
            type: string
          additionalProperties:
            type: number
        latency_ms:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        created_at:
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
      required:
        - id
        - verdict
        - score
        - document_type
        - checks
        - latency_ms
        - created_at
      additionalProperties: false
      description: >-
        Five checks, each with bilingual evidence. `final_verdict` appears on
        reads once a reviewer decided.
    Error:
      $schema: http://json-schema.org/draft-07/schema#
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
          required:
            - code
            - message
          additionalProperties: false
      required:
        - error
      additionalProperties: false
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: '`vn_live_…` or `vn_test_…`, from the console.'

````