Face Authentication

Face Authentication is a biometric service that enables face registration and authentication through facial comparison. This resource provides endpoints to register faces for individuals and query facial authentication attempts.

Face Registration

The registration endpoint allows associating a facial image with a person identifier (personId), creating a biometric reference that will be used later for authentication.

Faces registered by this endpoint will be used for facial comparison through the CafSdk or CafFaceLiveness SDKs. SDKs documented as deprecated will not necessarily use these facial registrations.

Register Face

post
Header parameters
AuthorizationstringRequired

Bearer token

Body
personIdstringRequired

Unique person identifier (CPF, external ID, etc). Must be between 5 and 254 characters and contain only letters, numbers and special characters "@", ".", "_", "-". If personId contains only numbers and the symbols ".", "-", "/", these special characters are removed, as the value is interpreted as a document mask.

Example: 12345678901
imageUrlstringRequired

URL of the facial image to be registered. Must be a valid and accessible .jpg or .png URL

Example: https://example.com/face-image.png
Responses
200

Face registered successfully

application/json
post
POST /v1/faces HTTP/1.1
Host: api.combateafraude.com
Authorization: text
Content-Type: application/json
Accept: */*
Content-Length: 74

{
  "personId": "12345678901",
  "imageUrl": "https://example.com/face-image.png"
}
{
  "requestId": "bb1ce1fd-5d0d-42af-bb0e-16f56b230a20",
  "message": "Face registration in progress",
  "personId": "12345678901"
}

Face Authentication Attempt Query

The query endpoint allows retrieving information about a specific facial authentication attempt, including URLs of the images used.

Query Attempt

get
Path parameters
attemptIdstringRequired

Unique identifier of the authentication attempt.

Example: 01K1XDD6W98M5QM9B8EAZZDV49
Header parameters
AuthorizationstringRequired

Bearer token

Responses
200

Attempt found successfully

application/json
get
GET /v1/faces/attempts/{attemptId} HTTP/1.1
Host: api.combateafraude.com
Authorization: text
Accept: */*

{
  "requestId": "bb1ce1fd-5d0d-42af-bb0e-16f56b230a20",
  "data": {
    "id": "01K1XDD6W98M5QM9B8EAZZDV49",
    "createdAt": "2025-07-15T10:30:00.000Z",
    "personId": "12345678901",
    "sourceIp": "192.168.1.100",
    "registeredFaceImageUrl": "https://s3.amazonaws.com/bucket/registered-face.jpg?signature=...",
    "capturedFaceImageUrl": "https://s3.amazonaws.com/bucket/captured-face.jpg?signature=...",
    "isMatch": true,
    "similarity": 0.95
  }
}

Important Notice about Integrations

To ensure the stability and security of our services, it is mandatory to implement integrations with Caf APIs exclusively via backend/server-side, as frontend calls (via browser or client-side) may be blocked by our systems when multiple IPs or browser user agents are detected. Furthermore, client-side integrations expose authentication keys to the risk of leakage and malicious use, which may lead to unauthorized resource consumption and additional charges. Authentication keys found to be used in incorrect implementations will be immediately deactivated.

We always recommend: (1) implementing on the backend, (2) using proper headers and authentication, and (3) never exposing credentials on the client-side. Please refer to our documentation for details or contact our technical support team.

Last updated