Callback Response Examples

Callback Response Examples

The Callback Response Example section offers users a glimpse into the anticipated responses they will receive from API interactions, aiding in the understanding of response structure and format. By leveraging these examples, developers can enhance their integration process and streamline development efforts, ensuring seamless communication between their application and the API. This section serves as a valuable resource for testing and refining integrations effectively.

Overview

When using the Global ID Recognition API with a callback URL, the system processes the request asynchronously and sends the results to your specified callback endpoint. This approach is ideal for batch processing or when you need to handle multiple requests without blocking your application.

Response Structure

The callback response contains the following key components:

• statusCode: HTTP status code indicating the result
• apiType: API type identifier (“id_recognition”)
• transactionId: Unique identifier for tracking the request
• result: Object containing detailed recognition results
  • data: Object containing extracted data
    • raw: Raw OCR data and coordinate information
      • Each field (address, name, number, etc.) may include coordinates and original_coordinates
      • coordinates: Coordinate information relative to the processed image
      • original_coordinates: Coordinate information relative to the original image when the ID photo was taken (optional)
    • ocr: Structured OCR data defined by Argos

Sample Response for success

{
  "statusCode": 200,
  "apiType": "id_recognition",
  "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}}"
  },
  "transactionId": "e0nvom3caiis7"
}

Sample Response for error

{
  "statusCode": 400,
  "apiType": "id_recognition",
  "transactionId": "{{transactionId}}",
  "errorCode": "1011",
  "message": "Fail to recognize idCard"
}

Integration Guidelines

1. Set up your callback endpoint to receive POST requests
2. Validate the transactionId to ensure you’re processing the correct response
3. Check the statusCode to determine if the request was successful
4. Parse the result object to extract document and personal information
5. Handle errors gracefully by checking for error objects in the response

Best Practices

• Implement idempotency using the transactionId to avoid duplicate processing
• Set appropriate timeouts for your callback endpoint
• Log all responses for debugging and monitoring
• Validate response structure before processing the data
• Handle network errors and implement retry logic if needed
• Store extracted data securely following data protection regulations