Documentation

Identity Verification APIs

This documentation covers both DMS Workspace APIs: IDScan for document recognition and LiveCheck for face liveness and biometric matching. Both are available over HTTPS. IDScan is served under /idcard_recognition_v2 and LiveCheck under /v1/livecheck.

Authentication

All requests require a Bearer token in the Authorization header. Obtain your API key from the dashboard after signup. Never expose your key in client-side code — proxy requests through your backend.

Header format

Authorization: Bearer YOUR_API_KEY

Base URLs

IDScan

https://api.dmsworkspace.com/idcard_recognition_v2

LiveCheck

https://api.dmsworkspace.com/v1/livecheck

Error responses

400Bad request — missing or invalid parameters

401Unauthorized — missing or invalid API key

402Payment required — scan quota exceeded

422Unprocessable — no document or face detected in image

500Internal server error — contact support

IDScan — Document Recognition

Extracts structured fields from identity documents using a four-stage pipeline: detection → classification → extraction → enrichment. Supports ID cards, passports, and driving licences across 50+ countries. Every response includes all key fields, the portrait photo, and a fraud assessment.

Pipeline overview

Detect & Rectify

YOLOv8-nano locates and crops the document
Perspective correction and orientation normalisation

Classify

MobileNetV3-Large identifies country and document type
Selects the appropriate field extraction template

Extract Fields

Template-based crop-OCR per country
LayoutLMv3 token classification (fine-tuned on 13k documents)
EU driving licence numbered-field extractor
PaddleOCR 3.x full-image fallback

Enrich & Validate

ICAO 9303 MRZ parser (highest merge priority)
Barcode decode — PDF417 and QR
Portrait crop via InsightFace
Fraud / specimen watermark checks
Field validators and normalisation

Merge priority (highest wins): MRZ › EU DL extractor › LayoutLMv3 › Template OCR › Classifier metadata

Endpoints

Method	Path	Description
POST	/idcard_recognition	Multipart file upload
POST	/idcard_recognition_base64	Base64 JSON — single side
POST	/idcard_recognition_base64_multi_page	Base64 JSON — two-sided document
GET	/health	Readiness probe

Response fields

Field	Description
DocumentType	DRIVING_LICENSE, PASSPORT, NATIONAL_ID, etc.
IssuingCountry	ISO 3166-1 alpha-3 country code
Surname	Family name extracted from the document
GivenNames	Given names extracted from the document
DateOfBirth	ISO 8601 date (YYYY-MM-DD)
DateOfExpiry	ISO 8601 date (YYYY-MM-DD)
DocumentNumber	Document identifier number
Sex	M, F, or X
Nationality	ISO 3166-1 alpha-3 nationality code
Portrait	Base64-encoded face crop from the document
OcrProvider	V2_TEMPLATE \| PADDLE_OCR \| OPEN_AI
FraudCheck.Result	GENUINE or SUSPICIOUS

Sample response

{
  "DocumentType": "DRIVING_LICENSE",
  "IssuingCountry": "ESP",
  "Surname": "GARCIA LOPEZ",
  "GivenNames": "CARLOS",
  "DateOfBirth": "1990-06-15",
  "DateOfExpiry": "2028-06-15",
  "DocumentNumber": "B12345678",
  "Sex": "M",
  "Nationality": "ESP",
  "Portrait": "<base64-encoded-face-crop>",
  "OcrProvider": "V2_TEMPLATE",
  "FraudCheck": {
    "Result": "GENUINE",
    "Checks": ["NO_SPECIMEN_WATERMARK", "NO_SCREEN_CAPTURE"]
  }
}

LiveCheck — Face Recognition & Liveness

Analyses faces for passive liveness, biometric matching, quality, and pose. The face_detection endpoint returns a liveness verdict, quality scores, 3D head pose, eye/mouth state, occlusion coverage, 68-point landmarks, and a 2048-byte biometric template — all in one call.

Endpoints

Method	Path	Description
POST	/face_detection	Detect, analyse & liveness check
POST	/template_extraction	Extract 2048-byte biometric template
POST	/face_verify	1:1 similarity from two templates
GET	/health	Readiness probe

Response fields — face_detection

Field	Type	Description
liveness	string	GENUINE or SPOOF — passive anti-spoofing verdict
quality	float	Face quality score 0–1. Reject below 0.5 in production.
luminance	float	Illumination score 0–1. Low values indicate poor lighting.
eye_distance	float	Inter-ocular distance in pixels.
pose.yaw	float	Horizontal head rotation in degrees.
pose.roll	float	Head tilt in degrees.
pose.pitch	float	Vertical head rotation in degrees.
eye_state	object	left_closed / right_closed — float 0–1 where 1 = fully closed.
mouth_opened	float	Mouth openness 0–1.
occlusion	float	Fraction of face area occluded.
bbox	int[4]	Bounding box [x1, y1, x2, y2] in pixels.
landmarks_68	float[]	68 × (x, y) facial landmark coordinates.
template	string	2048-byte biometric vector for 1:1 matching.

face_detection response

{
  "face_count": 1,
  "faces": [
    {
      "liveness": "GENUINE",
      "quality": 0.94,
      "luminance": 0.87,
      "eye_distance": 142.3,
      "pose": {
        "yaw": 1.8,
        "roll": -0.4,
        "pitch": 2.1
      },
      "eye_state": {
        "left_closed": 0.02,
        "right_closed": 0.03
      },
      "mouth_opened": 0.12,
      "occlusion": 0.01,
      "bbox": [120, 80, 380, 420],
      "landmarks_68": [[x1,y1], [x2,y2], "..."],
      "template": "<2048-byte-biometric-vector>"
    }
  ]
}

face_verify response

{
  "similarity": 0.9342,
  "match": true,
  "threshold": 0.82
}

Integration Examples

Code examples for every major language and framework. Always proxy API calls through your backend — never include your API key in client-side code.

IDScan — code examples

curl -X POST https://api.dmsworkspace.com/idcard_recognition \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@id_card.jpg"

LiveCheck — code examples

# Liveness + face analysis
curl -X POST https://api.dmsworkspace.com/face_detection \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "image=@selfie.jpg"

# 1:1 face verification
curl -X POST https://api.dmsworkspace.com/face_verify \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"template_a":"<vector>","template_b":"<vector>"}'

Benchmarks — IDScan Field Accuracy

Evaluated on a 428-image set. 100% JSON coverage — every image returns a structured response. Strongest on EU and Latin-script documents. Non-Latin scripts (CJK, Arabic) use MRZ-only extraction; native-script OCR is on the product roadmap.

Field	Exact match	Lenient match
Document Name	84.0%	84.7%
Sex	69.5%	69.5%
Date of Birth	65.8%	67.8%
Date of Expiry	59.5%	60.4%
Given Names	54.1%	56.9%
Surname	49.7%	54.3%
Document Number	42.2%	47.2%

Exact: character-for-character equality after normalisation. Lenient: allows common OCR substitutions (0/O, 1/I, etc.).