Face Liveness (Passive)

1 endpoint · Core API

This API employs advanced facial recognition technology to assess the liveness of a face captured in an image. By analyzing various facial features and movements, it generates a liveness score to ascertain whether the face is genuine and live or not. This process ensures secure identity verification by preventing fraudulent attempts to deceive facial recognition systems using static images or impersonation. With its sophisticated algorithms, the API offers a reliable method for verifying the authenticity of individuals, enhancing security measures in various applications such as online identity verification, access control, and biometric authentication.

What you can do

This API detects the liveness of a face captured in an image, providing a liveness score to determine whether the face is live or not, ensuring secure identity verification.

POST

/api/v1/FaceLiveness

Detect whether a face in a photo belongs to a live person (passive liveness)

docs.signcare.io/core/api/biometric/face-liveness-passive/#post-api-v1-faceliveness

Passive liveness: a single still image is enough. The end user does not have to blink, turn their head, or follow any on-screen prompt, and no video is uploaded. Use this to reject spoof attempts — a printed photo, a face shown on a phone or monitor, or a mask — before you trust a selfie.

Typical placement: run liveness first, then pass the same image to Face Match against the ID photo. Face Match on its own can be satisfied by holding up a photo of the genuine customer.

Request rules:

fileBase64 is required and must be raw Base64 only. Strip any data:image/jpeg;base64, prefix and remove all line breaks and whitespace, or the request is rejected as a validation error before it reaches the provider.
requestId is optional. Omit it and one is generated for you. Whatever is used comes back in request_id, so send your own value if you want to correlate with your logs.
Frame a single face. Faces that are very small, heavily cropped, or badly lit lower the score.

Reading the response:

isLive — the verdict. true = assessed as a live person, false = assessed as a spoof.
livenessScore — the provider's confidence behind that verdict. Returned as-is: SignCare applies no minimum threshold of its own, so if your risk policy needs a stricter cut-off than the provider's, compare this value yourself and do not rely on isLive alone.
multipleFacesDetected — true means more than one face was in the frame. Treat the result as inconclusive and ask for a re-capture, because isLive then describes only one of the faces.
reviewNeeded — the provider's own "send this to a human" flag, passed through verbatim. Route these to manual review rather than auto-approving.

Status codes: 200 success, 400 validation failure or an unreadable provider reply, 401 API key or app id rejected, 500 unexpected error. Note that when the provider replies with its own error, its code and message are surfaced in the body's statusCode and message — so always branch on the body success flag, not on the HTTP status alone.

Headers

X-API-KEY
stringrequired
Your secret API key for the environment you are calling (Stage and Live use different keys).
X-API-APP-ID
stringrequired
The App ID issued together with the key.
Content-Type
stringrequired
application/json

Body parameters

application/json

fileBase64
stringrequired
Required. Raw Base64-encoded JPEG or PNG image containing the face to check. Must NOT include a data-URI prefix (e.g. "data:image/jpeg;base64,") and must contain no line breaks or whitespace, or the request is rejected with 400. Frame a single, well-lit face.
minLength 1pattern ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2…default iVBORw0KGgo=
requestId
stringoptional
Optional. Your own identifier for correlating this check with your logs (JSON name is `requestId`, not `request_id`). If omitted, one is generated. The value used is echoed back in "request_id".
nullable

Sample request body

{ "fileBase64": "iVBORw0KGgo=" }

Responses

200OK

success
booleanoptional
No description.
statusCode
integer (int32)optional
No description.
default 200
message
stringoptional
No description.
nullabledefault XXXXX
data
objectoptional
Response model containing passive face liveness detection results.
4 fields
- isLive
  booleanoptional
  The liveness verdict. True = assessed as a live person present at capture; false = assessed as a spoof (printed photo, screen replay, or mask).
- livenessScore
  number (double)optional
  The provider's confidence behind the verdict, returned as-is. SignCare applies no minimum threshold, so apply your own cut-off here if your risk policy needs one stricter than the provider's.
- reviewNeeded
  stringoptional
  The provider's own manual-review flag, passed through verbatim. When set, route the case to human review rather than auto-approving it.
  nullable
- multipleFacesDetected
  booleanoptional
  True when more than one face was present in the frame. Treat the result as inconclusive and request a re-capture, since isLive then describes only one face.
messages
array<string>optional
No description.
nullable
request_id
stringoptional
No description.
nullable
isBillable
booleanoptional
Whether this request was charged: true if it was, false if not. Errors always show false. Flows that finish later (ITR Fetch, SHCIL eStamp, DigiLocker, eSign) show false here, because the charge is made when the result is ready. eSign charges each signer when they complete signing. DigiLocker deducts the credit when the link is created and refunds it automatically if the link expires before the user completes it.

Example

{ "success": false, "statusCode": 200, "message": "XXXXX", "data": { "isLive": false, "livenessScore": 0, "reviewNeeded": "string", "multipleFacesDetected": false }, "messages": [ "string" ], "request_id": "string", "isBillable": false }

400Bad Request

data
objectoptional
No description.
messages
array<string>optional
No description.
nullable
request_id
stringoptional
No description.
nullable
success
booleanoptional
No description.
default false
message
stringoptional
No description.
nullabledefault XXXXX
isBillable
booleanoptional
No description.
statusCode
integer (int32)optional
No description.
default 400

Example

{ "data": {}, "messages": [ "string" ], "request_id": "string", "success": false, "message": "XXXXX", "isBillable": false, "statusCode": 400 }

401Unauthorized

data
objectoptional
No description.
messages
array<string>optional
No description.
nullable
request_id
stringoptional
No description.
nullable
success
booleanoptional
No description.
default false
message
stringoptional
No description.
nullabledefault XXXXX
isBillable
booleanoptional
No description.
statusCode
integer (int32)optional
No description.
default 401

Example

{ "data": {}, "messages": [ "string" ], "request_id": "string", "success": false, "message": "XXXXX", "isBillable": false, "statusCode": 401 }

500Internal Server Error

data
objectoptional
No description.
messages
array<string>optional
No description.
nullable
request_id
stringoptional
No description.
nullable
success
booleanoptional
No description.
default false
message
stringoptional
No description.
nullabledefault XXXXX
isBillable
booleanoptional
No description.
statusCode
integer (int32)optional
No description.
default 500

Example

{ "data": {}, "messages": [ "string" ], "request_id": "string", "success": false, "message": "XXXXX", "isBillable": false, "statusCode": 500 }

Code samplescurl · Node.js · Python

Stage: uat-ext.signcare.io

curl -X POST 'https://uat-ext.signcare.io/api/v1/FaceLiveness' \ -H 'X-API-KEY: YOUR_API_KEY' \ -H 'X-API-APP-ID: YOUR_APP_ID' \ -H 'Content-Type: application/json' \ -d '{ "fileBase64": "iVBORw0KGgo=" }'

All KYC & Identity Verification pages