This document outlines the structure and meaning of the JSON response from the Identity Verification API. The response provides a comprehensive analysis of a user's identity based on their submitted document (ID card) and a selfie.
JSON Structure Overview
The main components of the JSON response are:
document: Contains the extracted information and analysis of the identification document.selfie: Contains the analysis of the user's selfie.face_match: A boolean indicating if the face in the selfie matches the face on the document.curp: Provides details and validation of the user's CURP.unico: Internal process identifier.label: A summary classification of the verification result.reason: An array of strings explaining thelabel.request_id: A unique identifier for the API request.
1. Root Level Fields
These fields provide the final summary and identifiers for the verification request.
| Field | Type | Description |
|---|---|---|
face_match | Boolean | Indicates whether the face from the selfie successfully matches the face on the document. true if they match. |
label | String | A final classification label for the verification inquiry. e.g., "Potential Threat" / "Review" / "No Threat". |
reason | Array | An array of strings detailing the reasons for the assigned label. |
request_id | String | A unique identifier for this specific API request. |
2. document Object
document ObjectThis object encapsulates all data extracted and analyzed from the user's identification document.
| Field | Type | Description |
|---|---|---|
details | Object | Contains metadata about the document processing. |
front | Object | Contains all information extracted from the front of the document. |
back | Object | Contains all information extracted from the back of the document. |
2.1. document.details
document.details| Field | Type | Description |
|---|---|---|
detected | Boolean | Indicates if a document was successfully detected in the image. |
forensics | Object | Contains results from forensic analysis of the document. |
document_id | Integer | A unique identifier for the processed document. |
2.1.1. document.details.forensics
document.details.forensics| Field | Type | Description |
|---|---|---|
is_valid | String | The result of the forensic analysis to determine the document's authenticity. e.g., "inconclusive". |
2.2. document.front
document.frontThis object contains the information extracted from the front of the ID and the facial analysis results for the document photo.
| Field | Type | Description |
|---|---|---|
information | Object | A collection of all textual data extracted from the document's front side. |
face_analysis | Object | Results from the analysis of the face photo found on the document. |
2.2.1. document.front.information
document.front.informationEach field in this object contains a text value (the extracted string) and a valid boolean.
| Field | Description |
|---|---|
birthdate | User's date of birth. |
sex | User's sex/gender. |
registration_year | Year the document was registered. |
name | User's first name(s). |
mother_last_name | User's maternal last name. |
last_name | User's paternal last name. |
electoral_key | The electoral key from the document. |
curp | The CURP extracted from the document. |
address | The user's address. |
complete_name | The user's full name. |
valid_thru | The document's expiration year. |
2.2.2. document.front.face_analysis
document.front.face_analysisThis object contains the analysis of the face found on the ID document.
| Field | Type | Description |
|---|---|---|
face_id | Integer | A unique identifier for this specific face instance. |
first_seen | String | Timestamp of the first time this face was ever seen in the system. |
unique_face_id_v2 | Integer | A persistent and unique identifier for this physical face across all inquiries (version 2). |
face_id_v2 | Integer | Another unique identifier for the face instance (version 2). |
inquiry_date | String | Timestamp of the current verification inquiry. |
last_seen | String | Timestamp of the most recent time this face was seen anywhere in the network. |
last_seen_by_your_company | String | Timestamp of the most recent time this face was seen in an inquiry by your company. |
match | Boolean | Indicates if this face is a potential match with other faces in the database. |
match_fraud_flag | Boolean | Indicates if this face has been associated with fraudulent activity. |
seen_by_your_company | Boolean | Indicates if this face has been previously seen in an inquiry by your company. |
seen_different_companies | Integer | The number of other companies in the network that have seen this face. |
times_seen_by_your_company | Integer | The total number of times this face has been seen in inquiries by your company. |
times_seen_last_month | Integer | The number of times this face has been seen in the last month across the network. |
warnings | Object | Contains specific warnings related to the face analysis. |
warnings.external_id | String | A warning message indicating that the user's face is associated with multiple different external IDs. |
2.3. document.back
document.backThis object contains information extracted from the Machine-Readable Zone (MRZ) on the back of the document.
| Field | Type | Description |
|---|---|---|
mrz | String | The full Machine-Readable Zone string. |
cic | String | The "CIC" number extracted from the MRZ. |
citizen_id | String | The citizen identification number from the MRZ. |
3. selfie Object
selfie ObjectThis object contains the analysis results for the user's submitted selfie image. Its structure is very similar to document.front.face_analysis.
| Field | Type | Description |
|---|---|---|
face_id | Integer | A unique identifier for this specific selfie instance. |
first_seen | String | Timestamp of the first time this selfie's face was ever seen in the system. |
unique_face_id_v2 | Integer | A persistent and unique identifier for this physical face across all inquiries (version 2). |
face_id_v2 | Integer | Another unique identifier for the face instance (version 2). |
inquiry_date | String | Timestamp of the current verification inquiry. |
last_seen | String | Timestamp of the most recent time this face was seen anywhere in the network. |
last_seen_by_your_company | String | Timestamp of the most recent time this face was seen in an inquiry by your company. |
match | Boolean | Indicates if this face is a potential match with other faces in the database. |
match_fraud_flag | Boolean | Indicates if this face has been associated with fraudulent activity. |
seen_by_your_company | Boolean | Indicates if this face has been previously seen in an inquiry by your company. |
seen_different_companies | Integer | The number of other companies in the network that have seen this face. |
times_seen_by_your_company | Integer | The total number of times this face has been seen in inquiries by your company. |
times_seen_last_month | Integer | The number of times this face has been seen in the last month across the network. |
warnings | Object | Contains specific warnings related to the selfie analysis. |
warnings.external_id | String | A warning message indicating that the selfie face is associated with multiple different external IDs. |
first_seen_image | Boolean | Indicates if this is the first time this exact image has been seen. |
4. curp Object
curp ObjectThis object provides a detailed breakdown and validation of the user's CURP against official government records.
| Field | Type | Description |
|---|---|---|
curp | String | The CURP string being analyzed. |
state_of_birth | String | The user's state of birth as decoded from the CURP. |
state_iso | String | The ISO 3166-2 code for the state of birth. |
date_of_birth | String | The user's date of birth as decoded from the CURP. |
age | Integer | The calculated age of the user. |
gender | String | The user's gender as decoded from the CURP (M for Male/Masculino). |
is_mexican | Boolean | Indicates if the CURP corresponds to a Mexican citizen. |
name_to_CURP_valid | Boolean | Indicates if the name provided in the request is consistent with the name associated with the CURP. |
government_valid | Boolean | Indicates if the CURP is valid according to official government databases (RENAPO). |
government_name | String | The full name associated with the CURP in the official government database. |
deceased | Boolean | Indicates if the person associated with the CURP is marked as deceased. |
error | String | Indicates if the CURP exists in RENAPO |
5. unico Object
unico ObjectThis object contains internal identifiers related to the verification process.
| Field | Type | Description |
|---|---|---|
process_id | String | A unique identifier for the backend process that ran this check. |
result | null | A field reserved for results from specific sub-processes; null if not applicable. |
EXAMPLE
{
"document": {
"details": {
"detected": true,
"forensics": {
"is_valid": "valid"
},
"document_id": 8172635
},
"front": {
"information": {
"birthdate": {
"text": "15/04/1995",
"valid": true
},
"sex": {
"text": "M",
"valid": true
},
"registration_year": {
"text": "2013 02",
"valid": true
},
"name": {
"text": "SOFIA ELENA",
"valid": true
},
"mother_last_name": {
"text": "GARCIA",
"valid": true
},
"last_name": {
"text": "MENDOZA",
"valid": true
},
"electoral_key": {
"text": "MNDGSE95041518M700",
"valid": true
},
"curp": {
"text": "MEGA950415MDFRRN07",
"valid": true
},
"address": {
"text": "CTO. INTERIOR AV. REVOLUCION 123, COL. SAN MIGUEL CHAPULTEPEC, 11850, MIGUEL HIDALGO, CDMX",
"valid": true
},
"complete_name": {
"text": "MENDOZA GARCIA SOFIA ELENA",
"valid": true
},
"valid_thru": {
"text": "2033",
"valid": true
}
},
"face_analysis": {
"face_id": 9988771,
"first_seen": "01/10/2024, 10:15:20",
"unique_face_id_v2": 102938,
"face_id_v2": 4455667,
"inquiry_date": "06/17/2025, 11:20:05",
"last_seen": "03/22/2025, 18:00:00",
"last_seen_by_your_company": "06/17/2025, 11:20:05",
"match": true,
"match_fraud_flag": false,
"seen_by_your_company": true,
"seen_different_companies": 1,
"times_seen_by_your_company": 3,
"times_seen_last_month": 1,
"warnings": {}
}
},
"back": {
"mrz": "IDMEXMENDOZA<<GARCIA<SOFIA<ELENA<<9504151M3312316MEX<08<<12345<6",
"cic": "112233445",
"citizen_id": "098765432"
}
},
"selfie": {
"face_id": 9988770,
"first_seen": "01/10/2024, 10:15:20",
"unique_face_id_v2": 102938,
"face_id_v2": 4455668,
"inquiry_date": "06/17/2025, 11:20:05",
"last_seen": "03/22/2025, 18:00:00",
"last_seen_by_your_company": "06/17/2025, 11:20:05",
"match": true,
"match_fraud_flag": false,
"seen_by_your_company": true,
"seen_different_companies": 1,
"times_seen_by_your_company": 3,
"times_seen_last_month": 1,
"warnings": {},
"first_seen_image": false
},
"face_match": true,
"curp": {
"curp": "MEGA950415MDFRRN07",
"state_of_birth": "Ciudad de México",
"state_iso": "MX-CMX",
"date_of_birth": "15/04/1995",
"age": 30,
"gender": "F",
"is_mexican": true,
"name_to_CURP_valid": true,
"government_valid": true,
"government_name": "SOFIA ELENA MENDOZA GARCIA",
"deceased": false
},
"unico": {
"process_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
"result": null
},
"label": "Potential Threat",
"reason": [
"The user's face was found in the company database with another external_id",
"The user's face on the document was flagged as identity fraud by a company on the Trully network",
"The user's face on the document was found in the company database with another external_id",
],
"request_id": "req_abc123def456ghi789"
}