Face Authentication

This API is deprecated.

The Core API is no longer recommended for new integrations. It will remain functional exclusively for existing clients. Migration to the Connect API is strongly recommended.

For more details, see the Deprecation Policy.

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

application/json

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

requestIdstringRequired

Unique identifier of request

Example: bb1ce1fd-5d0d-42af-bb0e-16f56b230a20

messagestringRequired

Status message

Example: Face registration in progress

personIdstringRequired

Person identifier

Example: 12345678901

400

Invalid request data

application/json

401

Invalid authentication token

application/json

422

Unsupported image format

application/json

500

Internal server error

application/json

post/faces

HTTPcURLJavaScriptPython

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

requestIdstringRequired

Unique identifier of request

Example: bb1ce1fd-5d0d-42af-bb0e-16f56b230a20

400

attemptId not provided

application/json

401

Invalid authentication token

application/json

404

Attempt not found

application/json

500

Internal server error

application/json

get/faces/attempts/{attemptId}

HTTPcURLJavaScriptPython

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=...",
    "isAlive": true,
    "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.