KYC · API reference

Face

Face Analyze

POST/v1/face/analyzeface.analyze

The all-in-one detection call. For every face it returns the box, the tilt, 5 landmarks, an aligned crop, the attributes you pick and the quality checks you define.

**Returns**

- faces[].roi: the face box, [x, y, width, height] in pixels - faces[].landmarks: 5 points: eyes, nose, mouth corners - faces[].crop: the aligned crop (when you asked for one) - faces[].attributes[]: each picked attribute: name, value, confidence - faces[].quality: your checks, each with its value, range and status (1 = pass)

**Limits**

- Up to 13 attributes. Each quality check needs a [min, max] range.

Price: 0.1 credits per successful call.

Body parameters

imagestringrequired

Face image. The image as base64 (JPEG or PNG). The SDKs also take a file path or the file bytes.

onlyCentralFaceboolean

Only the central face. Off returns every face in the image.

cropobject

Show 1 fields

typeany: Aligned crop. An aligned crop of each face at this shape.; 01234

attributesarray of strings

Attributes to return. Any of the 13 attributes.

qualityChecksarray of anys

Your quality checks. A check passes when its value is within your range.

tagstring

Tag. Any text you want echoed back in the response.

Returns

The check ran.

Show the FaceAnalyzeResponse fields

okbooleanrequired: true: the result is in data.
request_idstring
latency_msnumber: How long the check took, in milliseconds.
dataobjectrequired: The full result of Face Analyze: everything the check found. See the fields listed in the operation.
warningsarray of strings
errorany: Empty on success.

Errors

400A field is missing or not valid.
401No API key, or the key is not valid, expired or revoked.
402Not enough credits for this call (insufficient_credits), or the key reached its spend cap. Nothing was charged.
403The key may not call this API (permission, environment or IP allow-list). Nothing was charged.
413The image or the request is too large.
429Too many requests for this key: wait Retry-After seconds. Nothing was charged.
5XXThe check could not run. Nothing was charged.

Request

curl -X POST https://verisec.dev/v1/face/analyze \
  -H "Authorization: Bearer $VERISEC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==",
    "onlyCentralFace": false,
    "crop": {
      "type": 1
    },
    "attributes": [
      "Age",
      "EyeRight",
      "EyeLeft",
      "Mouth",
      "Emotion",
      "Smile",
      "Glasses",
      "HeadCovering",
      "ForeheadCovering",
      "MedicalMask",
      "Occlusion",
      "StrongMakeup",
      "Headphones"
    ],
    "qualityChecks": [
      {
        "name": "Yaw",
        "range": [
          -5,
          5
        ]
      },
      {
        "name": "BlurLevel",
        "range": [
          0,
          0.15
        ]
      }
    ]
  }'

Response · 200

{
  "ok": true,
  "request_id": "req_802e9e4d308844948142",
  "latency_ms": 1659,
  "data": {
    "code": 0,
    "msg": "OK",
    "detectionTime": 0.472509805,
    "faces": [
      {
        "roi": [
          102,
          118,
          228,
          321
        ],
        "rotationAngle": 0.1800577672707395,
        "landmarks": [
          [
            157,
            256
          ],
          [
            272,
            254
          ],
          [
            214,
            310
          ],
          [
            174,
            375
          ],
          [
            256,
            374
          ]
        ],
        "crop": "<base64 image>",
        "attributes": [
          {
            "name": "Age",
            "value": [
              29,
              31
            ]
          },
          {
            "confidence": 1,
            "name": "EyeRight",
            "value": "open"
          },
          {
            "confidence": 1,
            "name": "EyeLeft",
            "value": "open"
          },
          {
            "confidence": 1,
            "name": "Mouth",
            "value": "closed"
          }
        ],
        "quality": {
          "checks": [
            {
              "groupId": 2,
              "name": "Yaw",
              "range": [
                -5,
                5
              ],
              "status": 1,
              "value": -0.9091355800628662
            },
            {
              "groupId": 3,
              "name": "BlurLevel",
              "range": [
                0,
                0.15000000596046448
              ],
              "status": 1,
              "value": 0.06612038612365723
            }
          ],
          "nonCompliant": [],
          "score": -1
        }
      }
    ],
    "elapsedTime": 1.568222918,
    "metadata": {
      "serverTime": "2026-10-05T05:34:49.015Z",
      "ctx": {
        "userIp": "203.0.113.7"
      }
    },
    "tag": "req-1"
  },
  "warnings": [],
  "error": null
}

Face Detect

POST/v1/face/detectface.detect

Just the faces: each box, its tilt, 5 landmarks, and the count. No attributes, no quality.

**Returns**

- faceCount: how many faces were found - faces[].roi: the face box [x, y, w, h] - faces[].rotationAngle: the in-plane tilt, in degrees - faces[].landmarks: 5 points

Price: 0.02 credits per successful call.

Body parameters

imagestringrequired: Image. The image as base64 (JPEG or PNG). The SDKs also take a file path or the file bytes.
onlyCentralFaceboolean: Only the central face. Off returns every face.
tagstring: Tag. Any text you want echoed back in the response.

Returns

The check ran.

Show the FaceDetectResponse fields

okbooleanrequired

true: the result is in data.

request_idstring

latency_msnumber

How long the check took, in milliseconds.

dataobjectrequired

The answer of Face Detect.

Show 6 fields

codenumber

msgstring

faceCountnumber

facesarray of objects

Show 3 fields

roiarray of numbers
rotationAnglenumber
landmarksarray of array of numberss

elapsedTimenumber

metadataobject

Show 2 fields

serverTimestring

ctxobject

Show 1 fields

userIpstring

warningsarray of strings

errorany

Empty on success.

Errors

400A field is missing or not valid.
401No API key, or the key is not valid, expired or revoked.
402Not enough credits for this call (insufficient_credits), or the key reached its spend cap. Nothing was charged.
403The key may not call this API (permission, environment or IP allow-list). Nothing was charged.
413The image or the request is too large.
429Too many requests for this key: wait Retry-After seconds. Nothing was charged.
5XXThe check could not run. Nothing was charged.

Request

curl -X POST https://verisec.dev/v1/face/detect \
  -H "Authorization: Bearer $VERISEC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==",
    "onlyCentralFace": false
  }'

Response · 200

{
  "ok": true,
  "request_id": "req_d7227dc4bcc649eeab32",
  "latency_ms": 578,
  "data": {
    "code": 0,
    "msg": "OK",
    "faceCount": 1,
    "faces": [
      {
        "roi": [
          102,
          118,
          228,
          321
        ],
        "rotationAngle": 0.1800577672707395,
        "landmarks": [
          [
            157,
            256
          ],
          [
            272,
            254
          ],
          [
            214,
            310
          ],
          [
            174,
            375
          ],
          [
            256,
            374
          ]
        ]
      }
    ],
    "elapsedTime": 0.512770632,
    "metadata": {
      "serverTime": "2026-10-05T05:34:49.654Z",
      "ctx": {
        "userIp": "203.0.113.7"
      }
    }
  },
  "warnings": [],
  "error": null
}

Face Count

POST/v1/face/countface.count

Confirms an image holds exactly the number of faces you expect, for a capture gate.

**Returns**

- faceCount: faces found - ok: true when the count equals your expected value - rule: the rule applied, e.g. expected==1 - faces[].roi: each face box

**Limits**

- Expected count is 0 to 100.

Price: 0.02 credits per successful call.

Body parameters

imagestringrequired: Image. The image as base64 (JPEG or PNG). The SDKs also take a file path or the file bytes.
expectedinteger: Expected faces. ok is true only when the count equals this.
tagstring: Tag. Any text you want echoed back in the response.

Returns

The check ran.

Show the FaceCountResponse fields

okbooleanrequired

true: the result is in data.

request_idstring

latency_msnumber

How long the check took, in milliseconds.

dataobjectrequired

The answer of Face Count.

Show 8 fields

codenumber

msgstring

faceCountnumber

okboolean

rulestring

facesarray of objects

Show 1 fields

roiarray of numbers

elapsedTimenumber

metadataobject

Show 2 fields

serverTimestring

ctxobject

Show 1 fields

userIpstring

warningsarray of strings

errorany

Empty on success.

Errors

400A field is missing or not valid.
401No API key, or the key is not valid, expired or revoked.
402Not enough credits for this call (insufficient_credits), or the key reached its spend cap. Nothing was charged.
403The key may not call this API (permission, environment or IP allow-list). Nothing was charged.
413The image or the request is too large.
429Too many requests for this key: wait Retry-After seconds. Nothing was charged.
5XXThe check could not run. Nothing was charged.

Request

curl -X POST https://verisec.dev/v1/face/count \
  -H "Authorization: Bearer $VERISEC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==",
    "expected": 1
  }'

Response · 200

{
  "ok": true,
  "request_id": "req_7c565fdfe4564f889889",
  "latency_ms": 476,
  "data": {
    "code": 0,
    "msg": "OK",
    "faceCount": 1,
    "ok": true,
    "rule": "expected==1",
    "faces": [
      {
        "roi": [
          102,
          118,
          228,
          321
        ]
      }
    ],
    "elapsedTime": 0.45388238,
    "metadata": {
      "serverTime": "2026-10-05T05:34:50.151Z",
      "ctx": {
        "userIp": "203.0.113.7"
      }
    }
  },
  "warnings": [],
  "error": null
}

