Liveness

Liveness answers a single question: is the image sent that of a live person, present at the moment of capture? It exists to block presentation attacks — a photo of a photo, a screenshot, a video played back on a monitor, a mask.

The image usually comes from one of our capture SDKs, which run in the end user's app or browser and talk to the API using a short-lived JWT token.

🚧 Liveness does not compare against a document

This endpoint does not compare the face sent with the photo on a document, and it does not identify the person. It only says whether there is a live person in the capture. To compare the face captured here with another image, use Face Match for Liveness, chaining the id from this response.

Request

POST /liveness/v2

Parameters

Parameter	Description	Required
version	API version in the URL path. Use v2. See Versions.	Yes

Headers

Authorization: ApiKey <your-api-key>

This endpoint also accepts the JWT token, in the format Authorization: Bearer <accessToken> — that is how the SDKs authenticate. 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 — use whatever makes sense in your integration. 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/liveness/v2' \
  --header 'Authorization: ApiKey YOUR_API_KEY' \
  --form 'selfie=@./selfie.jpg'

Response

The envelope is the API standard:

Field	Description	Type
id	Unique identifier of the request. This is the one used in Face Match for Liveness.	String
version	API version that served the call	String
data	Object with the result of the analysis	Object
data.isAlive	true when the image is of a live person present at the capture	Boolean
metadata	Object with the metadata of the request	Object
metadata.filesInfo	List with the information of the file sent	Object[]
metadata.filesInfo[].fieldname	Name of the field used to send the file	String
metadata.filesInfo[].name	Name of the file sent	String
metadata.filesInfo[].size	Size of the file, in bytes	Number
metadata.filesInfo[].mimetype	Type of the file sent	String
metadata.filesInfo[].encoding	Encoding of the file as sent	String
metadata.filesInfo[].sha256	SHA-256 hash of the file sent	String
metadata.timeSpent	Processing time of the request, in milliseconds	Number

🚧 Attention!

isAlive: false does not necessarily mean an attempted fraud. A poor capture — low light, bad focus, face partly out of frame — also leads to false. What to do in that case is your decision.

JSON examples

1. Successful liveness check

Status Code: 200

{
  "id": "13cfec7c-b238-4820-a4d1-5173e4c1418e",
  "version": "v2",
  "data": {
    "isAlive": true
  },
  "metadata": {
    "filesInfo": [
      {
        "fieldname": "selfie",
        "name": "selfie.jpg",
        "size": 184320,
        "mimetype": "image/jpeg",
        "encoding": "7bit",
        "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
      }
    ],
    "timeSpent": 850
  }
}

2. Liveness check rejected

Status Code: 200

{
  "id": "6a1d1e8c-4a7d-4a5e-9f2c-1b0f2a9c7e11",
  "version": "v2",
  "data": {
    "isAlive": false
  },
  "metadata": {
    "filesInfo": [
      {
        "fieldname": "selfie",
        "name": "selfie.jpg",
        "size": 152064,
        "mimetype": "image/jpeg",
        "encoding": "7bit",
        "sha256": "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae"
      }
    ],
    "timeSpent": 790
  }
}

Response headers

Header	When it appears
Nextid-ReqId	On every response. Carries the request identifier, the same one as the id field in the body.

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.
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.

The error response format is described in HTTP response codes.

Versions

Version	Status	What changes
v2	Recommended	The API standard envelope, with data.isAlive.

v2 is the supported version of this endpoint. Always state the version in the path of the call.

Next step

Keep the id from the response: it is what identifies the liveness session in Face Match for Liveness.