Global ID Recognition API - ARGOS Identity

POST

recognition

Recognize and verify ID document

curl --request POST \
  --url https://idverify-api.argosidentity.com/modules/recognition \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "idImage": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==",
  "issuingCountry": "USA",
  "idType": "government_id",
  "idBackImage": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==",
  "callbackUrl": "https://your-domain.com/callback"
}
'

{
  "apiType": "id_recognition",
  "transactionId": "e0nvom3caiis7",
  "result": {
    "data": {
      "raw": {
        "address": {
          "value": "ADDRESS 110, SOMEWHERE STREET",
          "score": 89,
          "coordinates": {
            "first": {
              "x": 95,
              "y": 221
            },
            "fourth": {
              "x": 95,
              "y": 258
            },
            "second": {
              "x": 430,
              "y": 221
            },
            "third": {
              "x": 430,
              "y": 258
            }
          },
          "original_coordinates": {
            "first": {
              "x": 211,
              "y": 714
            },
            "fourth": {
              "x": 213,
              "y": 752
            },
            "second": {
              "x": 553,
              "y": 713
            },
            "third": {
              "x": 554,
              "y": 751
            }
          }
        },
        "authority": {
          "value": "{{value}}",
          "score": 4,
          "coordinates": {
            "first": {
              "x": 796,
              "y": 1460
            },
            "fourth": {
              "x": 799,
              "y": 1637
            },
            "second": {
              "x": 1931,
              "y": 1461
            },
            "third": {
              "x": 1925,
              "y": 1641
            }
          }
        },
        "name": {
          "value": "{{value}}",
          "score": 61,
          "coordinates": {
            "first": {
              "x": 367,
              "y": 462
            },
            "fourth": {
              "x": 375,
              "y": 669
            },
            "second": {
              "x": 1379,
              "y": 454
            },
            "third": {
              "x": 1378,
              "y": 663
            }
          }
        },
        "name_chn": {
          "value": "{{value}}",
          "score": 61,
          "coordinates": {
            "first": {
              "x": 367,
              "y": 462
            },
            "fourth": {
              "x": 375,
              "y": 669
            },
            "second": {
              "x": 1379,
              "y": 454
            },
            "third": {
              "x": 1378,
              "y": 663
            }
          }
        },
        "number": {
          "value": "{{value}}",
          "score": 95,
          "accepted": true,
          "coordinates": {
            "first": {
              "x": 248,
              "y": 698
            },
            "fourth": {
              "x": 256,
              "y": 867
            },
            "second": {
              "x": 1423,
              "y": 691
            },
            "third": {
              "x": 1421,
              "y": 861
            }
          }
        },
        "rotate": {
          "value": "0"
        }
      },
      "ocr": {
        "ocr_fullName": "{{ocr_fullName}}",
        "ocr_firstName": "{{ocr_firstName}}",
        "ocr_middleName": "{{ocr_middleName}}",
        "ocr_lastName": "{{ocr_lastName}}",
        "ocr_gender": "{{ocr_gender}}",
        "ocr_nationality": "{{ocr_nationality}}",
        "ocr_birthDate": "{{ocr_birthDate}}",
        "ocr_identityNumber": "{{ocr_identityNumber}}",
        "ocr_issueDate": "{{ocr_issueDate}}",
        "ocr_expireDate": "{{ocr_expireDate}}",
        "ocr_version": "{{ocr_version}}",
        "ocr_number": "{{ocr_number}}",
        "full_mrz": "{{full_mrz}}",
        "mrz_line1": "{{mrz_line1}}",
        "mrz_line2": "{{mrz_line2}}"
      }
    },
    "review_front": true,
    "review_back": false,
    "document_type": "{{document_type}}"
  }
}

The Global ID Recognition API processes and verifies identification documents by analyzing both the front and back images of the ID, along with the issuing country and ID type. This API ensures the authenticity and validity of the provided ID through detailed OCR (Optical Character Recognition) and provides comprehensive results.

API Overview

The Global ID Recognition API provides a powerful tool for worldwide ID document processing with the following capabilities:

Worldwide Support: Process ID documents from multiple countries
Automatic Recognition: Automatically detect ID type and issuing country
OCR Technology: Advanced optical character recognition for text extraction
Data Extraction: Extract structured data from ID documents
Verification: Verify document authenticity and validity
Multi-Format Support: Handle various ID document formats

Request Parameters

Required Parameters

idImage: Image of the front side of the ID document in base64 format
issuingCountry: The ISO 3 Alpha Country Code of the issuing country for the ID document
idType: The type of the ID document

Optional Parameters

idBackImage: Image of the back side of the ID document in base64 format
callbackUrl: The URL where the recognition results will be sent upon completion

Authentication

x-api-key: API key essential for authentication and access control purposes

Response Format

The API returns detailed recognition results including:

apiType: API type identifier
transactionId: Unique identifier for each request
result: Object containing the processing result
- documentInfo: Extracted document information
- personalInfo: Extracted personal information
- verificationStatus: Document verification status
- data: Object containing extracted data
  - raw: Raw OCR data and coordinate information
    - Each field (address, name, number, authority, etc.) may include:
      - value: Extracted field value (string)
      - score: Recognition confidence score (number)
      - accepted: Field acceptance status (boolean, present only for some fields)
      - coordinates: Coordinate information relative to the processed image (object)
        
        first, second, third, fourth: Four corner coordinate points (x, y) of the rectangle
      - original_coordinates: Coordinate information relative to the original image when the ID photo was taken (object, optional)
        
        first, second, third, fourth: Four corner coordinate points (x, y) relative to the original image
        
        Provided additionally for fields when original coordinate information exists on the back side
  - ocr: Structured OCR data defined by Argos

Supported Countries and ID Types

Major Countries

USA: United States
CAN: Canada
MEX: Mexico
BRA: Brazil
ARG: Argentina
GBR: United Kingdom
DEU: Germany
FRA: France
ESP: Spain
ITA: Italy
KOR: South Korea
JPN: Japan
CHN: China
AUS: Australia
NZL: New Zealand

Check out list of all supported countries at Glossary/Iso alpha 3 country codes

ID Types

government_id: An official identification document issued by a government, typically used for verifying the identity of an individual
passport: An official travel document issued by a government, certifying the holder’s identity and nationality, primarily used for international travel
drivers_license: An official document permitting a specific individual to operate one or more types of motorized vehicles, such as motorcycles, cars, trucks, or buses
residence_permit: An official document that allows a foreign individual to reside in a country for a certain period, typically issued by the immigration authority
vehicle_registration_certificate: An official document providing proof of registration of a vehicle, including details about the vehicle and the owner
visa: An official endorsement placed in a passport indicating that the holder is allowed to enter, leave, or stay for a specified period in a country
aadhaar: A unique 12-digit identification number issued by the Indian government to residents of India, based on their biometric and demographic data
pancard: A permanent account number (PAN) card issued by the Indian government to individuals and entities, used primarily for tax purposes

Check out list of all supported id types for each country at Glossary/Supported id types

Use Cases

KYC Processes: Streamline customer identity verification
Banking: Verify customer identity for account opening
Travel: Process travel documents and visas
Employment: Verify employee identity and work permits
Government Services: Process official identification documents

Processing Modes

Synchronous Processing

Immediate response with recognition results
Best for real-time applications
Direct API response

Asynchronous Processing

Use callback URL for delayed results
Better for batch processing
Detailed callback response format

Image Requirements

File Size

Recommended: Less than 10MB
Maximum: 50MB

Image Quality

Resolution: Minimum 300 DPI recommended
Format: High contrast, well-lit images work best
Orientation: Document should be properly oriented

Supported Formats

JPEG (.jpg, .jpeg)
PNG (.png)

Error Handling

The 400 status code indicates that the request was unacceptable, often due to missing a required parameter. In asynchronous operations, where callbackUrl is provided, the error is detected during request validation.

errorCode Type

The following table shows specific errorCodes returned by the API:

Status Code	errorCode	Description	Detailed
400	1001	Workspace is unavailable	workspace is not currently operating
400	1003	Fail to process data	Server had problem in processing data please retry
400	1005	idImage is required	idImage is not entered
400	1006	issuingCountry is required	issuingCountry is missing
400	1010	callbackUrl is required	callbackUrl is missing
400	1011	Fail to recognize idCard	the idCard’s image is different from issuingCountry and idType
400	1012	Fail to recognize back of an idCard	the idCard’s image is different from issuingCountry and idType
400	1013	Invalid image format	the image is not in Base64 format
400	1014	idType is required	idType is missing
400	1015	invalid inputs : missing fields	field is missing

Authorizations

x-api-key

string

header

required

Body

application/json

idImage

string

required

Image of the front side of the ID document in base64 format. Base64 encoded characters in the payload must not include the MIME type. For example, if the encoded base64 characters are "image/png;base64,/9j/2wBDABQODxIP...", then remove "image/png;base64," and send only the encoded data "/9j/2wBDABQODxIP...".

Example:

"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="

issuingCountry

string

required

The ISO 3 Alpha Country Code of the issuing country for the ID document.

Example:

"USA"

idType

enum<string>

required

The type of the ID document

Available options:

government_id,

passport,

drivers_license,

residence_permit,

vehicle_registration_certificate,

visa,

aadhaar,

pancard

Example:

"government_id"

idBackImage

string

Image of the back side of the ID document in base64 format.

Example:

"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="

callbackUrl

string<uri>

