​
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

{
  "statusCode": 200,
  "apiType": "id_recognition",
  "transactionId": "txn_123456789",
  "result": {
    "documentInfo": {
      "documentType": "National ID",
      "issuingCountry": "USA",
      "documentNumber": "123456789",
      "issueDate": "2020-01-15",
      "expiryDate": "2030-01-15",
      "issuingAuthority": "Department of Motor Vehicles"
    },
    "personalInfo": {
      "fullName": "John Michael Smith",
      "firstName": "John",
      "middleName": "Michael",
      "lastName": "Smith",
      "dateOfBirth": "1985-03-15",
      "gender": "M",
      "nationality": "USA",
      "address": {
        "street": "123 Main Street",
        "city": "Springfield",
        "state": "IL",
        "zipCode": "62701",
        "country": "USA"
      }
    },
    "verificationStatus": {
      "isValid": true,
      "confidence": 0.95,
      "verificationScore": 0.92,
      "securityFeatures": {
        "hologram": true,
        "uvElements": true,
        "microprinting": true
      }
    },
    "ocrData": {
      "extractedText": "Complete extracted text from document",
      "confidence": 0.98,
      "processingTime": 2.5
    }
  }
}

​
Response Fields

​
Status Information

  • statusCode: HTTP status code (200 for success)
  • apiType: Always “id_recognition” for this API
  • transactionId: Unique transaction identifier

​
Document Information

  • documentType: Type of identification document
  • issuingCountry: Country that issued the document
  • documentNumber: Unique document identifier
  • issueDate: Date when document was issued
  • expiryDate: Date when document expires
  • issuingAuthority: Government authority that issued the document

​
Personal Information

  • fullName: Complete name as shown on document
  • firstName: First name
  • middleName: Middle name (if available)
  • lastName: Last name
  • dateOfBirth: Date of birth
  • gender: Gender (M/F)
  • nationality: Nationality
  • address: Complete address information

​
Verification Status

  • isValid: Boolean indicating if document is valid
  • confidence: Overall confidence score (0-1)
  • verificationScore: Verification accuracy score
  • securityFeatures: Security features detected

​
OCR Data

  • extractedText: All text extracted from document
  • confidence: OCR confidence score
  • processingTime: Time taken for processing

​
Error Responses

{
  "statusCode": 400,
  "apiType": "id_recognition",
  "transactionId": "txn_123456789",
  "error": {
    "code": "INVALID_IMAGE",
    "message": "One or both images are invalid or corrupted"
  }
}

​
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