The Callback Response Example section showcases sample responses that users can anticipate from API interactions, providing clarity on response structure and format. By utilizing these examples, users can effectively develop and test their integrations, ensuring smooth communication between their application and the API. This section serves as a valuable resource for enhancing the integration process and streamlining development efforts.

​
Overview

When using the Face Compare 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 (“compare_face”)
  • transactionId: Unique identifier for tracking the request
  • result: Object containing detailed comparison results

​
Sample Response

{
  "statusCode": 200,
  "apiType": "compare_face",
  "transactionId": "txn_123456789",
  "result": {
    "face": {
      "isAvailable": true,
      "boundingBox": {
        "Width": 0.42534321546554565,
        "Height": 0.567890123456789,
        "Left": 0.12345678901234567,
        "Top": 0.23456789012345678
      },
      "confidence": 0.9876543210987654
    },
    "targetFace": {
      "isAvailable": true,
      "boundingBox": {
        "Width": 0.4567890123456789,
        "Height": 0.543210987654321,
        "Left": 0.13456789012345678,
        "Top": 0.24567890123456789
      },
      "confidence": 0.9765432109876543
    },
    "similarity": {
      "score": 0.8543210987654321,
      "threshold": 0.8,
      "isMatch": true
    }
  }
}

​
Response Fields

​
Status Information

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

​
Face Recognition Results

  • isAvailable: Boolean indicating if a face was detected
  • boundingBox: Coordinates of the detected face
    • Width: Width of the bounding box (0-1 scale)
    • Height: Height of the bounding box (0-1 scale)
    • Left: Left coordinate of the bounding box (0-1 scale)
    • Top: Top coordinate of the bounding box (0-1 scale)
  • confidence: Confidence score of face detection (0-1 scale)

​
Similarity Analysis

  • score: Similarity score between the two faces (0-1 scale)
  • threshold: Threshold used for matching (typically 0.8)
  • isMatch: Boolean indicating if faces match based on threshold

​
Error Responses

{
  "statusCode": 400,
  "apiType": "compare_face",
  "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 similarity scores and face detection data
  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