Face Attributes

POST/v1/face/attributesface.attributes

The attributes you choose, per face. Age is a range; eyes and mouth are open/closed; emotion is a label; the rest are yes/no, each with a confidence.

**Returns**

- faces[].roi: the face box - faces[].attributes[]: each picked attribute: name, value, confidence

**Limits**

- Pick any of the 13 attributes; at least one is required. - Age returns a [min, max] band, not a single number.

Price: 0.1 credits per successful call.

Body parameters

imagestringrequired: Face image. The image as base64 (JPEG or PNG). The SDKs also take a file path or the file bytes.
attributesarray of stringsrequired: Attributes to return.
tagstring: Tag. Any text you want echoed back in the response.

Returns

The check ran.

Show the FaceAttributesResponse fields

okbooleanrequired

true: the result is in data.

request_idstring

latency_msnumber

How long the check took, in milliseconds.

dataobjectrequired

The answer of Face Attributes.

Show 5 fields

codenumber

msgstring

facesarray of objects

Show 2 fields

roiarray of numbers

attributesarray of objects

Show 3 fields

namestring
valueany
confidencenumber

elapsedTimenumber

metadataobject

Show 2 fields

serverTimestring

ctxobject

Show 1 fields

userIpstring

warningsarray of strings

errorany

Empty on success.

Errors

400A field is missing or not valid.
401No API key, or the key is not valid, expired or revoked.
402Not enough credits for this call (insufficient_credits), or the key reached its spend cap. Nothing was charged.
403The key may not call this API (permission, environment or IP allow-list). Nothing was charged.
413The image or the request is too large.
429Too many requests for this key: wait Retry-After seconds. Nothing was charged.
5XXThe check could not run. Nothing was charged.

Request

curl -X POST https://verisec.dev/v1/face/attributes \
  -H "Authorization: Bearer $VERISEC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==",
    "attributes": [
      "Age",
      "EyeRight",
      "EyeLeft",
      "Mouth",
      "Emotion",
      "Smile",
      "Glasses",
      "HeadCovering",
      "ForeheadCovering",
      "MedicalMask",
      "Occlusion",
      "StrongMakeup",
      "Headphones"
    ]
  }'

Response · 200

{
  "ok": true,
  "request_id": "req_c976d867c0744bb3b4fa",
  "latency_ms": 1099,
  "data": {
    "code": 0,
    "msg": "OK",
    "faces": [
      {
        "roi": [
          102,
          118,
          228,
          321
        ],
        "attributes": [
          {
            "name": "Age",
            "value": [
              29,
              31
            ]
          },
          {
            "confidence": 1,
            "name": "EyeRight",
            "value": "open"
          },
          {
            "confidence": 1,
            "name": "EyeLeft",
            "value": "open"
          },
          {
            "confidence": 1,
            "name": "Mouth",
            "value": "closed"
          }
        ]
      }
    ],
    "elapsedTime": 1.041403888,
    "metadata": {
      "serverTime": "2026-10-05T05:34:51.240Z",
      "ctx": {
        "userIp": "203.0.113.7"
      }
    }
  },
  "warnings": [],
  "error": null
}

Mask & Glasses (PPE)

POST/v1/face/ppeface.ppe

Mask, glasses, head and forehead covering, headphones and occlusion, flattened so each item is one yes/no value per face.

**Returns**

- faces[].roi: the face box - faces[].<item>: yes or no for each item you asked for (e.g. MedicalMask)

**Limits**

- Pick any of the six items; at least one is required.

Price: 0.02 credits per successful call.

Body parameters

imagestringrequired: Face image. The image as base64 (JPEG or PNG). The SDKs also take a file path or the file bytes.
itemsarray of stringsrequired: Items to check.
tagstring: Tag. Any text you want echoed back in the response.

Returns

The check ran.

Show the FacePpeResponse fields

okbooleanrequired

true: the result is in data.

request_idstring

latency_msnumber

How long the check took, in milliseconds.

dataobjectrequired

The answer of Mask & Glasses (PPE).

Show 5 fields

codenumber

msgstring

facesarray of objects

Show 5 fields

roiarray of numbers
MedicalMaskstring
Glassesstring
HeadCoveringstring
Headphonesstring

elapsedTimenumber

metadataobject

Show 2 fields

serverTimestring

ctxobject

Show 1 fields

userIpstring

warningsarray of strings

errorany

Empty on success.

Errors

400A field is missing or not valid.
401No API key, or the key is not valid, expired or revoked.
402Not enough credits for this call (insufficient_credits), or the key reached its spend cap. Nothing was charged.
403The key may not call this API (permission, environment or IP allow-list). Nothing was charged.
413The image or the request is too large.
429Too many requests for this key: wait Retry-After seconds. Nothing was charged.
5XXThe check could not run. Nothing was charged.

Request

curl -X POST https://verisec.dev/v1/face/ppe \
  -H "Authorization: Bearer $VERISEC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==",
    "items": [
      "MedicalMask",
      "Glasses",
      "HeadCovering",
      "Headphones"
    ]
  }'

Response · 200

{
  "ok": true,
  "request_id": "req_0b29ee0fe55141448905",
  "latency_ms": 1260,
  "data": {
    "code": 0,
    "msg": "OK",
    "faces": [
      {
        "roi": [
          102,
          118,
          228,
          321
        ],
        "MedicalMask": "no",
        "Glasses": "no",
        "HeadCovering": "no",
        "Headphones": "no"
      }
    ],
    "elapsedTime": 1.206900618,
    "metadata": {
      "serverTime": "2026-10-05T05:34:52.515Z",
      "ctx": {
        "userIp": "203.0.113.7"
      }
    }
  },
  "warnings": [],
  "error": null
}

Emotion

POST/v1/face/emotionface.emotion

The dominant expression of each face. Send one image for per-face results, or a list of frames for a per-frame breakdown plus the overall dominant emotion.

**Returns**

- faces[].emotion / faces[].confidence: per face, for a single image - perFrame[]: per frame: emotion and confidence (for a batch) - dominant: the most frequent emotion across the frames

**Limits**

- A batch is 1 to 10 frames.

Price: 0.02 credits per successful call.

Body parameters

imagestring: Face image. One image. Or send frames instead. The image as base64 (JPEG or PNG). The SDKs also take a file path or the file bytes.
framesarray of strings: Frames. 1 to 10 images of the same scene, in order.
tagstring: Tag. Any text you want echoed back in the response.

Returns

The check ran.

Show the FaceEmotionResponse fields

okbooleanrequired

true: the result is in data.

request_idstring

latency_msnumber

How long the check took, in milliseconds.

dataobjectrequired

The answer of Emotion.

Show 5 fields

codenumber

msgstring

facesarray of objects

Show 3 fields

roiarray of numbers
emotionstring
confidencenumber

elapsedTimenumber

metadataobject

Show 2 fields

serverTimestring

ctxobject

Show 1 fields

userIpstring

warningsarray of strings

errorany

Empty on success.

Errors

400A field is missing or not valid.
401No API key, or the key is not valid, expired or revoked.
402Not enough credits for this call (insufficient_credits), or the key reached its spend cap. Nothing was charged.
403The key may not call this API (permission, environment or IP allow-list). Nothing was charged.
413The image or the request is too large.
429Too many requests for this key: wait Retry-After seconds. Nothing was charged.
5XXThe check could not run. Nothing was charged.

Request

curl -X POST https://verisec.dev/v1/face/emotion \
  -H "Authorization: Bearer $VERISEC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "frames": [
      "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="
    ]
  }'

Response · 200

{
  "ok": true,
  "request_id": "req_a68bd69124ec47a89571",
  "latency_ms": 839,
  "data": {
    "code": 0,
    "msg": "OK",
    "faces": [
      {
        "roi": [
          102,
          118,
          228,
          321
        ],
        "emotion": "neutral",
        "confidence": 0.15330377221107483
      }
    ],
    "elapsedTime": 0.762051539,
    "metadata": {
      "serverTime": "2026-10-05T05:34:53.384Z",
      "ctx": {
        "userIp": "203.0.113.7"
      }
    }
  },
  "warnings": [],
  "error": null
}

Smart Crop

POST/v1/face/cropface.crop

An aligned, straightened crop of the face at the shape you choose (square for an avatar, 4:5 for a document).

**Returns**

- crops[].crop: the aligned crop, base64 - crops[].roi: where the face was - crops[].rotationAngle: the tilt that was corrected

**Limits**

- Shapes: 3:4, 4:5, 2:3, 1:1, or 3:4 wider.

Price: 0.02 credits per successful call.

Body parameters

imagestringrequired: Image. The image as base64 (JPEG or PNG). The SDKs also take a file path or the file bytes.
typeinteger: Crop shape.; 01234
onlyCentralFaceboolean: Only the central face.
tagstring: Tag. Any text you want echoed back in the response.

Returns

The check ran.

Show the FaceCropResponse fields

okbooleanrequired

true: the result is in data.

request_idstring

latency_msnumber

How long the check took, in milliseconds.

dataobjectrequired

The answer of Smart Crop.

Show 5 fields

codenumber

msgstring

cropsarray of objects

Show 3 fields

