Emirates ID Verification API - v1

This document outlines the details of the Emirates ID Verification API.

API Description

Objective

The Emirates ID Verification API provides detailed information about an Emirates Identity Card.

Input	Output
The Emirates ID Number	The details associated with the Emirates ID. The complete list of output fields is available in the Success Response Details section.

Did You know?

• The Emirates ID (also known as Emirates Identity Card or EID) is a mandatory identification card for citizens and residents of the United Arab Emirates (UAE). It's managed by the Federal Authority for Identity, Citizenship, Customs and Port Security (ICP) and is essential for accessing government services, legal processes, and other key functions in the UAE.
• The Emirates ID Number is a unique 15-digit number printed on the citizen's Emirates ID card.

API URL

https://ind-thomas.hyperverge.co/v1/emiratesVerification

API Endpoint

emiratesVerification

Overview

The Emirates ID Verification API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format and you should upload all images and files as form-data through a POST request.

Authentication

You need a unique pair of application ID (appId) and application key (appKey) from HyperVerge to verify your identity for accessing the Emirates ID Verification API.

API Request Details

Method - POST

Headers

Header	Mandatory / Optional	Description	Input Format
content-type	Mandatory	This parameter defines the media type for the request payload	application/json
appId	Mandatory	The application identifier shared by HyperVerge. You can find the details in the dashboard's credentials tab.	Not Applicable - this is a unique value
appKey	Mandatory	The application key shared by HyperVerge. You can find the details in the dashboard's credentials tab.	Not Applicable - this is a unique value
transactionId	Mandatory	A unique identifier for tracking a user journey	Not Applicable - this is a unique value related to a transaction in your application

Input

The following table provides the details of the parameter required for the Emirates ID Verification API's request body:

Parameter	Mandatory / Optional	Type	Description	Input Format	Default Value
idNumber	Mandatory	string	The valid Emirates ID Number	A unique 15-digit number	Not Applicable

Request

The following code snippet demonstrates a standard curl request for the Emirates ID Verification API:

curl --location --request POST 'https://ind-thomas.hyperverge.co/v1/emiratesVerification' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--data '{
    "idNumber": "<Enter_the_valid_ID_Number>"
}'

Success Response

The following code snippet demonstrates a success response from the Emirates ID Verification API:

{
  "status": "success",
  "statusCode": 200,
  "result": {
    "idNumber": "<Masked_Emirates_ID_Number>",
    "serviceTransactionName": "<Service_Transaction_Description>",
    "requestDate": "<Request_Date_in_YYYY-MM-DD_Format>",
    "issueDate": "<Issue_Date_in_YYYY-MM-DD_Format>",
    "administration": "<Administration_Name>",
    "applicationFees": "<Application_Fee_Amount>",
    "approvalDate": "<Approval_Date_in_YYYY-MM-DD_Format>"
  },
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Success Response Details

The following table outlines the details of the success response from the Emirates ID Verification API:

Parameter	Type	Description
status	string	The status of the request
statusCode	integer	The HTTP status code returned for the request
idNumber	string	The Emirates ID number used for verification
serviceTransactionName	string	The name of the service transaction associated with the Emirates ID process
requestDate	string	The date on which the request was submitted, in YYYY-MM-DD format
issueDate	string	The date on which the Emirates ID was issued, in YYYY-MM-DD format
administration	string	The name or location of the administration office linked to the Emirates ID. For example, "Dubai" or "Abu Dhabi"
applicationFees	number	The fee charged for the application, in UAE Dirham (AED)
approvalDate	string	The date on which the application was approved, in YYYY-MM-DD format
requestId	string	The unique identifier for the API request
transactionId	string	The transaction ID associated with the request

Error Responses

The following are some error responses from the Emirates ID Verification API:

Invalid ID Number

{
    "status": "failure",
    "statusCode": 400,
    "error": "The ID number is invalid",
    "metaData": {
       "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Missing/Invalid Credentials

{
    "message": "Missing/Invalid credentials",
    "statusCode": 401,
    "status": "failure"
}

Incorrect Format for ID Number

{
    "status": "failure",
    "statusCode": 422,
    "error": "Enter valid 15 digit ID number",
    "metaData": {
       "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Missing Input

{
    "status": "failure",
    "statusCode": 422,
    "error": "ID number should not be empty",
    "metaData": {
       "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Internal Server Error

{
  "status": "failure",
  "statusCode": 500,
  "message": "internal server error"
}

External Downtime

{
    "status": "failure",
    "statusCode": 503,
    "message": "External source downtime",
    "error": "EXTERNAL_DOWNTIME",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Error Response Details

A failure or error response from the Emirates ID Verification API contains a failure status with a relevant status code and error message. The following table lists all error responses:

Status Code	Error Message	Error Description	Error Resolution
400	The ID number is invalid	The input ID number is invalid or does not exist	Verify that the provided Emirates ID number is correct and corresponds to an existing record
401	Missing/Invalid credentials	The request is either missing the mandatory appId and appKey combination or has invalid values	Provide valid appId and appKey in the request headers. Check the dashboard's credentials tab
422	Enter valid 15 digit ID number	The ID number provided is not in the required numeric format; it contains fewer or more than 15 digits, has alphabets, or special characters	Provide a valid 15-digit Emirates ID number in the request
422	ID number should not be empty	The request was made without providing the required ID number	Include a valid idNumber in the request body
500	Internal Server Error	There is an issue with the service. Kindly contact the HyperVerge Team for support.	Contact the HyperVerge team for investigation and resolution
503	External source downtime	The external vendor service is temporarily unavailable	Retry the request after some time. If the issue persists, contact the HyperVerge team