ID Card Validation API

The following document highlights the details of the ID Card Validation API.

API Description

Objective

The ID Card Validation API extracts text from officially valid documents (OVDs) while conducting supplementary image checks for thorough verification.

Input	Output
An image of any officially valid document supported by HyperVerge, along with the associated country and document type	The data extracted from the image

API URL

https://{regionCode}.idv.hyperverge.co/v1/readId

API Endpoint

readId

regionCode Details

The {regionCode} placeholder accepts the following values. For example: https://ind.idv.hyperverge.co/v1/readId

Region	regionCode Value
India	ind
USA	usa
Africa	zaf
Europe	irl
Singapore	sgp

Overview

The ID Card Validation API is RESTful and uses standard HTTP verbs and status codes. Responses are in JSON format. Upload all images and files as form-data through a POST request.

Method - `POST`

Authentication

You need a unique pair of application ID (appId) and application key (appKey) from HyperVerge to access the API.

Headers

Header	Mandatory / Optional	Description	Input Format
`content-type`	Mandatory	Defines the media type for the request payload.	`multipart/form-data`
`appId`	Mandatory	The application ID shared by HyperVerge. You can find the details in the dashboard's credentials tab.	This should be a unique value
`appKey`	Mandatory	The application key shared by HyperVerge. You can find the details in the dashboard's credentials tab.	This should be a unique value
`transactionId`	Mandatory	A unique identifier for tracking a user journey.	This should be both unique and easily associated with the user's journey in your application(s)

Inputs

The following table provides the details of the parameters required for the ID Card Validation API request body:

Parameter	Mandatory / Optional	Type	Description	Input Format	Default Value
`image` or `pdf`	Mandatory	file	The image file or PDF of the ID document.	JPG, JPEG, PNG, or PDF	Not Applicable
`countryId`	Mandatory	string	The 3-letter alpha code of the country. See the list of supported countries and country IDs.	Not Applicable	Not Applicable
`documentId`	Mandatory	string	The ID of the document. See the list of supported documents and document IDs.	Not Applicable	Not Applicable
`expectedDocumentSide`	Optional	string	The expected side of the document.	`front` / `back`	Not Applicable
`shouldSupportEPAN`	Optional	string	Enables support for ePAN documents during ID processing.	`yes` / `no`	`no`
`shouldSupportDigilockerPAN`	Optional	string	Enables support for DigiLocker PAN documents during ID processing.	`yes` / `no`	`no`

Request

The following code snippet demonstrates a standard curl request for the ID Card Validation API:

curl --location --request POST 'https://ind.idv.hyperverge.co/v1/readId' \
--header 'Content-Type: multipart/form-data' \
--header 'appId: <Enter_the_App_ID>' \
--header 'appKey: <Enter_the_App_Key>' \
--header 'transactionId: <Enter_the_Transaction_ID>' \
--form 'image=@"<Enter_the_File_Path>"' \
--form 'countryId="<Enter_the_Country_ID>"' \
--form 'documentId="<Enter_the_Document_ID>"' \
--form 'expectedDocumentSide="<front_or_back>"' \
--form 'shouldSupportEPAN="<Enter_the_Yes_Or_No>"' \
--form 'shouldSupportDigilockerPAN="<Enter_the_Yes_Or_No>"'

Success Response

The following code snippet demonstrates a success response from the ID Card Validation API:

{
  "status": "success",
  "statusCode": "200",
  "result": {
    "details": [
      {
        "idType": "<ID_Type>",
        "fieldsExtracted": {
          "firstName": { "value": "<First_Name>", "confidence": "<high/low>" },
          "middleName": { "value": "<Middle_Name>", "confidence": "<high/low>" },
          "lastName": { "value": "<Last_Name>", "confidence": "<high/low>" },
          "fullName": { "value": "<Full_Name>", "confidence": "<high/low>" },
          "dateOfBirth": { "value": "<Date_Of_Birth>", "confidence": "<high/low>" },
          "dateOfIssue": { "value": "<Date_Of_Issue>", "confidence": "<high/low>" },
          "dateOfExpiry": { "value": "<Date_Of_Expiry>", "confidence": "<high/low>" },
          "countryCode": { "value": "<Country_Code>", "confidence": "<high/low>" },
          "type": { "value": "<Document_Type>", "confidence": "<high/low>" },
          "gender": { "value": "<Gender>", "confidence": "<high/low>" },
          "address": {
            "value": "<Address>",
            "street": "<Street>",
            "district": "<District>",
            "zipCode": "<Zip_Code>",
            "province": "<Province>",
            "houseNumber": "<House_Number>",
            "additionalInfo": "<Additional_Info>",
            "confidence": "<high/low>"
          },
          "idNumber": { "value": "<ID_Number>", "confidence": "<high/low>" },
          "placeOfBirth": { "value": "<Place_Of_Birth>", "confidence": "<high/low>" },
          "placeOfIssue": { "value": "<Place_Of_Issue>", "confidence": "<high/low>" },
          "yearOfBirth": { "value": "<Year_Of_Birth>", "confidence": "<high/low>" },
          "age": { "value": "<Age>", "confidence": "<high/low>" },
          "fatherName": { "value": "<Father_Name>", "confidence": "<high/low>" },
          "motherName": { "value": "<Mother_Name>", "confidence": "<high/low>" },
          "husbandName": { "value": "<Husband_Name>", "confidence": "<high/low>" },
          "spouseName": { "value": "<Spouse_Name>", "confidence": "<high/low>" },
          "nationality": { "value": "<Nationality>", "confidence": "<high/low>" },
          "mrzString": { "value": "<MRZ_String>", "confidence": "<high/low>" },
          "homeTown": { "value": "<Home_Town>", "confidence": "<high/low>" }
        }
      }
    ],
    "summary": {
      "action": "<pass/fail/manualReview>",
      "details": []
    }
  },
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

The summary.action field indicates the recommended action for the result. The following are the possible values:

Pass
Fail
Manual Review

{
  "summary": {
    "action": "pass",
    "details": []
  }
}

{
  "summary": {
    "action": "fail",
    "details": [
      {
        "code": "001",
        "message": "Black and white document"
      }
    ]
  }
}

{
  "summary": {
    "action": "manualReview",
    "details": [
      {
        "code": "011",
        "message": "Name confidence is low"
      }
    ]
  }
}

Success Response Details

The following table describes the fields returned in the ID Card Validation API success response:

Parameter	Type	Description
`status`	string	The status of the request.
`statusCode`	string	The HTTP status code of the response.
`result.details[].idType`	string	The type of identification document detected.
`result.details[].fieldsExtracted`	object	The fields extracted from the document. Each field contains a `value` and a `confidence` level (`high` or `low`).
`firstName`	string	The extracted first name.
`middleName`	string	The extracted middle name.
`lastName`	string	The extracted last name.
`fullName`	string	The extracted full name.
`dateOfBirth`	string	The extracted date of birth in DD-MM-YYYY format.
`dateOfIssue`	string	The extracted date of issue.
`dateOfExpiry`	string	The extracted date of expiry.
`countryCode`	string	The extracted country code.
`type`	string	The extracted document type.
`gender`	string	The extracted gender.
`address`	object	The extracted address, broken into sub-fields: `street`, `district`, `zipCode`, `province`, `houseNumber`, and `additionalInfo`.
`idNumber`	string	The extracted ID number.
`placeOfBirth`	string	The extracted place of birth.
`placeOfIssue`	string	The extracted place of issue.
`yearOfBirth`	string	The extracted year of birth.
`age`	string	The extracted age.
`fatherName`	string	The extracted father's name.
`motherName`	string	The extracted mother's name.
`husbandName`	string	The extracted husband's name.
`spouseName`	string	The extracted spouse's name.
`nationality`	string	The extracted nationality.
`mrzString`	string	The extracted Machine Readable Zone (MRZ) string.
`homeTown`	string	The extracted home town.
`result.summary.action`	string	The recommended action: `pass`, `fail`, or `manualReview`.
`metaData.requestId`	string	The unique identifier for the request.
`metaData.transactionId`	string	The transaction ID associated with the request.

Error Responses

The following are sample error responses from the ID Card Validation API:

Error 400 - Input Error
Error 422 - Document Not Detected
Error 423 - Document Not Supported
Error 429 - Rate Limit Exceeded
Error 500/501/503 - Server Error

{
  "status": "failure",
  "statusCode": "400",
  "metadata": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  },
  "result": {
    "error": "API call requires at least one input image"
  }
}

{
  "status": "failure",
  "statusCode": "422",
  "metadata": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  },
  "result": {
    "error": "Document Not Detected"
  }
}

{
  "status": "failure",
  "statusCode": "423",
  "metadata": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  },
  "result": {
    "error": "Document Not Supported"
  }
}

{
  "status": "failure",
  "statusCode": "429",
  "message": "Requests rate limit exceeded"
}

{
  "status": "failure",
  "statusCode": "500",
  "error": "Internal Server Error"
}

Error Response Details

A failure response contains a failure status with a relevant status code and error message. The following table lists the error responses for the ID Card Validation API:

Status Code	Error Message	Error Description	Error Resolution
400	API call requires at least one input image	No image was provided in the request.	Include at least one image in the request.
400	API call handles only up to 1 image	More than one image was sent in the request.	Send only one image per request.
400	TransactionId not detected	The `transactionId` header was not included in the request.	Add the `transactionId` header to the request.
400	countryId/documentId is missing	The `countryId` or `documentId` parameter was not provided.	Include both `countryId` and `documentId` in the request.
401	Missing/Invalid credentials	The request is missing the mandatory `appId` and `appKey` combination or has invalid values.	Verify and provide valid `appId` and `appKey` credentials.
422	Document Not Detected	The AI model could not find a document in the image.	Ensure the image clearly shows the document and retry.
423	Document Not Supported	The document in the image is not supported by the API.	Check the supported documents list and retry with a supported document.
429	Requests rate limit exceeded	The number of transactions per minute has exceeded the limit set for your credentials.	Retry after some time or contact the HyperVerge team to review your rate limit.
500	Internal Server Error	Kindly check the request headers or contact the HyperVerge team for resolution.	Check the request headers or contact the HyperVerge team for resolution.
501	Internal Server Error	An unexpected server error occurred.	Contact the HyperVerge team for resolution.
503	Server busy	The server is overloaded.	Retry after some time or contact the HyperVerge team if the issue persists.

Additional Configurations and Checks

The ID Card Validation API supports additional image checks and configurations beyond text extraction. See the full list here.

caution

If these additional checks or configurations do not appear in the API response, they may not be enabled for your account. Contact the HyperVerge team for resolution.

API Description​

Objective​

API URL​

API Endpoint​

regionCode Details​

Overview​

Method - POST​

Authentication​

Headers​

Inputs​

Request​

Success Response​

Success Response Details​

Error Responses​

Error Response Details​

Additional Configurations and Checks​