​
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

​
Sample Response for success

{
  "statusCode": 200,
  "apiType": "id_recognition",
  "result": {
    "data": {
      "raw": {
        "address": {
          "value": "{{value}}",
          "score": 34,
          "coordinates": {
            "first": {
              "x": 410,
              "y": 1237
            },
            "fourth": {
              "x": 415,
              "y": 1362
            },
            "second": {
              "x": 560,
              "y": 1237
            },
            "third": {
              "x": 564,
              "y": 1362
            }
          }
        },
        "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