Biometrics

Liveness Detection

Credits: 1 per call.

Determines whether a selfie shows a real, live person in front of the camera (isLive: true) or a spoofing attempt (isLive: false).

Returns:

isLive: the decision. livenessScore (0–100) is the fused output of the anti-spoofing models; the decision threshold is 62.
confidence: how far the score landed from the threshold — HIGH (25 points or more), MEDIUM (10 or more) or LOW.
selfieAnalysis: quality and attribute labels of the evaluated face (image quality, orientation, eyes open, glasses, face covered, actionable issues[]). Same object as matchFaces, so both endpoints share one integration.

Multiple people in frame. By default a selfie with another person present returns MULTIPLE_FACES_DETECTED. Send allowMultipleFaces: true to evaluate the largest face in the image instead (the person holding the phone); selfieAnalysis describes that same face. Only faces of at least 25% of the main face’s area count as another person — people in the background do not.

Decision rule. Accept only type: SUCCESS with isLive: true. NO_FACE_DETECTED, MULTIPLE_FACES_DETECTED and IMAGE_UNREADABLE also return isLive: false, but nothing was evaluated — data always carries the full object so you can read data.isLive without branching on type. Detecting a spoofing attempt is a SUCCESS: the service did its job.

Images. JPG or PNG. The image is downscaled internally; no client-side resizing is needed. For best results send at least 1600 px on the longest side at JPEG quality 80 or better. The result is a liveness decision only; it does not verify identity — pair it with matchFaces for that.

INVALID_REQUEST returns every problem found in errors[] at once (cumulative), so you can fix them in one pass.

selfieAnalysis reference. Describes the evaluated face. Labels are derived from the face-analysis provider as follows:

Field	Values	Rule
`imageQuality`	`excellent` · `good` · `poor`	`excellent`: brightness ≥ 75 and sharpness ≥ 75 · `good`: both ≥ 50 · `poor`: otherwise. In practice `poor` almost always means a dark image, not an out-of-focus one.
`detectionConfidence`	`high` · `medium` · `low`	`high` ≥ 95 · `medium` ≥ 80 · `low` below 80.
`orientation`	`sideways` · `looking_left` · `looking_right` · `looking_up` · `looking_down` · `tilted` · `front`	Evaluated in that order, first match wins: `sideways` abs(yaw) ≥ 25° · `looking_left` yaw ≥ 10° · `looking_right` yaw ≤ −10° · `looking_up` pitch ≥ 20° · `looking_down` pitch ≤ −20° · `tilted` abs(roll) ≥ 15° · otherwise `front`.
`eyesOpen`, `mouthOpen`, `wearingGlasses`, `wearingSunglasses`, `faceCovered`	`true` · `false` · `null`	`null` when the attribute could not be determined. `mouthOpen` is informational and never produces an issue.

issues[] lists every condition detected on the face. All possible values:

Value	Condition
`poor_image_quality`	`imageQuality` is `poor`
`not_facing_camera`	`orientation` is not `front`
`eyes_closed`	`eyesOpen` is `false`
`face_covered`	`faceCovered` is `true` — mask, scarf, hand, hair over the eyes, face partly out of frame
`wearing_glasses`	`wearingGlasses` is `true` — informational, not a capture problem
`wearing_sunglasses`	`wearingSunglasses` is `true`
`low_detection_confidence`	`detectionConfidence` is `low`

In production about 4 in 10 legitimate selfies carry at least one issue — treat issues[] as retry hints, not as rejection criteria.

cURL

curl -X POST https://api.origoid.com/global/biometrics/v1/liveness-checks \
  -H "x-api-key: YOUR_API_KEY" \
  -H "content-type: application/json" \
  -d '{"selfie": "<base64 image (JPG or PNG)>"}'

const response = await fetch("https://api.origoid.com/global/biometrics/v1/liveness-checks", {
  method: "POST",
  headers: {
    "x-api-key": process.env.ORIGOID_API_KEY,
    "content-type": "application/json",
  },
  body: JSON.stringify({
    "selfie": "<base64 image (JPG or PNG)>"
  }),
});

if (!response.ok) {
  throw new Error(`HTTP ${response.status}`);
}

const result = await response.json();
console.log(result);

import os
import requests

response = requests.post(
    "https://api.origoid.com/global/biometrics/v1/liveness-checks",
    headers={
        "x-api-key": os.environ["ORIGOID_API_KEY"],
        "content-type": "application/json",
    },
    json={
        "selfie": "<base64 image (JPG or PNG)>"
    },
    timeout=30,
)
response.raise_for_status()
result = response.json()
print(result)

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class Example {
    public static void main(String[] args) throws Exception {
        String payload = "{\"selfie\": \"<base64 image (JPG or PNG)>\"}";

        HttpClient client = HttpClient.newBuilder()
            .connectTimeout(Duration.ofSeconds(10))
            .build();

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.origoid.com/global/biometrics/v1/liveness-checks"))
            .header("x-api-key", System.getenv("ORIGOID_API_KEY"))
            .header("content-type", "application/json")
            .timeout(Duration.ofSeconds(30))
            .POST(HttpRequest.BodyPublishers.ofString(payload))
            .build();

        HttpResponse<String> response = client.send(
            request, HttpResponse.BodyHandlers.ofString()
        );

        System.out.println(response.statusCode());
        System.out.println(response.body());
    }
}

