API Reference

Version 2.0.0 · Base URL http://erp.sd

The Digitalize Lab API provides face recognition and liveness detection capabilities via a simple REST interface. All endpoints accept multipart/form-data (file upload) or application/json (Base64 encoded) requests and return JSON responses.

All image inputs support JPEG, PNG, BMP, and WebP formats. Maximum recommended image size is 5MB.

Authentication

All API endpoints require a valid token passed in the X-API-Token header (or as a Bearer token in Authorization). Contact the admin to obtain a token.

Header
X-API-Token: <your-token>

Alternative — Bearer
Authorization: Bearer <your-token>

Error responses

401 — Missing or invalid token
{
  "status": "error",
  "message": "Missing API token. Pass X-API-Token header."
}

429 — Rate limit exceeded
{
  "status": "error",
  "message": "Rate limit exceeded: 60 requests/minute"
}

403 — Token disabled or expired
{
  "status": "error",
  "message": "API token is disabled."
}

Error Handling

All responses use HTTP 200 with a JSON body. Check the data.result field for error messages when image loading fails.

Error response example
{
  "status": "ok",
  "data": {
    "result": "Failed to open image1",
    "image1": {},
    "image2": {}
  }
}

Compare Face

POST /api/compare_face multipart/form-data

Compares two face images and returns whether they belong to the same person, along with a similarity score and face bounding boxes.

Request — Form Fields

Field	Type	Required	Description
image1	file	required	First face image
image2	file	required	Second face image to compare against

cURL

curl -X POST http://erp.sd/api/compare_face \
  -F "image1=@/path/to/face1.jpg" \
  -F "image2=@/path/to/face2.jpg"

Python

import requests

with open('face1.jpg', 'rb') as f1, open('face2.jpg', 'rb') as f2:
    resp = requests.post(
        'http://erp.sd/api/compare_face',
        files={'image1': f1, 'image2': f2}
    )
print(resp.json())

Response Fields

data.resultstring"matched" | "not matched" | error message
data.similarityfloatCosine similarity score, 0.0–1.0. Threshold: 0.67
data.image1.detectionobjectBounding box {x, y, width, height} of face in image1
data.image2.detectionobjectBounding box {x, y, width, height} of face in image2
data.image1.featurestring512-dimensional face embedding vector (JSON array)

Response example

{
  "status": "ok",
  "data": {
    "result": "matched",
    "similarity": 0.872,
    "image1": {
      "detection": { "x": 102, "y": 45, "width": 180, "height": 210 },
      "feature": "[0.023, -0.145, ...]"
    },
    "image2": {
      "detection": { "x": 88, "y": 52, "width": 175, "height": 205 },
      "feature": "[0.019, -0.138, ...]"
    }
  }
}

Compare Face — Base64

POST /api/compare_face_base64 application/json

Same as /api/compare_face but accepts Base64-encoded images in a JSON body. Useful for mobile apps and web clients.

Request Body

Field	Type	Required	Description
image1	string	required	Base64-encoded image (no data URI prefix)
image2	string	required	Base64-encoded image (no data URI prefix)

cURL

curl -X POST http://erp.sd/api/compare_face_base64 \
  -H "Content-Type: application/json" \
  -d '{
    "image1": "'$(base64 -i face1.jpg)'",
    "image2": "'$(base64 -i face2.jpg)'"
  }'

Python

import requests, base64

def to_b64(path):
    with open(path, 'rb') as f:
        return base64.b64encode(f.read()).decode()

resp = requests.post(
    'http://erp.sd/api/compare_face_base64',
    json={'image1': to_b64('face1.jpg'), 'image2': to_b64('face2.jpg')}
)
print(resp.json())

Response format is identical to /api/compare_face.

Check Liveness

POST /api/check_liveness multipart/form-data

Determines whether a face in an image is from a real live person or a spoof attempt (printed photo, screen replay, mask).

Request — Form Fields

Field	Type	Required	Description
image	file	required	Face image to check

cURL

curl -X POST http://erp.sd/api/check_liveness \
  -F "image=@/path/to/face.jpg"

Python

import requests

with open('face.jpg', 'rb') as f:
    resp = requests.post(
        'http://erp.sd/api/check_liveness',
        files={'image': f}
    )
print(resp.json())

Response Fields

data.resultstring"real" | "spoof" | error message
data.liveness_scorefloatScore 0.0–1.0. Above 0.5 = real. Below = spoof
data.face_rectobjectFace bounding box {x, y, w, h}
data.angles.yawfloatHead yaw angle in degrees
data.angles.rollfloatHead roll angle in degrees
data.angles.pitchfloatHead pitch angle in degrees

Response example

{
  "status": "ok",
  "data": {
    "result": "real",
    "liveness_score": 0.812,
    "face_rect": { "x": 95, "y": 42, "w": 182, "h": 215 },
    "angles": { "yaw": -4.2, "roll": 1.1, "pitch": -8.5 }
  }
}

Check Liveness — Base64

POST /api/check_liveness_base64 application/json

Same as /api/check_liveness but accepts a Base64-encoded image in a JSON body.

Request Body

Field	Type	Required	Description
image	string	required	Base64-encoded image

cURL

