Document Validation

Document Validation is the service that analyzes the identity document (and, optionally, a selfie) and determines whether they are authentic and consistent with each other. The service is integrated as part of the Facephi API ecosystem.

From the document (and, if provided, the selfie), the service runs a set of anti-fraud validations and returns a single diagnosis:

• APPROVED: the document (and, where applicable, its match with the selfie) passes the validations.

• DECLINED: an inconsistency, manipulation, or quality/format non-compliance is detected that prevents validation of the document.

• DOUBTFUL: the analysis is inconclusive. The document is neither confirmed authentic nor rejected, and the decision is left to the consumer. It appears only in automatic mode.

Asynchronous nature

Document Validation is an asynchronous service: the call that starts the validation does not block waiting for the result. It responds immediately with a transaction identifier (transactionId) and the consumer obtains the result through status queries (polling).

Service modes

Document Validation is provided in two modes, which are set when the service is enabled and are not chosen per request:

• Automatic: the diagnosis is issued entirely by the Facephi anti-fraud engine. When the analysis does not reach a conclusion, the transaction ends with diagnostic = DOUBTFUL and its rejectionReason corresponding.

• Hybrid: when the initial analysis is inconclusive, the case goes through an additional escalated verification before resolution. The final diagnosis is always APPROVED or DECLINED: this mode does not return DOUBTFUL. Reason codes 600 to 603 only appear here.

If you do not know which one your integration has, check with support.

Integration Flow

The startup (Token, operation and asset upload) is common to all services that work by reference and is developed in Common Flow. From there:

1. Complete the previous steps of the common Flow, including the asset upload of the document and, optionally, the selfie.

2. Start the validation by sending the fileKeys obtained as-is, with the operationId in the header operation-id. The service responds immediately with a transactionId.

3. Check the status of the transaction through polling until a terminal status is obtained.

The recommended polling cadence is in Best practices, and the detail of the terminal response in Result Response.

Document Validation works exclusively by reference: it does not accept the asset contents inline. The common reference model for the entire API is in Storage.

Route changes. The document validation is now published under /document/validate. The previous routes continue to be served so as not to break existing integrations, but they are obsolete and will no longer be documented:

The contract does not change: same headers, same request body, and same responses. Only the route changes.

Previous route	Current route
POST /daf/validate	POST /document/validate
GET /daf/{transactionId}	GET /document/validate/{transactionId}
POST /daf/fraud-report	POST /document/validate/fraud-report