<?php
$payload = '{"selfie": "<base64 image (JPG or PNG)>"}';

$ch = curl_init('https://api.origoid.com/global/biometrics/v1/liveness-checks');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $payload,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTPHEADER => [
        'x-api-key: ' . getenv('ORIGOID_API_KEY'),
        'content-type: application/json',
    ],
]);

$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($status >= 400) {
    throw new Exception("HTTP $status");
}

$result = json_decode($response, true);
print_r($result);

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"log"
	"net/http"
	"os"
	"time"
)

func main() {
	payload := []byte(`{"selfie": "<base64 image (JPG or PNG)>"}`)
	req, err := http.NewRequest("POST", "https://api.origoid.com/global/biometrics/v1/liveness-checks", bytes.NewBuffer(payload))
	if err != nil { log.Fatal(err) }
	req.Header.Set("x-api-key", os.Getenv("ORIGOID_API_KEY"))
	req.Header.Set("content-type", "application/json")

	client := &http.Client{Timeout: 30 * time.Second}
	resp, err := client.Do(req)
	if err != nil { log.Fatal(err) }
	defer resp.Body.Close()

	var result map[string]any
	if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
		log.Fatal(err)
	}
	fmt.Println(result)
}

using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        using var client = new HttpClient { Timeout = TimeSpan.FromSeconds(30) };
        client.DefaultRequestHeaders.Add("x-api-key",
            Environment.GetEnvironmentVariable("ORIGOID_API_KEY"));

        var payload = "{\"selfie\": \"<base64 image (JPG or PNG)>\"}";
        var content = new StringContent(payload, Encoding.UTF8, "application/json");

        var response = await client.PostAsync("https://api.origoid.com/global/biometrics/v1/liveness-checks", content);
        response.EnsureSuccessStatusCode();

        var body = await response.Content.ReadAsStringAsync();
        Console.WriteLine(body);
    }
}

{
  "status": "OK",
  "type": "SUCCESS",
  "message": "Liveness check completed",
  "data": {
    "isLive": true,
    "livenessScore": 98,
    "confidence": "HIGH",
    "selfieAnalysis": {
      "imageQuality": "excellent",
      "detectionConfidence": "high",
      "orientation": "front",
      "eyesOpen": true,
      "mouthOpen": false,
      "wearingGlasses": false,
      "wearingSunglasses": false,
      "faceCovered": false,
      "issues": []
    }
  },
  "transactionId": "f2da936b-4e13-47e9-8696-8f3526cf03fd",
  "processedAt": "2026-09-08T12:00:00-06:00",
  "billable": true
}

Authorizations

x-api-key

string

header

required

Body

application/json

selfie

string

required

Selfie image of the subject in Base64 (PNG/JPG).

allowMultipleFaces

boolean

default:false

Optional. When false (default), a selfie with another person in frame returns MULTIPLE_FACES_DETECTED. When true, the largest face in the image is evaluated and the others are ignored.

Response

Liveness analysis result (Strict Envelope Pattern).

status

enum<string>

required

High-level outcome. OK means the request was successfully processed (regardless of business result). ERROR means the request was rejected or could not be processed.

Available options:

OK,

ERROR

type

string

required

Stable result type code. Includes generic codes (SUCCESS, INVALID_REQUEST, UNAUTHORIZED, SERVICE_UNAVAILABLE, INTERNAL_ERROR, RATE_LIMIT_EXCEEDED) plus endpoint-specific result codes — see this endpoint's response examples.

message

string

required

Human-readable summary of the result. Always in English (per Language Conventions in the API overview).

transactionId

string<uuid>

required

Unique identifier of this request, generated by the API Gateway. Propagated end-to-end for traceability.

processedAt

string<date-time>

required

ISO 8601 datetime with Mexico City offset (-06:00). Always set by the API Gateway when the response leaves the system.

billable

boolean

required

Whether this request will be charged against the client's plan. Typically true for successful business results and false for validation errors or system errors that prevented processing.

data

object | null

Liveness result. Null for INVALID_REQUEST, INTERNAL_ERROR and SERVICE_UNAVAILABLE. On every OK outcome the object is present: when nothing could be evaluated (NO_FACE_DETECTED, MULTIPLE_FACES_DETECTED, IMAGE_UNREADABLE) isLive is false and the remaining fields are null.