roiarray of numbers
rotationAnglenumber
cropstring

elapsedTimenumber

metadataobject

Show 2 fields

serverTimestring

ctxobject

Show 1 fields

userIpstring

warningsarray of strings

errorany

Empty on success.

Errors

400A field is missing or not valid.
401No API key, or the key is not valid, expired or revoked.
402Not enough credits for this call (insufficient_credits), or the key reached its spend cap. Nothing was charged.
403The key may not call this API (permission, environment or IP allow-list). Nothing was charged.
413The image or the request is too large.
429Too many requests for this key: wait Retry-After seconds. Nothing was charged.
5XXThe check could not run. Nothing was charged.

Request

curl -X POST https://verisec.dev/v1/face/crop \
  -H "Authorization: Bearer $VERISEC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==",
    "type": 3,
    "onlyCentralFace": true
  }'

Response · 200

{
  "ok": true,
  "request_id": "req_cc2bde5498af4e6a8e35",
  "latency_ms": 530,
  "data": {
    "code": 0,
    "msg": "OK",
    "crops": [
      {
        "roi": [
          102,
          118,
          228,
          321
        ],
        "rotationAngle": 0.1800577672707395,
        "crop": "<base64 image>"
      }
    ],
    "elapsedTime": 0.484468657,
    "metadata": {
      "serverTime": "2026-10-05T05:34:56.695Z",
      "ctx": {
        "userIp": "203.0.113.7"
      }
    }
  },
  "warnings": [],
  "error": null
}

Face Redact

POST/v1/face/redactface.redact

The image back with every face hidden, blurred, pixelated or boxed out, plus where each face was.

**Returns**

- image: the redacted image, base64 - faceCount: faces hidden - boxes[]: each hidden region [x, y, w, h]

**Limits**

- Modes: blur, pixelate, black box. - If no face is found the original image comes back unchanged with faceCount 0.

Price: 0.02 credits per successful call.

Body parameters

imagestringrequired: Image. The image as base64 (JPEG or PNG). The SDKs also take a file path or the file bytes.
modestring: How to hide faces.; blurpixelatebox
tagstring: Tag. Any text you want echoed back in the response.

Returns

The check ran.

Show the FaceRedactResponse fields

okbooleanrequired

true: the result is in data.

request_idstring

latency_msnumber

How long the check took, in milliseconds.

dataobjectrequired

The answer of Face Redact.

Show 7 fields

codenumber

msgstring

faceCountnumber

imagestring

boxesarray of array of numberss

elapsedTimenumber

metadataobject

Show 2 fields

serverTimestring

ctxobject

Show 1 fields

userIpstring

warningsarray of strings

errorany

Empty on success.

Errors

400A field is missing or not valid.
401No API key, or the key is not valid, expired or revoked.
402Not enough credits for this call (insufficient_credits), or the key reached its spend cap. Nothing was charged.
403The key may not call this API (permission, environment or IP allow-list). Nothing was charged.
413The image or the request is too large.
429Too many requests for this key: wait Retry-After seconds. Nothing was charged.
5XXThe check could not run. Nothing was charged.

Request

curl -X POST https://verisec.dev/v1/face/redact \
  -H "Authorization: Bearer $VERISEC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==",
    "mode": "blur"
  }'

Response · 200

{
  "ok": true,
  "request_id": "req_f8f85cb128b741558fe5",
  "latency_ms": 579,
  "data": {
    "code": 0,
    "msg": "OK",
    "faceCount": 1,
    "image": "<base64 image>",
    "boxes": [
      [
        102,
        118,
        228,
        321
      ]
    ],
    "elapsedTime": 0.484965448,
    "metadata": {
      "serverTime": "2026-10-05T05:34:57.264Z",
      "ctx": {
        "userIp": "203.0.113.7"
      }
    }
  },
  "warnings": [],
  "error": null
}

Face Match

POST/v1/face/matchface.match

Compares the faces across two images: every face found in each, with a similarity for each pair. The 1:1 building block.

**Returns**

- results[].similarity: 0 to 1, calibrated; about 1 is the same person - results[].score: the raw distance; about 0 is the same person - detections[].faces[]: the faces found in each image, with boxes and crops

**Limits**

- Exactly two images per call. For more, call once per pair (or use Search / Cluster).

Price: 0.2 credits per successful call.

Body parameters

imagesarray of objectsrequired

Images. Exactly two images.

Show 5 fields

datastringrequired: The image as base64 (JPEG or PNG). The SDKs also take a file path or the file bytes.
indexinteger: The position of this image in the list (the SDKs fill it in).
typeinteger: Source. What this image is: a live photo, a printed document portrait, the photo from the chip, or another source.; 3125
detectAllboolean: Every face. On: every face in the image is compared. Off: only the main face.
livenessTransactionIdstring: Liveness transaction. The id of a liveness check you already ran, to link this image to it.

cropobject

Show 1 fields

typeany: Aligned crop. Adds an aligned crop of every face.; 01234

limitComparePerImageTypesinteger

Compare limit. A cap on comparisons per image type.

tagstring

Tag. Any text you want echoed back in the response.

Returns

The check ran.

Show the FaceMatchResponse fields

okbooleanrequired: true: the result is in data.
request_idstring
latency_msnumber: How long the check took, in milliseconds.
dataobjectrequired: The full result of Face Match: everything the check found. See the fields listed in the operation.
warningsarray of strings
errorany: Empty on success.

Errors

400A field is missing or not valid.
401No API key, or the key is not valid, expired or revoked.
402Not enough credits for this call (insufficient_credits), or the key reached its spend cap. Nothing was charged.
403The key may not call this API (permission, environment or IP allow-list). Nothing was charged.
413The image or the request is too large.
429Too many requests for this key: wait Retry-After seconds. Nothing was charged.
5XXThe check could not run. Nothing was charged.

Request

curl -X POST https://verisec.dev/v1/face/match \
  -H "Authorization: Bearer $VERISEC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "images": [
      {
        "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==",
        "index": 0
      },
      {
        "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==",
        "index": 1
      }
    ]
  }'

Response · 200

{
  "ok": true,
  "request_id": "req_613585979c3240a9b3d1",
  "latency_ms": 1441,
  "data": {
    "ErrorCode": 0,
    "code": 0,
    "detections": [
      {
        "faces": [
          {
            "crop": "<base64 image>",
            "faceIndex": 0,
            "landmarks": [
              [
                231,
                318
              ],
              [
                316,
                328
              ],
              [
                270,
                361
              ],
              [
                233,
                403
              ],
              [
                295,
                410
              ]
            ],
            "roi": [
              182,
              241,
              173,
              220
            ],
            "rotationAngle": -6.859032212941655
          }
        ],
        "imageIndex": 0,
        "status": 0
      },
      {
        "faces": [
          {
            "crop": "<base64 image>",
            "faceIndex": 0,
            "landmarks": [
              [
                979,
                327
              ],
              [
                1067,
                318
              ],
              [
                1025,
                363
              ],
              [
                1001,
                409
              ],
              [
                1066,
                400
              ]
            ],
            "roi": [
              940,
              245,
              176,
              216
            ],
            "rotationAngle": 6.693138443756709
          }
        ],
        "imageIndex": 1,
        "status": 0
      }
    ],
    "elapsedTime": 1.354184331,
    "msg": "OK",
    "results": [
      {
        "first": 3,
        "firstFaceIndex": 0,
        "firstIndex": 0,
        "score": 0.23992152512073517,
        "second": 3,
        "secondFaceIndex": 0,
        "secondIndex": 1,
        "similarity": 0.9983906745910645
      }
    ],
    "metadata": {
      "serverTime": "2026-10-05T05:34:58.755Z",
      "ctx": {
        "userIp": "203.0.113.7"
      }
    }
  },
  "warnings": [],
  "error": null
}

Face Verify (1:1)

POST/v1/face/verifyface.verify

A 1:1 decision: the similarity of two faces, and whether it clears your threshold.

**Returns**

- similarity: 0 to 1, the number to decide on - score: the raw distance - match: true at or above your threshold - threshold: the threshold applied - compared[]: the face box used in each image, so you can see which person was compared

**Limits**

- Threshold is 0 to 1. - livenessTransactionId links the first face to a passed liveness session.

Price: 0.2 credits per successful call.

Body parameters

image1stringrequired: First face. The image as base64 (JPEG or PNG). The SDKs also take a file path or the file bytes.
image2stringrequired: Second face. The image as base64 (JPEG or PNG). The SDKs also take a file path or the file bytes.
thresholdnumber: Threshold. match is true at or above this similarity.
livenessTransactionIdstring: Liveness transaction. Links the first face to a passed liveness session.
tagstring: Tag. Any text you want echoed back in the response.

Returns

The check ran.

Show the FaceVerifyResponse fields

okbooleanrequired

true: the result is in data.

request_idstring

latency_msnumber

How long the check took, in milliseconds.

dataobjectrequired

The answer of Face Verify (1:1).

Show 9 fields

codenumber

msgstring

similaritynumber

scorenumber

matchboolean

thresholdnumber

comparedarray of objects

Show 2 fields

imagestring
roiarray of numbers

elapsedTimenumber

metadataobject

Show 2 fields

serverTimestring

ctxobject

Show 1 fields

userIpstring

warningsarray of strings

