Access Documentation
OCR
ID Card OCR
ID Card OCR
# Card/ID OCR Recognition
# 1 Description
Provides an OCR recognition service for overseas cards and IDs.
Supports four-corner detection, quality detection, recapture (screen shot) detection, PS (Photoshop tampering) detection, AIGC detection, and watermark detection.
Supported document scope:
| Document Type | Supported Countries |
|---|---|
| ID Card | Indonesia, Philippines, Mexico |
# 2 Usage
# 2.1 Invoke URL
Singapore: https://api-sgp.yljz.com/finauth/v5/oversea_ocr
Indonesia: https://api-idn.yljz.com/finauth/v5/oversea_ocr
# 2.2 Invoke Method
Request method: POST
Request format: form-data
Description: The client passes the encrypted signature sign generated from the apikey and secret, together with a photo containing the document. FinAuth returns the recognition result of the document.
# 3 Request Parameters
| Parameter | Name | Required | Type | Description |
|---|---|---|---|---|
| sign | Signature | Yes | String | For the signature generation rules, see Authentication. |
| sign_version | Signature algorithm version | Yes | String | Pass: hmac_sha1 |
| certificate_id | Document type ID | Yes | String | Mexico voter ID: MX_ID; Indonesian ID card: ID_ID; Philippine ID card: PH_ID |
| image | Image | Yes | File | A photo containing the card/ID taken by the client (the client must ensure photo quality; FinAuth does not perform quality checks). Image limits: 1. File size ≤ 5 MB; 2. Resolution ≤ 5000×5000 px; 3. Format: JPG/JPEG/PNG. |
| biz_no | Business serial number | No | String | The business serial number for this request. |
| quad_detection | Four-corner detection | No | String | Default 0. 0: enable four-corner detection only, do not return the cropped image. 1: enable four-corner detection and return the cropped image. |
| screen | Recapture detection | No | String | Default 0 (disabled). 0: disable recapture detection; 1: enable recapture detection. |
| extract | Enable recognition | No | String | Default 1 (enabled). 0: disable recognition; 1: enable recognition. |
| quality | Quality detection | No | String | Default 0 (disabled). 0: disable quality detection; 1: enable quality detection. |
| ps | PS detection | No | String | Default 0 (disabled). 0: disable; 1: enable. |
| aigc | AIGC detection | No | String | Default 0 (disabled). 0: disable; 1: enable. |
| watermark | Watermark detection | No | String | Default 0 (disabled). 0: disable; 1: enable. |
| photocopy | Photocopy detection | No | String | Default 0 (disabled). 0: disable; 1: enable. |
| sticker | Sticker detection | No | String | Default 0 (disabled). 0: disable; 1: enable. |
| face_detect | Return the document portrait | No | String | Default 0 (disabled, not yet supported). 0: disable; 1: enable. |
# 4 Response Parameters
Note: Different document types return only the applicable subset of fields, not all fields.
| Field | Name | Type | Description |
|---|---|---|---|
| request_id | Request ID | String | A unique string that identifies each request. This field is always returned except when a 404 (API_NOT_FOUND) or 403 (AUTHORIZATION_ERROR) error occurs. |
| time_used | Time used | Int | The total time taken by the request, in milliseconds. This field is always returned. |
| biz_no | Business serial number | String | The business serial number that was passed in, returned unchanged. |
| extract_result | Recognition result | JSON | JSON format (if multiple documents appear in the image, only the information of the document with the highest confidence for the document number is returned). The content differs by document type ID. |
| quad_detection | Four-corner detection result | String | Effective when quad_detection=0/1. 0: four-corner detection passed; 1: four-corner detection failed. Returns null when the service is unavailable. |
| quad_detection_image | Four-corner cropped image | String | Returned as Base64 encoding when quad_detection=1. |
| quality | Quality result | String | Effective when quality=1. 0: quality is normal; 1: quality issue detected. Returns null when the service is unavailable. |
| ps | PS detection result | JSON | Effective when ps=1. 0: no PS tampering; 1: the document shows PS tampering. Returns null when the service is unavailable. |
| aigc | AIGC detection result | String | Effective when aigc=1. 0: not an AIGC document; 1: AIGC document. Returns null when the service is unavailable. |
| watermark | Watermark detection result | String | Effective when watermark=1. 0: no watermark; 1: the image contains a watermark. Returns null when the service is unavailable. |
| photocopy | photocopy detection result | String | Effective when photocopy=1. 0: no photocopy; 1: the image contains a photocopy. Returns null when the service is unavailable. |
| sticker | sticker detection result | String | Effective when sticker=1. 0: no sticker; 1: the image contains a sticker. Returns null when the service is unavailable. |
| error | Error message | String | When an error occurs, the corresponding error code is returned. |
# 5 Error Code Reference
| HTTP Status Code | Return Code | Billable | Description |
|---|---|---|---|
| 200 | SUCCESS | Yes | The call succeeded. |
| 400 | INVALID_IMAGE_SIZE: image | No | A single photo in the client's request exceeds the 5 MB limit. This error is returned as plain text, not JSON. |
| 400 | MISSING_ARGUMENTS: | No | A required parameter is missing. |
| 400 | BAD_ARGUMENTS: | No | A parameter failed to parse (for example, it must be a number but a string was provided; or it is too long; or the photo cannot be parsed). |
| 400 | ID_CARD_NOT_FOUND | No | No card/ID was found in the image, or it could not be recognized due to poor quality. |
| 404 | API_NOT_FOUND | No | The API being called does not exist. |
| 403 | AUTHORIZATION_ERROR | No | Invalid signature. |
| 403 | AUTHORIZATION_ERROR: | No | The api_key is disabled, the call limit is exceeded, there is no permission to call this API, or no permission to call this API with the current method. Values: 5001: api_key has no permission or is disabled; 5002: unauthorized IP (reserved); 5007: the api_key has reached its call limit for this API (only when the api_key is a test key). |
| 403 | CONCURRENCY_LIMIT_EXCEEDED | No | The concurrency limit is exceeded. |
| 500 | INTERNAL_ERROR | No | Internal server error. When this occurs, retry the request. If it persists, contact enterprise customer service promptly. |
# 6 Recognition Result by Document Type (extract_result)
# 6.1 Mexico Voter ID (MX_ID)
| Field Name | Type | Description | Example |
|---|---|---|---|
| name | string | Full name, concatenated in the order Given Name(s) + Paternal Surname + Maternal Surname. | MARGARITA GOMEZ VELAQUEZ |
| patName | string | Paternal surname (Paternal Surname). | GOMEZ |
| matName | string | Maternal surname (Maternal Surname). | VELAQUEZ |
| givenName | string | Given name(s) (Given Name(s)). | MARGARITA |
| gender | "M"|"F" | Gender. | M (male), F (female) |
| dob | string | Date of birth, format: YYYY-MM-DD. | 1980-07-05 |
| address | string | Address. | C PITAGORAS 1253 INT.4 COL.MORELOS |
| electorKey | string | Elector key (CLAVE DE ELECTOR). | GMVLMR80070501M100 |
| no | string | CURP number. | GOVM800705MCLMLR01 |
| stateCode | string | State code (ESTADO). | 9 |
| municipality | string | Municipality code (MUNICIPIO). | 4 |
| locality | string | Locality code (LOCALIDAD). | 1 |
| section | string | Section number (SECCIÓN). | 747 |
| registrationYear | string | Year of registration (AÑO DE REGISTRO). | 2008-02-01 |
| validThru | string | Valid through. | 2014-2024 |
| cic | string | Voter credential identification code (CIC), common on newer INE cards, usually 9 digits, returned only for the back side. | 074711637 |
| ocr | string | Voter ID OCR number, returned only for the back side. | 0747116375842 |
| isCard | string | Whether it is a card/ID: "true"/"false". | true |
| type | string | Voter ID version type. Possible values: A-D/E/F/G/H/I/J/back/other, where A-D are deprecated versions. When the front of a voter ID is passed, the version is returned; when the back is passed, back is returned; when another card type or a non-card image is passed, other is returned. |
G |
# 6.2 Indonesian ID Card (ID_ID)
| Field Name | Type | Description | Example |
|---|---|---|---|
| name | string | Name. | HERMAWAN |
| no | string | ID card number. | 3216082311830005 |
| pob | string | Place of birth. | JAKARTA |
| dob | string | Date of birth, format: YYYY-MM-DD. | 1983-11-23 |
| gender | string | Gender. | M |
| blood | string | Blood type. | null |
| address | string | Address. | JL POLONG 12 CS |
| rt_rw | string | Neighborhood/community code (RT/RW — Rukun Tetangga / Rukun Warga). | 008/007 |
| kel_desa | string | Village/urban ward (Kelurahan/Desa). | RATU JAYA |
| kecamatan | string | District (Kecamatan). | CIPAYUNG |
| city_regency | string | City/regency. | KOTA DEPOK |
| province | string | Province. | JAWA BARAT |
| religion | string | Religion. | ISLAM |
| marital | string | Marital status. | KAWIN |
| occup | string | Occupation. | KARYAWAN SWASTA |
| nationality | string | Nationality. | WNI |
| validThru | string | Valid through. | SEUMUR HIDUP |
| isCard | string | Whether it is a card/ID: "true"/"false". | true |
# 6.3 Philippine ID Card (PH_ID)
| Field Name | Type | Description | Example |
|---|---|---|---|
| givenName | string | Given name. | MARIBEL |
| middleName | string | Middle name. | BARONIA |
| surname | string | Surname. | TUBO |
| gender | string | Gender. | null |
| dob | string | Date of birth, format: YYYY-MM-DD. | 1979-11-25 |
| pob | string | Place of birth. | |
| blood | string | Blood type. | |
| marital | string | Marital status. | |
| no | string | Document number. | 6041730912782534 |
| address | string | Address. | # 160, MUNLAWIN NORTE, ALITAGTAG, BATANGAS, PHILIPPINES, 4205 |
| issDate | string | Issue date. | |
| isCard | string | Whether it is a card/ID: "true"/"false". | true |
# 7. Response Example
# 7.1 MX_ID Example
{
"request_id": "b4f2c8e1-9a3d-4f6b-8c2e-1d5a7b9c0e3f",
"time_used": 863,
"biz_no": "202608070001",
"extract_result": {
"name": "MARGARITA GOMEZ VELAQUEZ",
"patName": "GOMEZ",
"matName": "VELAQUEZ",
"givenName": "MARGARITA",
"gender": "M",
"dob": "1980-07-05",
"address": "C PITAGORAS 1253 INT.4 COL.MORELOS",
"electorKey": "GMVLMR80070501M100",
"no": "GOVM800705MCLMLR01",
"stateCode": "9",
"municipality": "4",
"locality": "1",
"section": "747",
"registrationYear": "2008-02-01",
"validThru": "2014-2024",
"cic": "074711637",
"ocr": "0747116375842",
"isCard": "true",
"type": "G"
},
"quad_detection": "0",
"quad_detection_image": "/9j/4AAQSkZJRgABAQA...（Base64，when quad_detection=1）",
"quality": "0",
"screen": "0",
"ps": "0",
"aigc": "0",
"watermark": "0"
"photocopy": "0"
"sticker": "0"
}
# 7.2 IND_ID Example
{
"request_id": "c7e5d2a1-8b4f-4a3c-9e6d-2f8b1c4d5e6f",
"time_used": 572,
"biz_no": "202608070002",
"extract_result": {
"name": "HERMAWAN",
"no": "3216082311830005",
"pob": "JAKARTA",
"dob": "1983-11-23",
"gender": "M",
"blood": null,
"address": "JL POLONG 12 CS",
"rt_rw": "008/007",
"kel_desa": "RATU JAYA",
"kecamatan": "CIPAYUNG",
"city_regency": "KOTA DEPOK",
"province": "JAWA BARAT",
"religion": "ISLAM",
"marital": "KAWIN",
"occup": "KARYAWAN SWASTA",
"nationality": "WNI",
"validThru": "SEUMUR HIDUP",
"isCard": "true"
},
"quad_detection": "0",
"quality": "0",
"screen": "0"
}
# 7.3 PHI_ID Example
{
"request_id": "d9f6e3b2-9c5a-4b7d-8f1e-3a9c2d5e6f7a",
"time_used": 641,
"biz_no": "202608070003",
"extract_result": {
"givenName": "MARIBEL",
"middleName": "BARONIA",
"surname": "TUBO",
"gender": null,
"dob": "1979-11-25",
"pob": "",
"blood": "",
"marital": "",
"no": "6041730912782534",
"address": "# 160, MUNLAWIN NORTE, ALITAGTAG, BATANGAS, PHILIPPINES, 4205",
"issDate": "",
# 7.4 Fail Response Example
{
"request_id": "e1f7a4c3-0d6b-4c8e-9a2f-4b1d3e6f7a8b",
"time_used": 120,
"error": "ID_CARD_NOT_FOUND"
}