Show child attributes

errors

object[]

Per-field error details. Present only on INVALID_REQUEST responses.

Show child attributes

cURL

curl -X POST https://api.origoid.com/global/biometrics/v1/liveness-checks \
  -H "x-api-key: YOUR_API_KEY" \
  -H "content-type: application/json" \
  -d '{"selfie": "<base64 image (JPG or PNG)>"}'

const response = await fetch("https://api.origoid.com/global/biometrics/v1/liveness-checks", {
  method: "POST",
  headers: {
    "x-api-key": process.env.ORIGOID_API_KEY,
    "content-type": "application/json",
  },
  body: JSON.stringify({
    "selfie": "<base64 image (JPG or PNG)>"
  }),
});

if (!response.ok) {
  throw new Error(`HTTP ${response.status}`);
}

const result = await response.json();
console.log(result);

import os
import requests

response = requests.post(
    "https://api.origoid.com/global/biometrics/v1/liveness-checks",
    headers={
        "x-api-key": os.environ["ORIGOID_API_KEY"],
        "content-type": "application/json",
    },
    json={
        "selfie": "<base64 image (JPG or PNG)>"
    },
    timeout=30,
)
response.raise_for_status()
result = response.json()
print(result)

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class Example {
    public static void main(String[] args) throws Exception {
        String payload = "{\"selfie\": \"<base64 image (JPG or PNG)>\"}";

        HttpClient client = HttpClient.newBuilder()
            .connectTimeout(Duration.ofSeconds(10))
            .build();

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.origoid.com/global/biometrics/v1/liveness-checks"))
            .header("x-api-key", System.getenv("ORIGOID_API_KEY"))
            .header("content-type", "application/json")
            .timeout(Duration.ofSeconds(30))
            .POST(HttpRequest.BodyPublishers.ofString(payload))
            .build();

        HttpResponse<String> response = client.send(
            request, HttpResponse.BodyHandlers.ofString()
        );

        System.out.println(response.statusCode());
        System.out.println(response.body());
    }
}

<?php
$payload = '{"selfie": "<base64 image (JPG or PNG)>"}';

$ch = curl_init('https://api.origoid.com/global/biometrics/v1/liveness-checks');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $payload,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTPHEADER => [
        'x-api-key: ' . getenv('ORIGOID_API_KEY'),
        'content-type: application/json',
    ],
]);

$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($status >= 400) {
    throw new Exception("HTTP $status");
}

$result = json_decode($response, true);
print_r($result);

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"log"
	"net/http"
	"os"
	"time"
)

func main() {
	payload := []byte(`{"selfie": "<base64 image (JPG or PNG)>"}`)
	req, err := http.NewRequest("POST", "https://api.origoid.com/global/biometrics/v1/liveness-checks", bytes.NewBuffer(payload))
	if err != nil { log.Fatal(err) }
	req.Header.Set("x-api-key", os.Getenv("ORIGOID_API_KEY"))
	req.Header.Set("content-type", "application/json")

	client := &http.Client{Timeout: 30 * time.Second}
	resp, err := client.Do(req)
	if err != nil { log.Fatal(err) }
	defer resp.Body.Close()

	var result map[string]any
	if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
		log.Fatal(err)
	}
	fmt.Println(result)
}

using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        using var client = new HttpClient { Timeout = TimeSpan.FromSeconds(30) };
        client.DefaultRequestHeaders.Add("x-api-key",
            Environment.GetEnvironmentVariable("ORIGOID_API_KEY"));

        var payload = "{\"selfie\": \"<base64 image (JPG or PNG)>\"}";
        var content = new StringContent(payload, Encoding.UTF8, "application/json");

        var response = await client.PostAsync("https://api.origoid.com/global/biometrics/v1/liveness-checks", content);
        response.EnsureSuccessStatusCode();

        var body = await response.Content.ReadAsStringAsync();
        Console.WriteLine(body);
    }
}

{
  "status": "OK",
  "type": "SUCCESS",
  "message": "Liveness check completed",
  "data": {
    "isLive": true,
    "livenessScore": 98,
    "confidence": "HIGH",
    "selfieAnalysis": {
      "imageQuality": "excellent",
      "detectionConfidence": "high",
      "orientation": "front",
      "eyesOpen": true,
      "mouthOpen": false,
      "wearingGlasses": false,
      "wearingSunglasses": false,
      "faceCovered": false,
      "issues": []
    }
  },
  "transactionId": "f2da936b-4e13-47e9-8696-8f3526cf03fd",
  "processedAt": "2026-09-08T12:00:00-06:00",
  "billable": true
}

Authentication

RENAPO

Social Security

INE

Biometrics

Compliance

Email

Proof of Address

Fiscal

Banking

Liveness Detection

Authorizations

Body

Response