Perform a Likeness (Face Similarity) Check

POST /api/v2/likeness_check operationId: likeness_check

Live: https://gdapi.globaldata.net.au/api/v2/likeness_check · Sandbox: https://sandbox-gdapi.globaldata.net.au/api/v2/likeness_check

Compares two face images (an ID/document or reference image and a probe/selfie image) and returns a similarity score together with a threshold evaluation flag (biometric_passed). The service is intended for validating whether the two supplied images likely represent the same individual.

Inputs

Provide both images as Base64 data URI strings (recommended form: data:image/jpeg;base64,/9j/4AA...) or raw base64 without a prefix. Supported formats are JPEG and PNG. Maximum file size per image is 5 MB.

An optional similarity_threshold (0-100) can be supplied to override the system default. If omitted, the configured default threshold is used when determining biometric_passed.

Similarity & Threshold

The underlying biometric engine returns a similarity value (floating point). The request (or default) threshold is applied: biometric_passed = similarity >= threshold.

Typical Use Case

Capture / obtain an authoritative reference photo (e.g. ID document portrait).
Capture a live probe (selfie) image from the user.
Submit both images to this endpoint.
Use the biometric_passed boolean (and raw similarity) to decide downstream workflow steps.

Error Handling

Validation and processing issues return HTTP 400 with a descriptive message. If multiple validation errors are present, the API returns the first validation message. Face comparison engine errors (for example no_face_found) are also returned as HTTP 400 messages.

Request body

Content type application/json. Two face images (reference & probe) and an optional threshold override.

Field Description

Field	Description
`photo`required	string Base64 (optionally data URI) reference image (e.g. ID/document portrait). JPEG or PNG. Max 5 MB. Example: `data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ...`
`probe_image`required	string Base64 (optionally data URI) probe / selfie image to compare against the reference. JPEG or PNG. Max 5 MB. Example: `data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ...`
`similarity_threshold`	number (float) [0..100] Optional override threshold (0-100). If omitted, system default is used. Example: `80`

photorequired

string

Base64 (optionally data URI) reference image (e.g. ID/document portrait). JPEG or PNG. Max 5 MB.

Example: data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ...

probe_imagerequired

string

Base64 (optionally data URI) probe / selfie image to compare against the reference. JPEG or PNG. Max 5 MB.

Example: data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ...

similarity_threshold

number (float) [0..100]

Optional override threshold (0-100). If omitted, system default is used.

Example: 80

Responses

200

Likeness comparison completed successfully

application/json

Field	Description
`message`	string Always `Ok` on success. Example: `Ok`
`api_reference`	string (uuid) Unique audit reference for this API call. Example: `fe4291ca-d831-4760-96df-c9cb03b3cd95`
`result`	object Likeness comparison result object.
`result.similarity`	number (float) Biometric engine similarity score (higher means more similar). Example: `95.5`
`result.threshold`	number (float) Threshold used to evaluate pass/fail (request value or system default). Example: `80`
`result.biometric_passed`	boolean True if `similarity >= threshold`. Example: `true`

Standard error responses: 400 401 402 403 429 5XX See common error responses

Previous Cancel an ID Pass Next Create a Liveness Check

Request body application/json

{
    "photo": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ...",
    "probe_image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ...",
    "similarity_threshold": 80
}

Response

200 Likeness comparison completed successfully

{
    "message": "Ok",
    "api_reference": "fe4291ca-d831-4760-96df-c9cb03b3cd95",
    "result": {
        "similarity": 95.5,
        "threshold": 80,
        "biometric_passed": true
    }
}

400 Bad or missing input parameter shared error response

{
    "message": "string"
}

401 Unauthorized - The request is not authorized. shared error response

{
    "message": "API Key Inactive"
}

402 Insufficient Credit - Insufficient credit to process this request shared error response

{
    "message": "Insufficient Credit"
}

403 No access - No permission to process this request shared error response

{
    "message": "No access"
}

429 Rate limited - The request rate limit has been reached shared error response

{
    "message": "Rate limited"
}

5XX Internal error - Internal system error shared error response

{
    "message": "Internal error"
}