HyperVerge Face Match API

openapi: 3.0.3
info:
  title: HyperVerge Identity Verification API
  description: >-
    HyperVerge is an AI-based identity verification and customer onboarding
    platform. This document models HyperVerge's documented public REST surface
    for India, drawn from HyperVerge's official REST-API documentation
    repositories on GitHub. The surface spans three region hosts:


      * `https://ind-docs.hyperverge.co/v2.0` - KYC document OCR / extraction.

      * `https://ind-verify.hyperverge.co` - central database verification,
        input validation, and field matching.

      * `https://ind-faceid.hyperverge.co` - face match.


    All requests authenticate with an `appId` and `appKey` pair issued by the
    HyperVerge team (headers are lowercase `appid`/`appkey` on the Face Match
    host). Credentials are provided after enterprise onboarding. Region hosts
    exist for other geographies (for example `apac.faceid.hyperverge.co` for
    Face Match in APAC); only the India hosts are modeled here.


    Scope note: endpoint paths, methods, and auth are grounded in HyperVerge's
    published REST documentation. Request/response schemas are modeled
    representatively (multipart form-data and JSON bodies) rather than copied
    field-for-field, and are flagged where they are approximate. Liveness
    detection is delivered via HyperVerge's SDKs/Workflow and is not modeled as
    a REST operation here because a standalone public REST endpoint was not
    confirmed at review time.
  version: '1.0'
  contact:
    name: HyperVerge
    url: https://hyperverge.co
  x-modeled-note: >-
    Paths, methods, hosts, and appId/appKey auth are confirmed from HyperVerge's
    public REST-API repositories. Response schemas are representative models, not
    verbatim contracts.
servers:
  - url: https://ind-verify.hyperverge.co
    description: India - Database Verification, Input Validation, Matching
  - url: https://ind-docs.hyperverge.co/v2.0
    description: India - KYC OCR / Extraction
  - url: https://ind-faceid.hyperverge.co
    description: India - Face Match
security:
  - appIdKey: []
tags:
  - name: KYC OCR
    description: Document OCR and KYC field extraction for Indian identity documents.
  - name: Database Verification
    description: Central/government database verification for Indian documents.
  - name: Input Validation
    description: Cross-validation of user input against OCR/QR extraction output.
  - name: Matching
    description: Fuzzy and direct field matching.
  - name: Face Match
    description: Selfie-to-ID / selfie-to-selfie face comparison.