curl -X POST http://erp.sd/api/check_liveness_base64 \
  -H "Content-Type: application/json" \
  -d '{"image": "'$(base64 -i face.jpg)'"}'

Response format is identical to /api/check_liveness.

Verify Document

POST /api/verify_document multipart/form-data

Processes an ID document image and extracts all available information: structured fields, MRZ data, barcodes, and the holder's portrait photo.

Supports 14,000+ document types from 250+ countries including national ID cards, passports, driver licenses, and residence permits.

Request — Form Fields

Field	Type	Required	Description
image	file	required	Document image (flat scan or photo)

cURL

curl -X POST http://erp.sd/api/verify_document \
  -F "image=@/path/to/id_card.jpg"

Python

import requests

with open('id_card.jpg', 'rb') as f:
    resp = requests.post(
        'http://erp.sd/api/verify_document',
        files={'image': f}
    )
print(resp.json())

Response Fields

data.errorCodeint0 = success; non-zero = processing error
data.documentNamestringDetected document type, e.g. "France - Id Card (2021)"
data.scorefloatDetection confidence 0.0–1.0
data.image.documentFrontSidestringBase64-encoded JPEG of the annotated document
data.image.portraitstringBase64-encoded JPEG of the extracted holder portrait
data.mrzobjectParsed MRZ data — see sub-fields below
data.mrz.namestringFull name
data.mrz.surnamestringSurname / family name
data.mrz.givenNamesstringGiven names
data.mrz.documentNumberstringDocument number
data.mrz.documentClassCodestringDocument class, e.g. "PC" (passport), "ID"
data.mrz.dateOfBirthstringDate of birth (YYYY-MM-DD)
data.mrz.dateOfExpirystringExpiry date (YYYY-MM-DD)
data.mrz.nationalitystringNationality (full name)
data.mrz.issuingStateCodestring3-letter issuing country code (ISO 3166-1 alpha-3)
data.mrz.sexstring"M" | "F"
data.mrz.mrzCodestringRaw MRZ lines joined with "^"
data.mrz.validStateintMRZ checksum validity: 1 = valid
data.ocrobjectVisual OCR fields (name, surname, dateOfBirth, etc.) — present for ID cards with VIZ zone
data.barcodeobjectBarcode/PDF417 parsed fields — present when barcode is found
data.portrait_rectobjectPortrait bounding box in original image {top, left, right, bottom}
data.positionobjectDocument bounding box in original image {top, left, right, bottom}

Response example

{
  "status": "ok",
  "data": {
    "errorCode": 0,
    "documentName": "Sudan - Passport",
    "score": 0.97,
    "image": {
      "documentFrontSide": "/9j/4AAQSkZJRgAB...",
      "portrait": "/9j/4AAQSkZJRgAB..."
    },
    "mrz": {
      "name": "ABDALRAHMAN KAMAL MOUSA MOLOOD",
      "surname": "ABDALRAHMAN KAMAL MOUSA",
      "givenNames": "MOLOOD",
      "documentNumber": "B98765432",
      "documentClassCode": "PC",
      "dateOfBirth": "1992-07-14",
      "dateOfExpiry": "2031-09-10",
      "nationality": "Sudan",
      "issuingStateCode": "SDN",
      "sex": "M",
      "mrzCode": "PCSDNABDALRAHMAN<KAMAL<MOUSA<<MOLOOD<<<<<<<^B9876543...",
      "validState": 1
    },
    "portrait_rect": { "top": 226, "left": 62, "right": 404, "bottom": 713 },
    "position":      { "top": 280, "left": 334, "right": 2129, "bottom": 1511 }
  }
}

Verify Document — Base64

POST /api/verify_document_base64 application/json

Same as /api/verify_document but accepts a Base64-encoded image in a JSON body.

Request Body

Field	Type	Required	Description
image	string	required	Base64-encoded document image

cURL

curl -X POST http://erp.sd/api/verify_document_base64 \
  -H "Content-Type: application/json" \
  -d '{"image": "'$(base64 -i id_card.jpg)'"}'

Response format is identical to /api/verify_document.

Health Check

GET /health System status

Returns the current system status and engine version.

cURL

curl http://erp.sd/health

Response

{
  "status": "ok",
  "version": "2.0.0"
}

Changelog

v2.0.0 Latest April 2026

Added — Passive liveness detection endpoint (POST /api/check_liveness) with neural-network anti-spoofing. Returns liveness score, bounding box, and head-pose angles (yaw / roll / pitch).
Added — Base64 variants for all endpoints (/api/compare_face_base64, /api/check_liveness_base64, /api/verify_document_base64) for browser and mobile clients.
Added — ID Document Verification (POST /api/verify_document) supporting 14,000+ document types with full MRZ parsing, portrait extraction, barcode decoding, and structured field output.
Added — GET /health endpoint returning engine status and version.
Improved — Face comparison now returns per-image detection bounding boxes and a 512-dimensional feature vector alongside the similarity score.
Improved — All API errors return structured JSON ({"status":"error","message":"..."}) — no HTML error pages.
Changed — Similarity threshold raised to 0.67 (from 0.60 in v1.x) for lower false-accept rate.

v1.x Prior releases

Foundation — Face comparison API (POST /api/compare_face) with cosine similarity scoring and bounding-box detection.
Foundation — Token-based authentication and per-key rate limiting.