errorany

Empty on success.

Errors

400A field is missing or not valid.
401No API key, or the key is not valid, expired or revoked.
402Not enough credits for this call (insufficient_credits), or the key reached its spend cap. Nothing was charged.
403The key may not call this API (permission, environment or IP allow-list). Nothing was charged.
413The image or the request is too large.
429Too many requests for this key: wait Retry-After seconds. Nothing was charged.
5XXThe check could not run. Nothing was charged.

Request

curl -X POST https://verisec.dev/v1/face/verify \
  -H "Authorization: Bearer $VERISEC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image1": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==",
    "image2": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==",
    "threshold": 0.75
  }'

Response · 200

{
  "ok": true,
  "request_id": "req_cd1d47ea5bf34b7aae6c",
  "latency_ms": 2362,
  "data": {
    "code": 0,
    "msg": "OK",
    "similarity": 0.9983906745910645,
    "score": 0.23992152512073517,
    "match": true,
    "threshold": 0.75,
    "compared": [
      {
        "image": "image1",
        "roi": [
          182,
          241,
          173,
          220
        ]
      },
      {
        "image": "image2",
        "roi": [
          940,
          245,
          176,
          216
        ]
      }
    ],
    "elapsedTime": 2.299846035,
    "metadata": {
      "serverTime": "2026-10-05T05:35:01.160Z",
      "ctx": {
        "userIp": "203.0.113.7"
      }
    }
  },
  "warnings": [],
  "error": null
}

Similarity Score

POST/v1/face/similarityface.similarity

Only the raw numbers: similarity and distance between two faces. No threshold, no decision.

**Returns**

- similarity: 0 to 1, calibrated - score: the raw distance - compared[]: the face box used in each image

Price: 0.02 credits per successful call.

Body parameters

image1stringrequired: First face. The image as base64 (JPEG or PNG). The SDKs also take a file path or the file bytes.
image2stringrequired: Second face. The image as base64 (JPEG or PNG). The SDKs also take a file path or the file bytes.
tagstring: Tag. Any text you want echoed back in the response.

Returns

The check ran.

Show the FaceSimilarityResponse fields

okbooleanrequired

true: the result is in data.

request_idstring

latency_msnumber

How long the check took, in milliseconds.

dataobjectrequired

The answer of Similarity Score.

Show 7 fields

codenumber

msgstring

similaritynumber

scorenumber

comparedarray of objects

Show 2 fields

imagestring
roiarray of numbers

elapsedTimenumber

metadataobject

Show 2 fields

serverTimestring

ctxobject

Show 1 fields

userIpstring

warningsarray of strings

errorany

Empty on success.

Errors

400A field is missing or not valid.
401No API key, or the key is not valid, expired or revoked.
402Not enough credits for this call (insufficient_credits), or the key reached its spend cap. Nothing was charged.
403The key may not call this API (permission, environment or IP allow-list). Nothing was charged.
413The image or the request is too large.
429Too many requests for this key: wait Retry-After seconds. Nothing was charged.
5XXThe check could not run. Nothing was charged.

Request

curl -X POST https://verisec.dev/v1/face/similarity \
  -H "Authorization: Bearer $VERISEC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image1": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==",
    "image2": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="
  }'

Response · 200

{
  "ok": true,
  "request_id": "req_84fff5b015e1404ba5cc",
  "latency_ms": 1394,
  "data": {
    "code": 0,
    "msg": "OK",
    "similarity": 0.002763261552900076,
    "score": 2.0924413204193115,
    "compared": [
      {
        "image": "image1",
        "roi": [
          182,
          241,
          173,
          220
        ]
      },
      {
        "image": "image2",
        "roi": [
          102,
          118,
          228,
          321
        ]
      }
    ],
    "elapsedTime": 1.308462705,
    "metadata": {
      "serverTime": "2026-10-05T05:35:08.693Z",
      "ctx": {
        "userIp": "203.0.113.7"
      }
    }
  },
  "warnings": [],
  "error": null
}

Face Search (1:N)

POST/v1/face/searchface.search

One face against a gallery you send. Returns the gallery faces at or above your threshold, highest similarity first.

**Returns**

- matches[]: id, similarity and rank, best first, above the threshold - best: the top match, or null

**Limits**

- 1 to 10 gallery faces. Each is compared one at a time, so more faces take longer. - A gallery face with no detectable face is skipped and noted in warnings.

Price: 0.3 credits per successful call.

Body parameters

probestringrequired

Face to find. The image as base64 (JPEG or PNG). The SDKs also take a file path or the file bytes.

galleryarray of objectsrequired

Gallery. 1 to 10 faces, each with your own id.

Show 2 fields

imagestringrequired: The image as base64 (JPEG or PNG). The SDKs also take a file path or the file bytes.
idstring: Your id for this face (the SDKs fill in face-1, face-2, ... when left out).

topKinteger

Top matches.

thresholdnumber

Threshold. Only faces at or above this similarity are matches.

tagstring

Tag. Any text you want echoed back in the response.

Returns

The check ran.

Show the FaceSearchResponse fields

okbooleanrequired

true: the result is in data.

request_idstring

latency_msnumber

How long the check took, in milliseconds.

dataobjectrequired

The answer of Face Search (1:N).

Show 6 fields

codenumber

msgstring

matchesarray of objects

Show 3 fields

idstring
similaritynumber
ranknumber

bestobject

Show 2 fields

idstring
similaritynumber

elapsedTimenumber

metadataobject

Show 2 fields

serverTimestring

ctxobject

Show 1 fields

userIpstring

warningsarray of strings

errorany

Empty on success.

Errors

400A field is missing or not valid.
401No API key, or the key is not valid, expired or revoked.
402Not enough credits for this call (insufficient_credits), or the key reached its spend cap. Nothing was charged.
403The key may not call this API (permission, environment or IP allow-list). Nothing was charged.
413The image or the request is too large.
429Too many requests for this key: wait Retry-After seconds. Nothing was charged.
5XXThe check could not run. Nothing was charged.

Request

curl -X POST https://verisec.dev/v1/face/search \
  -H "Authorization: Bearer $VERISEC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "probe": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==",
    "gallery": [
      {
        "image": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==",
        "id": "face-1"
      }
    ],
    "topK": 3,
    "threshold": 0.75
  }'

Response · 200

{
  "ok": true,
  "request_id": "req_f7cc793770774b209ad5",
  "latency_ms": 4758,
  "data": {
    "code": 0,
    "msg": "OK",
    "matches": [
      {
        "id": "b",
        "similarity": 0.9983906745910645,
        "rank": 1
      }
    ],
    "best": {
      "id": "b",
      "similarity": 0.9983906745910645
    },
    "elapsedTime": 4.759,
    "metadata": {
      "serverTime": "2026-10-05T05:35:10.320Z",
      "ctx": {
        "userIp": "203.0.113.7"
      }
    }
  },
  "warnings": [
    "gallery face 'c': Second image face not detected."
  ],
  "error": null
}

Duplicate Check

POST/v1/face/dedupeface.dedupe

Whether a new face already exists in your set: the closest existing face and if it clears the duplicate threshold.

**Returns**

- duplicate: true if the closest face is at or above your threshold - matchedId: the id it matched, or null - similarity: the closest similarity

**Limits**

- 1 to 10 existing faces.

Price: 0.02 credits per successful call.

Body parameters

candidatestringrequired

New face. The image as base64 (JPEG or PNG). The SDKs also take a file path or the file bytes.

existingarray of objectsrequired

Existing faces. 1 to 10 faces, each with your own id.

Show 2 fields

imagestringrequired: The image as base64 (JPEG or PNG). The SDKs also take a file path or the file bytes.
idstring: Your id for this face (the SDKs fill in face-1, face-2, ... when left out).

thresholdnumber

Threshold. A duplicate at or above this similarity.

tagstring

Tag. Any text you want echoed back in the response.

Returns

The check ran.

Show the FaceDedupeResponse fields

okbooleanrequired

true: the result is in data.

request_idstring

latency_msnumber

How long the check took, in milliseconds.

dataobjectrequired

The answer of Duplicate Check.

Show 7 fields

codenumber

msgstring

duplicateboolean

matchedIdstring

similaritynumber

elapsedTimenumber

metadataobject

Show 2 fields

serverTimestring

ctxobject

Show 1 fields

userIpstring

warningsarray of strings

errorany

Empty on success.

Errors

400A field is missing or not valid.
401No API key, or the key is not valid, expired or revoked.
402Not enough credits for this call (insufficient_credits), or the key reached its spend cap. Nothing was charged.
403The key may not call this API (permission, environment or IP allow-list). Nothing was charged.
413The image or the request is too large.
429Too many requests for this key: wait Retry-After seconds. Nothing was charged.
5XXThe check could not run. Nothing was charged.

Request

curl -X POST https://verisec.dev/v1/face/dedupe \
  -H "Authorization: Bearer $VERISEC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "candidate": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==",
    "existing": [
      {
        "image": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==",
        "id": "face-1"
      }
    ],
    "threshold": 0.8
  }'

Response · 200