paths:
  /readKYC:
    servers:
      - url: https://ind-docs.hyperverge.co/v2.0
    post:
      operationId: readKYC
      tags:
        - KYC OCR
      summary: Extract KYC fields (auto-detect document)
      description: >-
        Auto-detects the supported Indian document type in the supplied image,
        PDF, or URL and extracts the relevant KYC fields.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/OcrDocumentInput'
      responses:
        '200':
          description: Extraction result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OcrResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /readPAN:
    servers:
      - url: https://ind-docs.hyperverge.co/v2.0
    post:
      operationId: readPAN
      tags:
        - KYC OCR
      summary: Extract PAN card fields
      description: Extracts fields from an Indian PAN card image, PDF, or URL.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/OcrDocumentInput'
      responses:
        '200':
          description: Extraction result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OcrResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /readAadhaar:
    servers:
      - url: https://ind-docs.hyperverge.co/v2.0
    post:
      operationId: readAadhaar
      tags:
        - KYC OCR
      summary: Extract Aadhaar card fields
      description: Extracts fields from an Aadhaar card image, PDF, or URL.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/OcrDocumentInput'
      responses:
        '200':
          description: Extraction result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OcrResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /readPassport:
    servers:
      - url: https://ind-docs.hyperverge.co/v2.0
    post:
      operationId: readPassport
      tags:
        - KYC OCR
      summary: Extract Indian passport fields
      description: Extracts fields from an Indian passport image, PDF, or URL.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/OcrDocumentInput'
      responses:
        '200':
          description: Extraction result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OcrResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /readVoterID:
    servers:
      - url: https://ind-docs.hyperverge.co/v2.0
    post:
      operationId: readVoterID
      tags:
        - KYC OCR
      summary: Extract Voter ID fields
      description: Extracts fields from a Voter ID (EPIC) card image, PDF, or URL.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/OcrDocumentInput'
      responses:
        '200':
          description: Extraction result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OcrResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api:
    servers:
      - url: https://ind-verify.hyperverge.co
    get:
      operationId: verifyHealthCheck
      tags:
        - Database Verification
      summary: Connection health check
      description: Returns the plain-text string "Aok" to confirm connectivity.
      responses:
        '200':
          description: Plain-text "Aok".
          content:
            text/plain:
              schema:
                type: string
                example: Aok
  /api/verifyPAN:
    servers:
      - url: https://ind-verify.hyperverge.co
    post:
      operationId: verifyPAN
      tags:
        - Database Verification
      summary: Verify PAN against central database
      description: Verifies a PAN number against name and date of birth.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifyPanInput'
      responses:
        '200':
          description: Verification result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/getNameFromPAN:
    servers:
      - url: https://ind-verify.hyperverge.co
    post:
      operationId: getNameFromPAN
      tags:
        - Database Verification
      summary: Get registered name from PAN
      description: Returns the registered holder name for a PAN number.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - pan
              properties:
                pan:
                  type: string
                  description: PAN in CCCCCDDDDC format.
                  example: ABCDE1234F
      responses:
        '200':
          description: Verification result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/checkDL:
    servers:
      - url: https://ind-verify.hyperverge.co
    post:
      operationId: checkDL
      tags:
        - Database Verification
      summary: Verify Driving License
      description: Verifies and extracts driving-license data by DL number and date of birth.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - dlNumber
                - dob
              properties:
                dlNumber:
                  type: string
                  description: Driving license number (9-20 characters).
                dob:
                  type: string
                  description: Date of birth in DD-MM-YYYY format.
                  example: 01-01-1990
      responses:
        '200':
          description: Verification result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/checkVoterId:
    servers:
      - url: https://ind-verify.hyperverge.co
    post:
      operationId: checkVoterId
      tags:
        - Database Verification
      summary: Verify Voter ID (EPIC)
      description: Extracts and verifies Voter ID information by EPIC number.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - epicNumber
              properties:
                epicNumber:
                  type: string
                  description: Voter ID EPIC number (6-13 characters).
      responses:
        '200':
          description: Verification result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/checkBankAccount:
    servers:
      - url: https://ind-verify.hyperverge.co
    post:
      operationId: checkBankAccount
      tags:
        - Database Verification
      summary: Verify bank account
      description: Verifies bank account details by IFSC and account number.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - ifsc
                - accountNumber
              properties:
                ifsc:
                  type: string
                  description: IFSC code (11 characters).
                accountNumber:
                  type: string
                  description: Bank account number.
      responses:
        '200':
          description: Verification result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/validatePANInput:
    servers:
      - url: https://ind-verify.hyperverge.co
    post:
      operationId: validatePANInput
      tags:
        - Input Validation
      summary: Validate PAN input against OCR
      description: >-
        Cross-validates user-entered PAN details against the OCR extraction
        result and returns per-field match flags.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValidateInput'
      responses:
        '200':
          description: Per-field validation result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/validateAadhaarInput:
    servers:
      - url: https://ind-verify.hyperverge.co
    post:
      operationId: validateAadhaarInput
      tags:
        - Input Validation
      summary: Validate Aadhaar input against OCR/QR
      description: >-
        Cross-validates user-entered Aadhaar details (or QR-extracted data)
        against front/back OCR results.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValidateInput'
      responses:
        '200':
          description: Per-field validation result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/validatePassportInput:
    servers:
      - url: https://ind-verify.hyperverge.co
    post:
      operationId: validatePassportInput
      tags:
        - Input Validation
      summary: Validate passport input against OCR
      description: Cross-validates user-entered passport details against front/back OCR results.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValidateInput'
      responses:
        '200':
          description: Per-field validation result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/validateVoterIdInput:
    servers:
      - url: https://ind-verify.hyperverge.co
    post:
      operationId: validateVoterIdInput
      tags:
        - Input Validation
      summary: Validate Voter ID input against OCR
      description: Cross-validates user-entered Voter ID details against front/back OCR results.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValidateInput'
      responses:
        '200':
          description: Per-field validation result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/matchFields:
    servers:
      - url: https://ind-verify.hyperverge.co
    post:
      operationId: matchFields
      tags:
        - Matching
      summary: Match field pairs
      description: >-
        Compares two values across supported fields. Fuzzy matching is applied
        to name and address; direct matching to fields such as dob, pan_no,
        aadhaar, passport_num, voterid, phone, gender, and others. Returns a
        per-field result plus an overall `all` flag.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties:
                type: object
                properties:
                  value1:
                    type: string
                  value2:
                    type: string
              example:
                name:
                  value1: Jane Doe
                  value2: Jane A Doe
                dob:
                  value1: 01/01/1990
                  value2: 01/01/1990
      responses:
        '200':
          description: Per-field match result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/photo/verifyPair:
    servers:
      - url: https://ind-faceid.hyperverge.co
    get:
      operationId: faceMatchHealthCheck
      tags:
        - Face Match
      summary: Face Match health check
      description: Returns the plain-text string "Hello!" to confirm connectivity.
      responses:
        '200':
          description: Plain-text "Hello!".
          content:
            text/plain:
              schema:
                type: string
                example: Hello!
    post:
      operationId: verifyPair
      tags:
        - Face Match
      summary: Verify a face pair
      description: >-
        Determines whether two face images belong to the same person. Supply
        either a selfie + id pair or a selfie + selfie2 pair. Uses lowercase
        `appid`/`appkey` headers on this host.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                selfie:
                  type: string
                  format: binary
                  description: Selfie image (JPEG, PNG, or TIFF).
                id:
                  type: string
                  format: binary
                  description: ID document photo to match against the selfie.
                selfie2:
                  type: string
                  format: binary
                  description: Second selfie, for selfie-to-selfie matching.
                allowMultipleFaces:
                  type: string
                  enum: ['yes', 'no']
                enableDashboard:
                  type: string
                  enum: ['yes', 'no']
      responses:
        '200':
          description: Face match result with a match score.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FaceMatchResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  securitySchemes:
    appIdKey:
      type: apiKey
      in: header
      name: appId
      description: >-
        HyperVerge issues an appId and appKey pair after enterprise onboarding.
        Both are sent as request headers: `appId` and `appKey` on the ind-docs
        and ind-verify hosts, and lowercase `appid` and `appkey` on the
        ind-faceid (Face Match) host. Do not expose these credentials in
        browser applications.
  responses:
    Unauthorized:
      description: Invalid or missing appId/appKey credentials.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    OcrDocumentInput:
      type: object
      description: >-
        Supply exactly one of image, pdf, or url. Modeled representatively from
        HyperVerge KYC docs.
      properties:
        image:
          type: string
          format: binary
          description: Document image (JPEG, PNG, or TIFF).
        pdf:
          type: string
          format: binary
          description: Document as a PDF.
        url:
          type: string
          format: uri
          description: Publicly accessible URL to the document.
        qualityCheck:
          type: string
          enum: ['yes', 'no']
          description: Detect black/white or low-quality documents.
        faceCheck:
          type: string
          enum: ['yes', 'no']
          description: Verify a face is present on the document.
        outputImageUrl:
          type: string
          enum: ['yes', 'no']
          description: Return a cropped/aligned image URL.
    OcrResult:
      type: object
      description: Representative KYC extraction response (modeled).
      properties:
        status:
          type: string
          example: success
        statusCode:
          type: string
          example: '200'
        result:
          type: object
          additionalProperties: true
          description: Extracted document fields (fields vary by document type).
    VerifyPanInput:
      type: object
      required:
        - pan
        - name
        - dob
      properties:
        pan:
          type: string
          description: PAN in CCCCCDDDDC format.
          example: ABCDE1234F
        name:
          type: string
        dob:
          type: string
          description: Date of birth in DD/MM/YYYY format.
          example: 01/01/1990
    VerificationResult:
      type: object
      description: Representative database-verification response (modeled).
      properties:
        status:
          type: string
          example: success
        statusCode:
          type: string
          example: '200'
        result:
          type: object
          additionalProperties: true
    ValidateInput:
      type: object
      description: >-
        Representative validation body (modeled). Carries user-entered values
        under `userInput` and the OCR/QR extraction under `ocrResult`,
        `ocrResultFront`/`ocrResultBack`, or `qrResult` depending on the
        document.
      properties:
        userInput:
          type: object
          additionalProperties: true
        ocrResult:
          type: object
          additionalProperties: true
        ocrResultFront:
          type: object
          additionalProperties: true
        ocrResultBack:
          type: object
          additionalProperties: true
        qrResult:
          type: object
          additionalProperties: true
    ValidationResult:
      type: object
      description: Representative per-field match response (modeled).
      properties:
        status:
          type: string
          example: success
        statusCode:
          type: string
          example: '200'
        result:
          type: object
          additionalProperties: true
          description: Per-field match flags, plus an overall `all` flag on matchFields.
    FaceMatchResult:
      type: object
      description: Representative face-match response (modeled).
      properties:
        status:
          type: string
          example: success
        statusCode:
          type: string
          example: '200'
        result:
          type: object
          properties:
            match:
              type: object
              properties:
                value:
                  type: string
                  description: Match verdict (e.g. yes/no).
                confidence:
                  type: string
                  description: Match confidence/score.
    Error:
      type: object
      properties:
        status:
          type: string
          example: failure
        statusCode:
          type: string
          example: '401'
        error:
          type: string
          example: Invalid credentials.