Selfie Biometric Matching

Biometric Match of Images/Templates

This guide helps enterprise developers quickly integrate REL-ID secure biometric services into their backend systems. Compare face/selfie images or templates for a specific REL-ID user.

🔐 Authentication

OAuth2 Bearer Token is required in the Authorization header.

Example:

Authorization: Bearer <access_token>

🧠 Use Case

Used to match:

Image vs Image
Image vs Template
Template vs Image
Template vs Template

🔗 Endpoint

POST /IdvWebServer/api/compare

🔤 Request Headers

Header	Value	Required
Authorization	Bearer `<access_token>`	Yes
Content-Type	application/json	Yes

📦 Request Body

{
  "baseImage": "<base64 image>",
  "baseTemplate": "<base64 template>",
  "compareToImage": "<base64 image>",
  "compareToTemplate": "<base64 template>",
  "userId": "REL-ID userId"
}

🔑 Mandatory Fields

userId is required.
One of baseImage or baseTemplate must be provided.
One of compareToImage or compareToTemplate must be provided.

✅ Success Response

{
  "userId": "string",
  "compareResult": "MATCHED | FAILED",
  "faceMatcherScore": "float",
  "resultCriteria": "string"
}

HTTP Status: 200 OK

🧪 Example CURL

curl --location 'https://REL-ID-SERVER-IP:8004/IdvWebServer/api/compare' \
--header 'Authorization: Bearer <access_token>' \
--header 'Content-Type: application/json' \
--data '{
  "baseImage": "<base64-encoded-image>",
  "compareToTemplate": "<base64-template>",
  "userId": "user123"
}'

🔐 OAuth2 Authentication Failure Format

{
  "error": "invalid_token",
  "error_description": "Invalid access token: <token>"
}

🔁 Response Headers (on Authentication Failure)

Header	Value
`Pragma`	`no-cache`
`Cache-Control`	`no-cache, no-store, max-age=0, must-revalidate`
`WWW-Authenticate`	`Bearer error=<error>, error_description="<description>"`

These headers accompany the error response and follow the OAuth2 specification. The WWW-Authenticate header includes the same error details as the JSON response body.

❌ Failure Responses

🔒 401 Unauthorized (Token Invalid or IP Not Whitelisted)

{
  "timestamp": 1649916471549,
  "status": 401,
  "error": "Unauthorized",
  "message": "Unauthorized",
  "path": "/IdvWebServer/api/compare"
}

❗ 400 Bad Request

Occurs when one or more of the following conditions are true:

The user is not present in the REL-ID system.
Invalid or malicious input data is provided.
Both baseImage and baseTemplate are empty.
Both compareToImage and compareToTemplate are empty.
Both baseImage and baseTemplate are populated (only one should be provided).

Both compareToImage and compareToTemplate are populated (only one should be provided).

{
  "timeStamp": "01-04-2022 12:21:44",
  "status": "BAD_REQUEST",
  "error": "Failed.",
  "message": "Invalid User",
  "path": "/api/compare"
}

🟠 422 Unprocessable Entity

{
  "timeStamp": "03-04-2022 04:53:41",
  "status": "UNPROCESSABLE_ENTITY",
  "error": "Failed.",
  "message": "Mandatory fields missing (userId).",
  "path": "/api/compare"
}

🔥 500 Internal Server Error

{
  "timeStamp": "2022-04-03T04:53:41",
  "status": 500,
  "error": "Internal Server Error",
  "message": "Unexpected error occurred.",
  "path": "/api/compare"
}

📋 Notes

IP must be whitelisted in the REL-ID system.
Server runs on port 8004.

Updated 3 months ago