{
  "ok": true,
  "request_id": "req_60d9550d11bb4defb9c0",
  "latency_ms": 3046,
  "data": {
    "code": 0,
    "msg": "OK",
    "duplicate": true,
    "matchedId": "u2",
    "similarity": 0.9983906745910645,
    "elapsedTime": 3.046,
    "metadata": {
      "serverTime": "2026-10-05T05:35:14.914Z",
      "ctx": {
        "userIp": "203.0.113.7"
      }
    }
  },
  "warnings": [],
  "error": null
}

Watchlist Screening

POST/v1/face/watchlistface.watchlist

A face against your own labelled list (blocked, VIP, staff). Returns a hit and the matched entry with its label.

**Returns**

- hit: true if a list face clears the threshold - entry: the matched id, label and similarity, or null

**Limits**

- 1 to 10 list faces.

Price: 0.3 credits per successful call.

Body parameters

probestringrequired

Face to check. The image as base64 (JPEG or PNG). The SDKs also take a file path or the file bytes.

listarray of objectsrequired

Your list. 1 to 10 faces, each with your own id and a label.

Show 3 fields

imagestringrequired: The image as base64 (JPEG or PNG). The SDKs also take a file path or the file bytes.
idstring: Your id for this face (the SDKs fill in face-1, face-2, ... when left out).
labelstring: A label for this face.

thresholdnumber

Threshold. A hit at or above this similarity.

tagstring

Tag. Any text you want echoed back in the response.

Returns

The check ran.

Show the FaceWatchlistResponse fields

okbooleanrequired

true: the result is in data.

request_idstring

latency_msnumber

How long the check took, in milliseconds.

dataobjectrequired

The answer of Watchlist Screening.

Show 6 fields

codenumber

msgstring

hitboolean

entryobject

Show 3 fields

idstring
labelstring
similaritynumber

elapsedTimenumber

metadataobject

Show 2 fields

serverTimestring

ctxobject

Show 1 fields

userIpstring

warningsarray of strings

errorany

Empty on success.

Errors

400A field is missing or not valid.
401No API key, or the key is not valid, expired or revoked.
402Not enough credits for this call (insufficient_credits), or the key reached its spend cap. Nothing was charged.
403The key may not call this API (permission, environment or IP allow-list). Nothing was charged.
413The image or the request is too large.
429Too many requests for this key: wait Retry-After seconds. Nothing was charged.
5XXThe check could not run. Nothing was charged.

Request

curl -X POST https://verisec.dev/v1/face/watchlist \
  -H "Authorization: Bearer $VERISEC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "probe": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==",
    "list": [
      {
        "image": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==",
        "id": "face-1"
      }
    ],
    "threshold": 0.8
  }'

Response · 200

{
  "ok": true,
  "request_id": "req_9f8770f9789243b38e7d",
  "latency_ms": 2753,
  "data": {
    "code": 0,
    "msg": "OK",
    "hit": true,
    "entry": {
      "id": "w1",
      "label": "blocked",
      "similarity": 0.9983906745910645
    },
    "elapsedTime": 2.753,
    "metadata": {
      "serverTime": "2026-10-05T05:35:19.340Z",
      "ctx": {
        "userIp": "203.0.113.7"
      }
    }
  },
  "warnings": [],
  "error": null
}

Face Cluster

POST/v1/face/clusterface.cluster

Groups faces by person. Every pair is compared, and faces are linked when they clear your threshold.

**Returns**

- clusters[]: groups of ids that are the same person - pairs[]: every pair with its similarity, highest first

**Limits**

- 2 to 8 faces (every pair is compared, so this grows quickly).

Price: 0.02 credits per successful call.

Body parameters

facesarray of objectsrequired

Faces. 2 to 8 faces, each with your own id.

Show 2 fields

imagestringrequired: The image as base64 (JPEG or PNG). The SDKs also take a file path or the file bytes.
idstring: Your id for this face (the SDKs fill in face-1, face-2, ... when left out).

thresholdnumber

Threshold. Two faces join a group at or above this similarity.

tagstring

Tag. Any text you want echoed back in the response.

Returns

The check ran.

Show the FaceClusterResponse fields

okbooleanrequired

true: the result is in data.

request_idstring

latency_msnumber

How long the check took, in milliseconds.

dataobjectrequired

The answer of Face Cluster.

Show 6 fields

codenumber

msgstring

clustersarray of array of stringss

pairsarray of objects

Show 3 fields

astring
bstring
similaritynumber

elapsedTimenumber

metadataobject

Show 2 fields

serverTimestring

ctxobject

Show 1 fields

userIpstring

warningsarray of strings

errorany

Empty on success.

Errors

400A field is missing or not valid.
401No API key, or the key is not valid, expired or revoked.
402Not enough credits for this call (insufficient_credits), or the key reached its spend cap. Nothing was charged.
403The key may not call this API (permission, environment or IP allow-list). Nothing was charged.
413The image or the request is too large.
429Too many requests for this key: wait Retry-After seconds. Nothing was charged.
5XXThe check could not run. Nothing was charged.

Request

curl -X POST https://verisec.dev/v1/face/cluster \
  -H "Authorization: Bearer $VERISEC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "faces": [
      {
        "image": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==",
        "id": "face-1"
      },
      {
        "image": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==",
        "id": "face-2"
      }
    ],
    "threshold": 0.75
  }'

Response · 200

{
  "ok": true,
  "request_id": "req_b2b8a49b6eb94360a874",
  "latency_ms": 4301,
  "data": {
    "code": 0,
    "msg": "OK",
    "clusters": [
      [
        "1",
        "3"
      ],
      [
        "2"
      ]
    ],
    "pairs": [
      {
        "a": "1",
        "b": "3",
        "similarity": 0.9983906745910645
      },
      {
        "a": "1",
        "b": "2",
        "similarity": 0.002763261552900076
      },
      {
        "a": "2",
        "b": "3",
        "similarity": 0.0023473226465284824
      }
    ],
    "elapsedTime": 4.301,
    "metadata": {
      "serverTime": "2026-10-05T05:35:22.373Z",
      "ctx": {
        "userIp": "203.0.113.7"
      }
    }
  },
  "warnings": [],
  "error": null
}

Age Estimation

POST/v1/face/ageface.age

The age range of each face, its midpoint, and an aligned crop. The range is most exact with the crop on.

**Returns**

- faces[].age: the [min, max] age band - faces[].ageMid: the midpoint, for a single number - faces[].crop: the aligned crop

Price: 0.05 credits per successful call.

Body parameters

imagestringrequired

Face image. The image as base64 (JPEG or PNG). The SDKs also take a file path or the file bytes.

onlyCentralFaceboolean

Only the central face.

cropobject

Show 1 fields

typeany: Aligned crop. Recommended: the range is most exact with a crop.; 01234

tagstring

Tag. Any text you want echoed back in the response.

Returns

The check ran.

Show the FaceAgeResponse fields

okbooleanrequired: true: the result is in data.
request_idstring
latency_msnumber: How long the check took, in milliseconds.
dataobjectrequired: The full result of Age Estimation: everything the check found. See the fields listed in the operation.
warningsarray of strings
errorany: Empty on success.

Errors

400A field is missing or not valid.
401No API key, or the key is not valid, expired or revoked.
402Not enough credits for this call (insufficient_credits), or the key reached its spend cap. Nothing was charged.
403The key may not call this API (permission, environment or IP allow-list). Nothing was charged.
413The image or the request is too large.
429Too many requests for this key: wait Retry-After seconds. Nothing was charged.
5XXThe check could not run. Nothing was charged.

Request

curl -X POST https://verisec.dev/v1/face/age \
  -H "Authorization: Bearer $VERISEC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==",
    "onlyCentralFace": false,
    "crop": {
      "type": 1
    }
  }'

Response · 200

{
  "ok": true,
  "request_id": "req_76185051933d44baaa47",
  "latency_ms": 1425,
  "data": {
    "code": 0,
    "msg": "OK",
    "faces": [
      {
        "roi": [
          102,
          118,
          228,
          321
        ],
        "age": [
          29,
          31
        ],
        "ageMid": 30,
        "crop": "<base64 image>"
      }
    ],
    "elapsedTime": 1.364995716,
    "metadata": {
      "serverTime": "2026-10-05T05:35:25.112Z",
      "ctx": {
        "userIp": "203.0.113.7"
      }
    }
  },
  "warnings": [],
  "error": null
}

Age Check

POST/v1/age/verifyage.verify

An age gate: pass or fail against a minimum age, deciding on the lower end of the range (strict) or the midpoint.

**Returns**

- age: the estimated band - allowed: true if old enough - basis: the exact rule applied, e.g. lowerBound(29)>=18

**Limits**

- Minimum age 0 to 120.

Price: 0.05 credits per successful call.

Body parameters

imagestringrequired: Face image. The image as base64 (JPEG or PNG). The SDKs also take a file path or the file bytes.
minAgeinteger: Minimum age.
policystring: Decide on.; lowerBoundmidpoint
tagstring: Tag. Any text you want echoed back in the response.

Returns

The check ran.

Show the AgeVerifyResponse fields

okbooleanrequired

true: the result is in data.

request_idstring

latency_msnumber

How long the check took, in milliseconds.

dataobjectrequired

The answer of Age Check.

Show 8 fields

codenumber

msgstring

agearray of numbers

allowedboolean

minAgenumber

basisstring

elapsedTimenumber

metadataobject

Show 2 fields

serverTimestring

