Face Match for Liveness

The {livenessRequestId} in this endpoint is the id returned by the previous call to Liveness. The image you send here is compared with the face captured in that session, and the response only says whether the two belong to the same person.

It is the second half of the liveness flow: first you prove there is a live person in the capture, then you prove that person is the same one as in another image — the photo on a document, for example.

🚧 The liveness session must have passed

The comparison only runs when the liveness session referenced resulted in isAlive: true. If the session does not exist or was rejected, the response comes back with matched: false and code 200, without any comparison taking place.

Request

POST /face-match-for-liveness/{livenessRequestId}/v2

Parameters

Parameter	Description	Required
livenessRequestId	The id returned by the call to Liveness that captured the reference face.	Yes

Headers

Authorization: ApiKey <your-api-key>

This endpoint also accepts the JWT token, in the format Authorization: Bearer <accessToken>. See JWT Token.

Accepted files

Item	Value
Formats	image/png, image/jpeg
Files per call	1 file
Maximum size (multipart)	15 MB

The form field name is up to you. If more than one file is sent, the request is rejected with 422.

Besides multipart/form-data, the file can be sent as JSON, in the base64 field, as described in Sending files.

Example request

curl -i -X POST 'https://api-homolog.nxcd.app/face-match-for-liveness/13cfec7c-b238-4820-a4d1-5173e4c1418e/v2' \
  --header 'Authorization: ApiKey YOUR_API_KEY' \
  --form 'documento=@./documento-frente.jpg'

Response

TIP

The response of this endpoint does not use the id / version / data / metadata envelope of the other analysis endpoints. The body has a single field. The request identifier is still available in the Nextid-ReqId header.

Field	Description	Type
matched	true when the face in the image sent is the same as the one in the liveness session referenced.	Boolean

JSON examples

1. The faces match

Status Code: 200

{
  "matched": true
}

2. The faces do not match, or the comparison could not be made

Status Code: 200

{
  "matched": false
}

🚧 matched: false has more than one meaning

The same response covers "the faces belong to different people" and "there was nothing to compare". The cases that return matched: false without running the comparison are:

• no file was sent in the request;
• the livenessRequestId does not correspond to any liveness session;
• the liveness session was rejected (isAlive: false);
• there is no record of the liveness session's file, neither in the request cache nor in billing.

To tell these cases apart, check the liveness result before calling this endpoint and keep the session id.

Response headers

Header	When it appears
Nextid-ReqId	On every response. Carries the identifier of this request.

Errors

Code	When it happens
401 Unauthorized	API key or JWT token missing, invalid, or without permission for liveness.
404 Not Found	The version given in the URL does not exist, or the liveness session's file is on record, but was not found in storage.
406 Not Acceptable	The body was sent as JSON, but without the base64 field.
413 Payload Too Large	The file sent as multipart/form-data is larger than 15 MB.
415 Unsupported Media Type	The Content-Type header is missing or is not supported.
422 Unprocessable Entity	The file format is not accepted, or more than one file was sent in the same call.
500 Internal Server Error	Unexpected failure during processing.

TIP

A livenessRequestId that does not exist does not produce a 404: the response is 200 with matched: false. These are distinct situations: when there is nothing to compare, the response is 200 with matched: false; the 404 only happens when the session exists and has a file on record, but that file is no longer in storage.

The error response format is described in HTTP response codes.

Versions

This endpoint accepts version v2 at the end of the URL. Omitting the version, the call is served by v2.

Version	Status	What changes
v2	Recommended	The version used when nothing is given in the URL.

The only field returned is matched. Omitting the version makes no difference: /face-match-for-liveness/{livenessRequestId} and /face-match-for-liveness/{livenessRequestId}/v2 are the same call. Prefer stating v2 in the path.

An unrecognized value in the version position returns 404.

🚧 Do not confuse this with Face Match

/face-match, documented separately, compares faces between the files you send in the same request and returns the full envelope. This endpoint here compares against the face from a previous liveness session and returns only matched.