Cross-validates user-entered identity details against OCR (or QR) output for PAN, Aadhaar, Passport, and Voter ID during onboarding, returning per-field match results. JSON with appId/appKey headers.
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.