ctxobject

Show 1 fields

userIpstring

warningsarray of strings

errorany

Empty on success.

Errors

400A field is missing or not valid.
401No API key, or the key is not valid, expired or revoked.
402Not enough credits for this call (insufficient_credits), or the key reached its spend cap. Nothing was charged.
403The key may not call this API (permission, environment or IP allow-list). Nothing was charged.
413The image or the request is too large.
429Too many requests for this key: wait Retry-After seconds. Nothing was charged.
5XXThe check could not run. Nothing was charged.

Request

curl -X POST https://verisec.dev/v1/age/verify \
  -H "Authorization: Bearer $VERISEC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==",
    "minAge": 18,
    "policy": "lowerBound"
  }'

Response · 200

{
  "ok": true,
  "request_id": "req_4e2655f727c143dcbef3",
  "latency_ms": 1476,
  "data": {
    "code": 0,
    "msg": "OK",
    "age": [
      29,
      31
    ],
    "allowed": true,
    "minAge": 18,
    "basis": "lowerBound(29)>=18",
    "elapsedTime": 1.388019878,
    "metadata": {
      "serverTime": "2026-10-05T05:35:26.567Z",
      "ctx": {
        "userIp": "203.0.113.7"
      }
    }
  },
  "warnings": [],
  "error": null
}

Age Check + Liveness

POST/v1/age/verify-liveage.verifyLive

The age gate plus liveness: allowed only when the person is old enough AND the face is live.

**Returns**

- age: the estimated band - allowed: true only if old enough and live - live: the liveness result

**Limits**

- A single still often reads as not-live; this is strongest with a genuine live capture.

Price: 0.25 credits per successful call.

Body parameters

imagestringrequired: Face image. The image as base64 (JPEG or PNG). The SDKs also take a file path or the file bytes.
minAgeinteger: Minimum age.
tagstring: Tag. Any text you want echoed back in the response.

Returns

The check ran.

Show the AgeVerifyLiveResponse fields

okbooleanrequired

true: the result is in data.

request_idstring

latency_msnumber

How long the check took, in milliseconds.

dataobjectrequired

The answer of Age Check + Liveness.

Show 8 fields

codenumber

msgstring

agearray of numbers

allowedboolean

liveboolean

basisstring

elapsedTimenumber

metadataobject

Show 2 fields

serverTimestring

ctxobject

Show 1 fields

userIpstring

warningsarray of strings

errorany

Empty on success.

Errors

400A field is missing or not valid.
401No API key, or the key is not valid, expired or revoked.
402Not enough credits for this call (insufficient_credits), or the key reached its spend cap. Nothing was charged.
403The key may not call this API (permission, environment or IP allow-list). Nothing was charged.
413The image or the request is too large.
429Too many requests for this key: wait Retry-After seconds. Nothing was charged.
5XXThe check could not run. Nothing was charged.

Request

curl -X POST https://verisec.dev/v1/age/verify-live \
  -H "Authorization: Bearer $VERISEC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==",
    "minAge": 21
  }'

Response · 200

{
  "ok": true,
  "request_id": "req_fd9a9fa7649d4f5fa11a",
  "latency_ms": 3992,
  "data": {
    "code": 0,
    "msg": "OK",
    "age": [
      29,
      31
    ],
    "allowed": false,
    "live": false,
    "basis": "lowerBound(29)>=21",
    "elapsedTime": 3.993,
    "metadata": {
      "serverTime": "2026-10-05T05:35:27.626Z",
      "ctx": {
        "userIp": "203.0.113.7"
      }
    }
  },
  "warnings": [],
  "error": null
}

Photo Quality

POST/v1/face/qualityface.quality

Scores a portrait against a standard (ICAO, Schengen, US visa, Full) or your own checks. Returns every check with its value, its range and pass/fail, plus group roll-ups and an optional crop.

**Returns**

- compliant: true when nothing failed - nonCompliant[]: the checks that failed - checks[]: every check: name, range, value, status - groups[]: per group, how many passed - crop: the aligned crop, if requested

**Limits**

- ICAO and US visa run 44 checks, Schengen 43, Full 47. - Your own checks replace the standard: exactly those run, with your ranges.

Price: 0.02 credits per successful call.

Body parameters

imagestringrequired

Portrait. The image as base64 (JPEG or PNG). The SDKs also take a file path or the file bytes.

scenariostring

Standard.

QualityICAOQualityVisaSchengenQualityVisaUSAQualityFull

onlyCentralFaceboolean

Only the central face.

outputobject

Show 2 fields

cropobject

Show 1 fields

typeany: Aligned crop.; 01234

backgroundColorarray of integers

Crop background. Replaces the background of the crop.

customChecksany

Your own checks. When you add checks, they replace the standard: exactly these run, with your ranges.

tagstring

Tag. Any text you want echoed back in the response.

Returns

The check ran.

Show the FaceQualityResponse fields

okbooleanrequired: true: the result is in data.
request_idstring
latency_msnumber: How long the check took, in milliseconds.
dataobjectrequired: The full result of Photo Quality: everything the check found. See the fields listed in the operation.
warningsarray of strings
errorany: Empty on success.

Errors

400A field is missing or not valid.
401No API key, or the key is not valid, expired or revoked.
402Not enough credits for this call (insufficient_credits), or the key reached its spend cap. Nothing was charged.
403The key may not call this API (permission, environment or IP allow-list). Nothing was charged.
413The image or the request is too large.
429Too many requests for this key: wait Retry-After seconds. Nothing was charged.
5XXThe check could not run. Nothing was charged.

Request

curl -X POST https://verisec.dev/v1/face/quality \
  -H "Authorization: Bearer $VERISEC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==",
    "scenario": "QualityICAO",
    "onlyCentralFace": true,
    "output": {
      "crop": {
        "type": 0
      },
      "backgroundColor": [
        255,
        255,
        255
      ]
    }
  }'

Response · 200

{
  "ok": true,
  "request_id": "req_150622a436b04dd19022",
  "latency_ms": 1816,
  "data": {
    "code": 0,
    "msg": "OK",
    "compliant": true,
    "nonCompliant": [],
    "groups": [
      {
        "compliantCount": 5,
        "groupId": 1,
        "name": "ImageCharacteristics",
        "totalCount": 5
      },
      {
        "compliantCount": 8,
        "groupId": 2,
        "name": "HeadSizeAndPosition",
        "totalCount": 8
      },
      {
        "compliantCount": 4,
        "groupId": 3,
        "name": "FaceQuality",
        "totalCount": 4
      },
      {
        "compliantCount": 8,
        "groupId": 4,
        "name": "EyesCharacteristics",
        "totalCount": 8
      },
      {
        "compliantCount": 4,
        "groupId": 5,
        "name": "ShadowsAndLightning",
        "totalCount": 4
      },
      {
        "compliantCount": 4,
        "groupId": 6,
        "name": "PoseAndExpression",
        "totalCount": 4
      },
      {
        "compliantCount": 8,
        "groupId": 7,
        "name": "HeadOcclusion",
        "totalCount": 8
      },
      {
        "compliantCount": 3,
        "groupId": 8,
        "name": "Background",
        "totalCount": 3
      }
    ],
    "checks": [
      {
        "groupId": 1,
        "name": "ImageWidth",
        "range": [
          480,
          10000
        ],
        "status": 1,
        "value": 480
      },
      {
        "groupId": 1,
        "name": "ImageHeight",
        "range": [
          640,
          10000
        ],
        "status": 1,
        "value": 640
      },
      {
        "groupId": 1,
        "name": "ImageWidthToHeight",
        "range": [
          0.7400000095367432,
          0.800000011920929
        ],
        "status": 1,
        "value": 0.75
      },
      {
        "groupId": 1,
        "name": "ImageChannelsNumber",
        "range": [
          3,
          3
        ],
        "status": 1,
        "value": 3
      }
    ],
    "scenario": "QualityICAO",
    "crop": "<base64 image>",
    "elapsedTime": 1.768051338,
    "metadata": {
      "serverTime": "2026-10-05T05:35:32.429Z",
      "ctx": {
        "userIp": "203.0.113.7"
      }
    }
  },
  "warnings": [],
  "error": null
}

Photo Compliance

POST/v1/photo/compliancephoto.compliance

A pass/fail against one named passport or visa photo standard, with the list of failed checks.

**Returns**

- compliant: true or false - nonCompliant[]: the checks that failed - checks[]: every check with value and status - standard: the standard applied

**Limits**

- Standards: ICAO, VisaSchengen, VisaUSA, Full.

Price: 0.02 credits per successful call.

Body parameters

imagestringrequired: Portrait. The image as base64 (JPEG or PNG). The SDKs also take a file path or the file bytes.
standardstring: Standard.; ICAOVisaSchengenVisaUSAFull
tagstring: Tag. Any text you want echoed back in the response.

Returns

The check ran.

Show the PhotoComplianceResponse fields

okbooleanrequired

true: the result is in data.

request_idstring

latency_msnumber

How long the check took, in milliseconds.

dataobjectrequired

The answer of Photo Compliance.

Show 8 fields

codenumber

msgstring

compliantboolean

nonCompliantarray of anys

checksarray of objects

Show 5 fields

groupIdnumber
namestring
rangearray of numbers
statusnumber
valuenumber