The URL where the recognition results will be sent upon completion. If a callbackUrl is provided, the process works asynchronously. If no callbackUrl is provided, the process operates synchronously.

Example:

"https://your-domain.com/callback"

Response

Successful ID recognition

apiType

string

API type identifier

Example:

"id_recognition"

transactionId

string

Unique identifier for each request

Example:

"txn_123456789"

result

object

Object containing the processing result

Show child attributes

ID Image Best Practice

⌘I

Recognize and verify ID document

curl --request POST \
  --url https://idverify-api.argosidentity.com/modules/recognition \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "idImage": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==",
  "issuingCountry": "USA",
  "idType": "government_id",
  "idBackImage": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==",
  "callbackUrl": "https://your-domain.com/callback"
}
'

{
  "apiType": "id_recognition",
  "transactionId": "e0nvom3caiis7",
  "result": {
    "data": {
      "raw": {
        "address": {
          "value": "ADDRESS 110, SOMEWHERE STREET",
          "score": 89,
          "coordinates": {
            "first": {
              "x": 95,
              "y": 221
            },
            "fourth": {
              "x": 95,
              "y": 258
            },
            "second": {
              "x": 430,
              "y": 221
            },
            "third": {
              "x": 430,
              "y": 258
            }
          },
          "original_coordinates": {
            "first": {
              "x": 211,
              "y": 714
            },
            "fourth": {
              "x": 213,
              "y": 752
            },
            "second": {
              "x": 553,
              "y": 713
            },
            "third": {
              "x": 554,
              "y": 751
            }
          }
        },
        "authority": {
          "value": "{{value}}",
          "score": 4,
          "coordinates": {
            "first": {
              "x": 796,
              "y": 1460
            },
            "fourth": {
              "x": 799,
              "y": 1637
            },
            "second": {
              "x": 1931,
              "y": 1461
            },
            "third": {
              "x": 1925,
              "y": 1641
            }
          }
        },
        "name": {
          "value": "{{value}}",
          "score": 61,
          "coordinates": {
            "first": {
              "x": 367,
              "y": 462
            },
            "fourth": {
              "x": 375,
              "y": 669
            },
            "second": {
              "x": 1379,
              "y": 454
            },
            "third": {
              "x": 1378,
              "y": 663
            }
          }
        },
        "name_chn": {
          "value": "{{value}}",
          "score": 61,
          "coordinates": {
            "first": {
              "x": 367,
              "y": 462
            },
            "fourth": {
              "x": 375,
              "y": 669
            },
            "second": {
              "x": 1379,
              "y": 454
            },
            "third": {
              "x": 1378,
              "y": 663
            }
          }
        },
        "number": {
          "value": "{{value}}",
          "score": 95,
          "accepted": true,
          "coordinates": {
            "first": {
              "x": 248,
              "y": 698
            },
            "fourth": {
              "x": 256,
              "y": 867
            },
            "second": {
              "x": 1423,
              "y": 691
            },
            "third": {
              "x": 1421,
              "y": 861
            }
          }
        },
        "rotate": {
          "value": "0"
        }
      },
      "ocr": {
        "ocr_fullName": "{{ocr_fullName}}",
        "ocr_firstName": "{{ocr_firstName}}",
        "ocr_middleName": "{{ocr_middleName}}",
        "ocr_lastName": "{{ocr_lastName}}",
        "ocr_gender": "{{ocr_gender}}",
        "ocr_nationality": "{{ocr_nationality}}",
        "ocr_birthDate": "{{ocr_birthDate}}",
        "ocr_identityNumber": "{{ocr_identityNumber}}",
        "ocr_issueDate": "{{ocr_issueDate}}",
        "ocr_expireDate": "{{ocr_expireDate}}",
        "ocr_version": "{{ocr_version}}",
        "ocr_number": "{{ocr_number}}",
        "full_mrz": "{{full_mrz}}",
        "mrz_line1": "{{mrz_line1}}",
        "mrz_line2": "{{mrz_line2}}"
      }
    },
    "review_front": true,
    "review_back": false,
    "document_type": "{{document_type}}"
  }
}

ID Liveness

Global ID Recognition

Documentation Index

​API Overview

​Request Parameters

​Required Parameters

​Optional Parameters

​Authentication

​Response Format

​Supported Countries and ID Types

​Major Countries

​ID Types

​Use Cases

​Processing Modes

​Synchronous Processing

​Asynchronous Processing

​Image Requirements

​File Size

​Image Quality

​Supported Formats

​Error Handling

​errorCode Type

Authorizations

Body

Response

API Overview

Request Parameters

Required Parameters

Optional Parameters

Authentication

Response Format

Supported Countries and ID Types

Major Countries

ID Types

Use Cases

Processing Modes

Synchronous Processing

Asynchronous Processing

Image Requirements

File Size

Image Quality

Supported Formats

Error Handling

errorCode Type