Liveness Detection

Check that a selfie comes from a live face, not a print or screen.

Postman collectionOpenAPI spec

Base URL

https://use.api.co.id

Send a selfie to POST /liveness/detect as multipart/form-data (field face1, optional reference_id) with the x-api-co-id header. The response contains transaction_id, result (whether liveness was detected), score, and the provider message.

Request fields

Field	Required	Rule
face1	yes	Selfie photo JPG/JPEG/PNG, max 2 MB
reference_id	no	Customer reference, max 64 characters

You don't send transaction_id. API.CO.ID generates it automatically, forwards it to the provider as trId, and returns it in the response.

curl -X POST "https://use.api.co.id/liveness/detect" \
  -H "x-api-co-id: YOUR_API_KEY" \
  -F "face1=@/absolute/path/to/selfie.jpg" \
  -F "reference_id=customer-reference-001"

Image guidance

• Use a clear photo of a human face.
• Avoid backlit or overly dark images.
• Use JPG, JPEG, or PNG.
• Keep the file at 2 MB or less.
• Avoid images containing multiple faces.

Results

Liveness detected:

{
  "is_success": true,
  "message": "Success",
  "data": {
    "transaction_id": "LIVE20260815093000A1B2C3",
    "result": true,
    "score": "100.0000",
    "message": "Liveness detection successfully"
  }
}

Liveness not detected:

{
  "is_success": true,
  "message": "Success",
  "data": {
    "transaction_id": "LIVE20260815093000D4E5F6",
    "result": false,
    "score": "0.0000",
    "message": "Liveness detection successfully"
  }
}

result: false still returns HTTP 200 because the provider processed the request successfully; liveness just wasn't detected. It is a valid business result.

Access & billing

API.CO.ID checks access in this order:

1. Valid API key.
2. Enough balance/subscription for liveness-detection.
3. Customer eKYC approved.
4. Request forwarded to the provider.
5. Points charged if the provider processes the request.

If a request is rejected before reaching the provider (wrong API key, insufficient balance, KYC not approved, missing file, file too large, or unsupported file type), no points are charged.

Common errors

HTTP	Condition
400Bad Request	face1 file missing, empty, unsupported type, or invalid image
401Unauthorized	API key missing or wrong
402Payment Required	Insufficient balance/subscription
403Forbidden	eKYC not approved, pending, rejected, or expired
413Payload Too Large	face1 file larger than 2 MB
422Unprocessable	Request rejected by provider validation
429Too Many Requests	Product quota exhausted when a subscription quota is active
502Bad Gateway	Provider auth/server/response error
503Unavailable	Provider quota unavailable
504Gateway Timeout	Provider timeout

Detect face liveness

POST/liveness/detect

Upload one selfie image to detect whether liveness is present. The image must be JPG, JPEG, or PNG and no larger than 2 MB. Do not log raw image or base64 data. result: false means the provider processed the request but liveness was not detected.

Body (multipart/form-data)

Name	Type	Description
face1Required	file	Selfie image in JPG, JPEG, or PNG format; maximum 2 MB
reference_idOptional	string	Optional customer reference for correlation Example: customer-reference-001

Response fields

Name	Type	Description
is_successRequired	boolean	Example: true
messageRequired	string	Example: Success
dataRequired	object
data.transaction_idRequired	string	Example: LIVE20260815093000A1B2C3
data.resultRequired	boolean	true if liveness is detected, false if not detected
data.scoreOptional	string	Example: 100.0000
data.messageRequired	string	Example: Liveness detection successfully

Request

curl -X POST "https://use.api.co.id/liveness/detect" \  -H "x-api-co-id: $API_CO_ID_KEY" \  -F "[email protected]" \  -F "reference_id=customer-reference-001"

Response

200OKLiveness detection processed successfully

{  "is_success": true,  "message": "Success",  "data": {    "transaction_id": "LIVE20260815093000A1B2C3",    "result": true,    "score": "100.0000",    "message": "Liveness detection successfully"  }}