standardstring

elapsedTimenumber

metadataobject

Show 2 fields

serverTimestring

ctxobject

Show 1 fields

userIpstring

warningsarray of strings

errorany

Empty on success.

Errors

400A field is missing or not valid.
401No API key, or the key is not valid, expired or revoked.
402Not enough credits for this call (insufficient_credits), or the key reached its spend cap. Nothing was charged.
403The key may not call this API (permission, environment or IP allow-list). Nothing was charged.
413The image or the request is too large.
429Too many requests for this key: wait Retry-After seconds. Nothing was charged.
5XXThe check could not run. Nothing was charged.

Request

curl -X POST https://verisec.dev/v1/photo/compliance \
  -H "Authorization: Bearer $VERISEC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==",
    "standard": "ICAO"
  }'

Response · 200

{
  "ok": true,
  "request_id": "req_a68179bfea99413fb2d4",
  "latency_ms": 1150,
  "data": {
    "code": 0,
    "msg": "OK",
    "compliant": true,
    "nonCompliant": [],
    "checks": [
      {
        "groupId": 1,
        "name": "ImageWidth",
        "range": [
          480,
          10000
        ],
        "status": 1,
        "value": 480
      },
      {
        "groupId": 1,
        "name": "ImageHeight",
        "range": [
          640,
          10000
        ],
        "status": 1,
        "value": 640
      },
      {
        "groupId": 1,
        "name": "ImageWidthToHeight",
        "range": [
          0.7400000095367432,
          0.800000011920929
        ],
        "status": 1,
        "value": 0.75
      },
      {
        "groupId": 1,
        "name": "ImageChannelsNumber",
        "range": [
          3,
          3
        ],
        "status": 1,
        "value": 3
      }
    ],
    "standard": "ICAO",
    "elapsedTime": 1.079265742,
    "metadata": {
      "serverTime": "2026-10-05T05:35:33.591Z",
      "ctx": {
        "userIp": "203.0.113.7"
      }
    }
  },
  "warnings": [],
  "error": null
}

Photo Policy

POST/v1/photo/policyphoto.policy

Your own checks with your own ranges. Exactly the checks you send run, nothing else.

**Returns**

- pass: true when every check passed - failed[]: the checks that failed - checks[]: each check: name, range, value, status

**Limits**

- At least one check. Pick from the full check list; each needs a range.

Price: 0.02 credits per successful call.

Body parameters

imagestringrequired: Portrait. The image as base64 (JPEG or PNG). The SDKs also take a file path or the file bytes.
policyarray of anysrequired: Your checks.
tagstring: Tag. Any text you want echoed back in the response.

Returns

The check ran.

Show the PhotoPolicyResponse fields

okbooleanrequired

true: the result is in data.

request_idstring

latency_msnumber

How long the check took, in milliseconds.

dataobjectrequired

The answer of Photo Policy.

Show 7 fields

codenumber

msgstring

passboolean

failedarray of anys

checksarray of objects

Show 4 fields

namestring
rangearray of numbers
valuenumber
statusnumber

elapsedTimenumber

metadataobject

Show 2 fields

serverTimestring

ctxobject

Show 1 fields

userIpstring

warningsarray of strings

errorany

Empty on success.

Errors

400A field is missing or not valid.
401No API key, or the key is not valid, expired or revoked.
402Not enough credits for this call (insufficient_credits), or the key reached its spend cap. Nothing was charged.
403The key may not call this API (permission, environment or IP allow-list). Nothing was charged.
413The image or the request is too large.
429Too many requests for this key: wait Retry-After seconds. Nothing was charged.
5XXThe check could not run. Nothing was charged.

Request

curl -X POST https://verisec.dev/v1/photo/policy \
  -H "Authorization: Bearer $VERISEC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==",
    "policy": [
      {
        "name": "Yaw",
        "range": [
          -10,
          10
        ]
      },
      {
        "name": "BlurLevel",
        "range": [
          0,
          0.15
        ]
      }
    ]
  }'

Response · 200

{
  "ok": true,
  "request_id": "req_2d9e88790fd247f2a93f",
  "latency_ms": 596,
  "data": {
    "code": 0,
    "msg": "OK",
    "pass": true,
    "failed": [],
    "checks": [
      {
        "name": "Yaw",
        "range": [
          -10,
          10
        ],
        "value": -0.9016010761260986,
        "status": 1
      },
      {
        "name": "BlurLevel",
        "range": [
          0,
          0.15000000596046448
        ],
        "value": 0.05496573448181152,
        "status": 1
      }
    ],
    "elapsedTime": 0.565639973,
    "metadata": {
      "serverTime": "2026-10-05T05:35:34.214Z",
      "ctx": {
        "userIp": "203.0.113.7"
      }
    }
  },
  "warnings": [],
  "error": null
}

Quality Gate

POST/v1/photo/gatephoto.gate

A fast good-enough answer. Only the checks you require run, at their standard ranges, so it returns one ok and the list of any that failed.

**Returns**

- ok: true when every required check passed - failed[]: the checks that failed

**Limits**

- At least one check. Ranges are the standard ones, not yours (use Photo Policy for custom ranges).

Price: 0.02 credits per successful call.

Body parameters

imagestringrequired: Photo. The image as base64 (JPEG or PNG). The SDKs also take a file path or the file bytes.
requirearray of stringsrequired: Required checks.
tagstring: Tag. Any text you want echoed back in the response.

Returns

The check ran.

Show the PhotoGateResponse fields

okbooleanrequired

true: the result is in data.

request_idstring

latency_msnumber

How long the check took, in milliseconds.

dataobjectrequired

The answer of Quality Gate.

Show 6 fields

codenumber

msgstring

okboolean

failedarray of anys

elapsedTimenumber

metadataobject

Show 2 fields

serverTimestring

ctxobject

Show 1 fields

userIpstring

warningsarray of strings

errorany

Empty on success.

Errors

400A field is missing or not valid.
401No API key, or the key is not valid, expired or revoked.
402Not enough credits for this call (insufficient_credits), or the key reached its spend cap. Nothing was charged.
403The key may not call this API (permission, environment or IP allow-list). Nothing was charged.
413The image or the request is too large.
429Too many requests for this key: wait Retry-After seconds. Nothing was charged.
5XXThe check could not run. Nothing was charged.

Request

curl -X POST https://verisec.dev/v1/photo/gate \
  -H "Authorization: Bearer $VERISEC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==",
    "require": [
      "BlurLevel",
      "TooDark",
      "OffGaze"
    ]
  }'

Response · 200

{
  "ok": true,
  "request_id": "req_3ba5164cc7ce4867acf8",
  "latency_ms": 774,
  "data": {
    "code": 0,
    "msg": "OK",
    "ok": true,
    "failed": [],
    "elapsedTime": 0.701326287,
    "metadata": {
      "serverTime": "2026-10-05T05:35:35.005Z",
      "ctx": {
        "userIp": "203.0.113.7"
      }
    }
  },
  "warnings": [],
  "error": null
}

Photo Auto-fix

POST/v1/photo/autofixphoto.autofix

The portrait cropped to the shape you need, with the background replaced by your colour.

**Returns**

- image: the fixed portrait, base64 - aspect: the shape applied

**Limits**

- Shapes: 3:4, 4:5, 2:3, 1:1. Colour is [red, green, blue], each 0 to 255. - If the background cannot be told apart from the face (a portrait printed on a pattern), image is null and the reason is in warnings.

Price: 0.02 credits per successful call.

Body parameters

imagestringrequired: Portrait. The image as base64 (JPEG or PNG). The SDKs also take a file path or the file bytes.
aspectstring: Shape.; 3:44:52:31:1
backgroundColorarray of integers: Background.
tagstring: Tag. Any text you want echoed back in the response.

Returns

The check ran.

Show the PhotoAutofixResponse fields

okbooleanrequired

true: the result is in data.

request_idstring

latency_msnumber

How long the check took, in milliseconds.

dataobjectrequired

The answer of Photo Auto-fix.

Show 6 fields

codenumber

msgstring

imagestring

aspectstring

elapsedTimenumber

metadataobject

Show 2 fields

serverTimestring

ctxobject

Show 1 fields

userIpstring

warningsarray of strings

errorany

Empty on success.

Errors

400A field is missing or not valid.
401No API key, or the key is not valid, expired or revoked.
402Not enough credits for this call (insufficient_credits), or the key reached its spend cap. Nothing was charged.
403The key may not call this API (permission, environment or IP allow-list). Nothing was charged.
413The image or the request is too large.
429Too many requests for this key: wait Retry-After seconds. Nothing was charged.
5XXThe check could not run. Nothing was charged.

Request

curl -X POST https://verisec.dev/v1/photo/autofix \
  -H "Authorization: Bearer $VERISEC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==",
    "aspect": "3:4",
    "backgroundColor": [
      255,
      255,
      255
    ]
  }'

Response · 200

{
  "ok": true,
  "request_id": "req_62735bd14fb144ef8a4f",
  "latency_ms": 828,
  "data": {
    "code": 0,
    "msg": "OK",
    "image": "<base64 image>",
    "aspect": "3:4",
    "elapsedTime": 0.705820283,
    "metadata": {
      "serverTime": "2026-10-05T05:35:35.761Z",
      "ctx": {
        "userIp": "203.0.113.7"
      }
    }
  },
  "warnings": [],
  "error": null
}

