Face Database Validation Object

The validation of a face against QI Tech's face database must be performed through the Face Database Validation Event Type endpoint. The API checks whether the submitted face is already known to the face database and decides the event based on that.

The flow has two steps:

1. Face capture. Generate a face registration in Face Recognition, via SDK or API. The returned registration_key identifies that registration.
2. Validation. Send the registration_key to this Event Type. The API searches for the face in the face database and returns the decision.

Event Type scope

Face Database Validation only queries the face database with the submitted registration. The face database and the CPF's reference registration remain unchanged after the validation.

Status Dynamics - analysis_status

The analysis_status field indicates the decision status of the fraud engine. The request response is always synchronous. When the event is sent to manual review, the response returns in_manual_analysis and the manual handling happens asynchronously: the final decision is sent via Webhook. Your integration must handle both scenarios.

Statuses that can be returned in the request response:

analysis_status	description
automatically_approved	QI Tech's algorithms recommend that this event be approved.
automatically_reproved	QI Tech's algorithms recommend that this event be rejected.
automatically_challenge	QI Tech's algorithms recommend that the user take an action to provide more information for the analysis.
in_manual_analysis	QI Tech's algorithms have flagged this event for manual review. The final decision is sent via Webhook.

Statuses sent via Webhook, after manual review:

analysis_status	description
manually_approved	After manual review, the analyst decided to approve the event.
manually_reproved	After manual review, the analyst decided to reject the event.

The full state machine is described in Status Dynamics.

Face Database Validation Object Definition

Request Body

{
  "id": "e034f932-9729-467f-9fcf-4b60cfbf06e1",
  "event_date": "2026-08-03T11:35:29.777Z",
  "document_number": "045.224.930-96",
  "face": {
    "registration_key": "d8cccd5d-015d-453d-b5ad-3d8c3cb718ea"
  }
}

Name	Type	Description
id	string	Event identifier in your system, 1 to 50 characters. It is essential that this number is unique for each request (required)
event_date	datetime	Date and time the event occurred in your application, in ISO 8601 with timezone. Accepts an explicit offset (-03:00) or UTC (Z). Dates without a timezone are not accepted. (required)
document_number	string	Holder's CPF with punctuation, in the format XXX.XXX.XXX-XX. (required)
face	face	Object containing the face registration to be searched for in the face database. (required)
face.registration_key	string	Identifier (UUID) of the face registration generated in Face Recognition, via SDK or API. This is the face that will be searched for in the face database. (required)

Submit a Face Database Validation

Request Body

  {
    "id": "e034f932-9729-467f-9fcf-4b60cfbf06e1",
    ...
  }

Response Body - automatically_approved

  {
    "id": "e034f932-9729-467f-9fcf-4b60cfbf06e1",
    "analysis_status": "automatically_approved",
    "reason": "Identidade validada automaticamente",
    "reason_description": "Identidade validada automaticamente"
  }

Response Body - automatically_reproved

  {
    "id": "8daca5f4-e109-4ccc-8522-12358702d04d",
    "analysis_status": "automatically_reproved",
    "reason": "Não há indícios suficientes para constatarmos que a foto enviada pertence ao titular do documento",
    "reason_description": "Não há indícios suficientes para constatarmos que a foto enviada pertence ao titular do documento"
  }

To perform the validation, simply send a Face Database Validation type object to the following endpoint:

POST https://api.caas.qitech.app/account_event/event_type/face_database_validation/event

The response contains the following fields:

Name	Type	Description
id	string	The same id sent in the request, echoed back for correlation.
analysis_status	enumerator	Analysis decision for the event. This is the field your integration must branch on.
reason	string	Reason that determined the decision. Values are defined in each client's configuration, so they vary by integration and by Event Type.
reason_description	string	Human-readable description of the reason, for display in operational screens and audit trails.

The same request can result in any of the statuses, depending on the integration's configuration and what the database returns:

analysis_status	meaning	expected action in the journey
automatically_approved	Identity automatically validated against the face database.	Continue the journey. No further action needed.
automatically_reproved	There is not enough evidence that the submitted photo belongs to the document holder.	Block the step and apply the agreed rejection policy. Resubmission only with a new capture.

Branch on analysis_status

The values of reason are defined in each client's configuration. Do not build logic on the text of reason: use it for display and auditing, and branch on analysis_status.