📄 How to Identify Failed Steps in an ID360 JSON Report

When an ID360 verification returns a KO ❌ status, it is possible to analyze the cause by checking the structure of the JSON file 📂. Here are the paths to follow to find the relevant information 🔍.

⚠️ Important: You must review all the steps described in this guide 🗂️, even if certain keys or sections of the JSON file are not present at the current moment in your workflow.
Each JSON key corresponds to a specific configuration of the workflow 🛠️.

🔄 If your process configuration changes (adding ➕, removing ➖, or modifying ✏️ steps or checks), the list of possible errors will also change.
Therefore, the absence of a key in today’s JSON does not guarantee it will be absent tomorrow.

✅ For this reason, it is essential to review all the steps mentioned in this guide in order to anticipate and properly handle future changes 🚀.

JSON Path: all_status_codes

This array contains the major errors detected during verification.

Each status_code element contains:

• code: the error code (e.g., VLD_VALIDATION_KO, exhaustive list here))
• message: a description of the failed validations

Example:

{
  "all_status_codes": [{
     "status_code": {
        "code": "VLD_VALIDATION_KO",
        "message": "1 validations failed: . Max allowed: 0"
        },
        "where": "ID360"
      },{
     "status_code": {
        "code": "MDL_INPUT_INVALID",
        "message": "No MRZ could be read on the uploaded image(s)"
       },
       "where": "id_document"
      },{
      "status_code": {
        "code": "VLD_ID_INVALID",
        "message": "Id from id_document_result is ignored because the format is not recognized"
        },
        "where": "validation"
      }]
}

🎯 Purpose: Identification of major errors.

JSON Path: finalizer_reports > validator_report > validations

Each validation represents a business rule applied to a data field.

Check for:

• is_valid: false → indicates a failed validation
• ref: rule identifier (e.g., IDENTITY.FIRST_NAME.first_name)
• fields: affected data

Example:

{
  "ref": "IDENTITY.FIRST_NAME.first_name",
  "is_valid": false,
  "fields": [...]
}

🎯 Use Case: Identify which user data failed the controls.

⚠️ Note: For last name comparisons, two checks are performed: one on the preferred name, the other on the birth name. Therefore, you may see the field “ref”: “IDENTITY.NAME.name” appear twice. If either check is successful, the name comparison should be considered passed.

JSON Path: finalizer_reports > validator_report > comparisons

These blocks compare values from multiple sources (e.g., user input vs. documents, or between documents).

Check for:

• is_equivalent: false → comparison failed
• ref: rule identifier
• field1 and field2: the values being compared

Example:

{
  "ref": "KBIS.SIREN.siren",
  "is_equivalent": false,
  "field1": {...},
  "field2": {...}
}

🎯 Use Case: Detect inconsistencies between documents or between documents and user input.

JSON Path: finalizer_reports > validator_report > customs

These checks are client-specific or related to particular document types.

Check for:

• is_valid: false → custom rule failed
• ref: rule name
• fields: data fields being evaluated

Example:

{
  "ref": "IDENTITY_DOCUMENT.document_number",
  "is_valid": false,
  "fields": [...]
}

🎯 Use Case: Understand failures on custom rules defined for a specific client.

JSON Path: steps

The steps block contains the various steps of the process. For each step, you should:

• Read the status field
• If the value is KO, review the status_codes list within that step to understand the causes

Example:

"steps": {
  "id_document": {
    "status": "KO",
    "status_codes": [
      {
        "code": "MDL_INPUT_INVALID",
        "message": "No MRZ could be read on the uploaded image(s)"
      }
    ]
  }
}

🎯 Use Case: Helps isolate which steps failed and provides contextual details on the encountered issues.