Best Frame

POST/v1/photo/best-framephoto.bestFrame

Picks the most compliant of several frames against a standard, and shows how every frame ranked.

**Returns**

- bestIndex: the index of the best frame, or null if none had a face - ranking[]: each frame: compliant and failedCount, best first

**Limits**

- 2 to 10 frames.

Price: 0.02 credits per successful call.

Body parameters

framesarray of stringsrequired: Frames. 2 to 10 images of the same scene, in order.
standardstring: Standard.; ICAOVisaSchengenVisaUSAFull
tagstring: Tag. Any text you want echoed back in the response.

Returns

The check ran.

Show the PhotoBestFrameResponse fields

okbooleanrequired

true: the result is in data.

request_idstring

latency_msnumber

How long the check took, in milliseconds.

dataobjectrequired

The answer of Best Frame.

Show 6 fields

codenumber

msgstring

bestIndexnumber

rankingarray of objects

Show 3 fields

indexnumber
compliantboolean
failedCountany

elapsedTimenumber

metadataobject

Show 2 fields

serverTimestring

ctxobject

Show 1 fields

userIpstring

warningsarray of strings

errorany

Empty on success.

Errors

400A field is missing or not valid.
401No API key, or the key is not valid, expired or revoked.
402Not enough credits for this call (insufficient_credits), or the key reached its spend cap. Nothing was charged.
403The key may not call this API (permission, environment or IP allow-list). Nothing was charged.
413The image or the request is too large.
429Too many requests for this key: wait Retry-After seconds. Nothing was charged.
5XXThe check could not run. Nothing was charged.

Request

curl -X POST https://verisec.dev/v1/photo/best-frame \
  -H "Authorization: Bearer $VERISEC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "frames": [
      "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==",
      "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="
    ],
    "standard": "ICAO"
  }'

Response · 200

{
  "ok": true,
  "request_id": "req_08beeb19f3bc46b09a8f",
  "latency_ms": 2427,
  "data": {
    "code": 0,
    "msg": "OK",
    "bestIndex": 1,
    "ranking": [
      {
        "index": 1,
        "compliant": true,
        "failedCount": 0
      },
      {
        "index": 0,
        "compliant": false,
        "failedCount": 11
      },
      {
        "index": 2,
        "compliant": false,
        "failedCount": null
      }
    ],
    "elapsedTime": 2.428,
    "metadata": {
      "serverTime": "2026-10-05T05:35:37.492Z",
      "ctx": {
        "userIp": "203.0.113.7"
      }
    }
  },
  "warnings": [],
  "error": null
}

Liveness

POST/v1/livenessliveness.check

Passive liveness from one image. status 0 means live, 1 means not live or undetermined; code carries the reason; an age estimate comes free.

**Returns**

- status: 0 = live, 1 = not live - live: the same as status 0, as a boolean - code: the reason code (0 when live) - age: an age estimate

**Limits**

- Single image (passive). The face should be at least about 480×480 px.

Price: 0.2 credits per successful call.

Body parameters

imagestringrequired: Selfie. The image as base64 (JPEG or PNG). The SDKs also take a file path or the file bytes.
tagstring: Tag. Any text you want echoed back in the response.

Returns

The check ran.

Show the LivenessCheckResponse fields

okbooleanrequired: true: the result is in data.
request_idstring
latency_msnumber: How long the check took, in milliseconds.
dataobjectrequired: The full result of Liveness: everything the check found. See the fields listed in the operation.
warningsarray of strings
errorany: Empty on success.

Errors

400A field is missing or not valid.
401No API key, or the key is not valid, expired or revoked.
402Not enough credits for this call (insufficient_credits), or the key reached its spend cap. Nothing was charged.
403The key may not call this API (permission, environment or IP allow-list). Nothing was charged.
413The image or the request is too large.
429Too many requests for this key: wait Retry-After seconds. Nothing was charged.
5XXThe check could not run. Nothing was charged.

Request

curl -X POST https://verisec.dev/v1/liveness \
  -H "Authorization: Bearer $VERISEC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="
  }'

Response · 200

{
  "ok": true,
  "request_id": "req_de9a0ff4be064b4a940c",
  "latency_ms": 2323,
  "data": {
    "code": 244,
    "status": 1,
    "live": false,
    "tag": "bc6fd861-ce62-4a1b-bc27-d7830fca6438",
    "sessionId": "bc6fd861-ce62-4a1b-bc27-d7830fca6438",
    "transactionId": "9e00947e-b2aa-49d2-879d-16e476f8efc7",
    "metadata": {
      "elapsedTime": 2.224224916,
      "serverTime": "2026-10-05T05:35:41.299Z",
      "ctx": {
        "userIp": "203.0.113.7"
      }
    },
    "age": [
      {
        "pred": 30
      }
    ]
  },
  "warnings": [],
  "error": null
}

Anti-spoof Reason

POST/v1/liveness/antispoofliveness.antispoof

The same check with the reason spelled out: whether it is live, the reason by name, and its category (a presentation attack or a capture problem).

**Returns**

- live: true or false - reason: the reason by name, e.g. ART_MASK - reasonCode: the numeric code - category: presentation-attack, capture-quality, no-face or none

Price: 0.2 credits per successful call.

Body parameters

imagestringrequired: Selfie. The image as base64 (JPEG or PNG). The SDKs also take a file path or the file bytes.
tagstring: Tag. Any text you want echoed back in the response.

Returns

The check ran.

Show the LivenessAntispoofResponse fields

okbooleanrequired

true: the result is in data.

request_idstring

latency_msnumber

How long the check took, in milliseconds.

dataobjectrequired

The answer of Anti-spoof Reason.

Show 7 fields

codenumber

liveboolean

reasonstring

reasonCodenumber

categorystring

elapsedTimenumber

metadataobject

Show 3 fields

elapsedTimenumber

serverTimestring

ctxobject

Show 1 fields

userIpstring

warningsarray of strings

errorany

Empty on success.

Errors

400A field is missing or not valid.
401No API key, or the key is not valid, expired or revoked.
402Not enough credits for this call (insufficient_credits), or the key reached its spend cap. Nothing was charged.
403The key may not call this API (permission, environment or IP allow-list). Nothing was charged.
413The image or the request is too large.
429Too many requests for this key: wait Retry-After seconds. Nothing was charged.
5XXThe check could not run. Nothing was charged.

Request

curl -X POST https://verisec.dev/v1/liveness/antispoof \
  -H "Authorization: Bearer $VERISEC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="
  }'

Response · 200

{
  "ok": true,
  "request_id": "req_615d48c9ae85440fa804",
  "latency_ms": 1947,
  "data": {
    "code": 244,
    "live": false,
    "reason": "ART_MASK",
    "reasonCode": 244,
    "category": "presentation-attack",
    "elapsedTime": 1.86945563,
    "metadata": {
      "elapsedTime": 1.86945563,
      "serverTime": "2026-10-05T05:35:45.174Z",
      "ctx": {
        "userIp": "203.0.113.7"
      }
    }
  },
  "warnings": [],
  "error": null
}

Liveness Gate

POST/v1/liveness/gateliveness.gate

One pass/fail for a pipeline. Strict also requires a clean reason code, not just a live verdict.

**Returns**

- pass: true when live (and, in strict mode, the reason code is clean) - status: 0 = live, 1 = not

Price: 0.2 credits per successful call.

Body parameters

imagestringrequired: Selfie. The image as base64 (JPEG or PNG). The SDKs also take a file path or the file bytes.
strictboolean: Strict. Strict also requires a clean reason code.
tagstring: Tag. Any text you want echoed back in the response.

Returns

The check ran.

Show the LivenessGateResponse fields

okbooleanrequired

true: the result is in data.

request_idstring

latency_msnumber

How long the check took, in milliseconds.

dataobjectrequired

The answer of Liveness Gate.

Show 5 fields

codenumber

passboolean

statusnumber

elapsedTimenumber

metadataobject

Show 3 fields

elapsedTimenumber

serverTimestring

ctxobject

Show 1 fields

userIpstring

warningsarray of strings

errorany

Empty on success.

Errors

400A field is missing or not valid.
401No API key, or the key is not valid, expired or revoked.
402Not enough credits for this call (insufficient_credits), or the key reached its spend cap. Nothing was charged.
403The key may not call this API (permission, environment or IP allow-list). Nothing was charged.
413The image or the request is too large.
429Too many requests for this key: wait Retry-After seconds. Nothing was charged.
5XXThe check could not run. Nothing was charged.

Request

curl -X POST https://verisec.dev/v1/liveness/gate \
  -H "Authorization: Bearer $VERISEC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==",
    "strict": true
  }'

Response · 200

{
  "ok": true,
  "request_id": "req_d64bff25bb9c4ef6ae08",
  "latency_ms": 2304,
  "data": {
    "code": 244,
    "pass": false,
    "status": 1,
    "elapsedTime": 2.23751486,
    "metadata": {
      "elapsedTime": 2.23751486,
      "serverTime": "2026-10-05T05:35:47.485Z",
      "ctx": {
        "userIp": "203.0.113.7"
      }
    }
  },
  "warnings": [],
  "error": null
}