/v1/healthPublicLiveness probe returning process health and API version.
curl https://api.facecore.dev/v1/health{
"request_id": "req_01j9m2x9k1",
"status": "ok",
"version": "1.0.0"
}Reference
Base URL: https://api.facecore.dev. Authenticate requests using Authorization: Bearer <API_KEY>. Every response includes request_id.
/v1/healthPublicLiveness probe returning process health and API version.
curl https://api.facecore.dev/v1/health{
"request_id": "req_01j9m2x9k1",
"status": "ok",
"version": "1.0.0"
}/v1/readyPublicReadiness probe verifying database connectivity and commercial model-license gates.
curl https://api.facecore.dev/v1/ready{
"request_id": "req_01j9m2x9k2",
"ready": true,
"database_ok": true,
"commercial_gate_ok": true,
"violations": []
}/v1/modelsBearer API KeyList active detector, embedder, liveness, quality, and geometry models with license status.
curl https://api.facecore.dev/v1/models \
-H "Authorization: Bearer $FACECORE_KEY"{
"request_id": "req_01j9m2x9k3",
"models": [
{
"model_id": "arcface-r100-v1",
"model_version": "1.2.0",
"kind": "embedder",
"license_id": "Apache-2.0",
"commercial_ok": true,
"status": "active",
"capture_type": "selfie_id",
"preprocessing_version": "pp-v1"
}
]
}/v1/detectBearer API KeyDetect faces, bounding boxes, 5-point landmarks, and optional quality metrics.
| Parameter | In | Type | Description |
|---|---|---|---|
| image* | form | file | JPEG, PNG, or WebP frame. |
| include_quality | form | boolean | Attach quality score, pose_ypr, and reason codes (default true). |
curl https://api.facecore.dev/v1/detect \
-H "Authorization: Bearer $FACECORE_KEY" \
-F image=@frame.jpg \
-F include_quality=true{
"request_id": "req_01j9m2x9k4",
"face_count": 1,
"detector": "scrfd-2.5g",
"faces": [
{
"bbox": [118.4, 84.0, 312.8, 344.2],
"landmarks": [[178.1, 188.0], [254.6, 186.9], [216.2, 232.5], [184.5, 286.1], [249.8, 285.0]],
"score": 0.994,
"quality": {
"score": 84.2,
"reasons": [],
"pose_ypr": [-3.8, 1.4, -0.7],
"interocular_px": 76.5,
"metrics": { "sharpness": 0.91, "brightness": 0.64 }
}
}
]
}/v1/qualityBearer API KeyEvaluate blur, lighting, pose, occlusion, and interocular resolution before matching.
| Parameter | In | Type | Description |
|---|---|---|---|
| image* | form | file | Image containing a single face. |
| target_index | form | integer | Optional face index when multiple faces are present. |
curl https://api.facecore.dev/v1/quality \
-H "Authorization: Bearer $FACECORE_KEY" \
-F image=@selfie.jpg{
"request_id": "req_01j9m2x9k5",
"face_count": 1,
"quality": {
"score": 84.2,
"reasons": [],
"pose_ypr": [-3.8, 1.4, -0.7],
"interocular_px": 76.5,
"metrics": { "sharpness": 0.91, "brightness": 0.64, "occlusion": 0.02 }
}
}/v1/verifyBearer API KeyIdempotent1:1 face verification with quality gating, calibrated thresholds, optional liveness session binding, and full decision audit.
| Parameter | In | Type | Description |
|---|---|---|---|
| image_a* | form | file | Live capture or probe selfie. |
| image_b* | form | file | Reference image or ID document crop. |
| profile | form | string | strict | standard | relaxed (default standard). |
| capture_type | form | string | selfie_selfie | selfie_id | multiview. |
| liveness_session_id | form | string | Optional completed one-time liveness session ID. |
| require_liveness | form | boolean | Force INCONCLUSIVE if liveness verdict is missing. |
| Idempotency-Key | header | string | Safe retry key for 24-hour idempotent replay. |
curl https://api.facecore.dev/v1/verify \
-H "Authorization: Bearer $FACECORE_KEY" \
-H "Idempotency-Key: 9b7c4e10-3a2d-4c8f-8e11-12f34a56b789" \
-F image_a=@selfie.jpg \
-F image_b=@id_photo.jpg \
-F profile=standard \
-F capture_type=selfie_id{
"request_id": "req_01j9m2x9k6",
"decision_id": "dec_01j9m2x9m0",
"decision": "MATCH",
"score": 0.614,
"threshold": 0.452,
"profile": "standard",
"capture_type": "selfie_id",
"quality": {
"a": { "score": 84.2, "reasons": [], "pose_ypr": [-3.8, 1.4, -0.7], "interocular_px": 76.5, "metrics": {} },
"b": { "score": 61.8, "reasons": [], "pose_ypr": [1.2, 0.4, 0.2], "interocular_px": 54.0, "metrics": {} }
},
"liveness": { "verdict": "LIVE", "score": 0.94, "tier": "active", "reasons": [] },
"models": { "detector": "scrfd-2.5g", "embedder": "arcface-r100-v1@1.2.0" },
"policy_version": "p-2026-01",
"reasons": [],
"geometry_source": "not_requested"
}/v1/decisions/{decision_id}Bearer API KeyRetrieve the immutable audit record for a prior verification or identification decision.
| Parameter | In | Type | Description |
|---|---|---|---|
| decision_id* | path | string | Decision ID returned by /v1/verify or /identify. |
curl https://api.facecore.dev/v1/decisions/dec_01j9m2x9m0 \
-H "Authorization: Bearer $FACECORE_KEY"{
"request_id": "req_01j9m2x9k7",
"decision_id": "dec_01j9m2x9m0",
"tenant_id": "tnt_01j9k4m8p2",
"operation": "verify",
"result": "MATCH",
"score": 0.614,
"threshold": 0.452,
"profile": "standard",
"reasons": [],
"model_versions": { "detector": "scrfd-2.5g", "embedder": "arcface-r100-v1@1.2.0" },
"policy_version": "p-2026-01",
"latency_ms": 142,
"decision_request_id": "req_01j9m2x9k6",
"created_at": "2026-11-14T20:14:09Z"
}/v1/liveness/sessionsBearer API KeyIssue a single-use, time-bounded liveness session with cryptographic nonce and randomized challenges.
| Parameter | In | Type | Description |
|---|---|---|---|
| tier | body | string | passive | active | multiview (default active). |
| challenge_count | body | integer | Number of active head/blink prompts (default 2). |
| subject_id | body | string | Optional subject identifier to bind the session. |
curl -X POST https://api.facecore.dev/v1/liveness/sessions \
-H "Authorization: Bearer $FACECORE_KEY" \
-H "Content-Type: application/json" \
-d '{"tier": "active", "challenge_count": 2}'{
"request_id": "req_01j9m2x9k8",
"session_id": "liv_01j9m2x9p1",
"nonce": "n_84c19f0e2b7a",
"challenges": ["turn_left", "blink"],
"expires_at": "2026-11-14T20:19:09Z"
}/v1/liveness/sessions/{session_id}/submitBearer API KeySubmit captured frames and signed HMAC-SHA256 capture manifest to close the one-time liveness session.
| Parameter | In | Type | Description |
|---|---|---|---|
| session_id* | path | string | Session ID from /v1/liveness/sessions. |
| frames* | form | file[] | Ordered frame sequence. |
| manifest_signature* | form | string | HMAC-SHA256 signature over session_id, nonce, frame hashes, and timestamps. |
curl -X POST https://api.facecore.dev/v1/liveness/sessions/liv_01j9m2x9p1/submit \
-H "Authorization: Bearer $FACECORE_KEY" \
-F frames=@frame_1.jpg \
-F frames=@frame_2.jpg \
-F manifest_signature="$SIGNATURE"{
"request_id": "req_01j9m2x9k9",
"session_id": "liv_01j9m2x9p1",
"verdict": "LIVE",
"score": 0.942,
"tier": "active",
"reasons": []
}/v1/multiview/analyzeBearer API KeyVerify left, centre, and right captures behave like a coherent 3D head rather than a tilted flat photo.
| Parameter | In | Type | Description |
|---|---|---|---|
| views* | form | file[] | Ordered left, centre, and right captures (3+ views). |
| reference_image | form | file | Optional reference image to simultaneously run 1:1 verification. |
curl -X POST https://api.facecore.dev/v1/multiview/analyze \
-H "Authorization: Bearer $FACECORE_KEY" \
-F views=@left.jpg \
-F views=@centre.jpg \
-F views=@right.jpg{
"request_id": "req_01j9m2x9ka",
"passed": true,
"multiview_score": 0.91,
"checks": {
"pose_progressive": true,
"shape_consistent": true,
"identity_consistent": true
},
"reasons": [],
"geometry_source": "estimated_3d",
"view_yaws": [-21.4, -1.2, 23.1]
}/v1/consentsBearer API KeyRecord explicit subject consent before enrolling a template into any gallery.
| Parameter | In | Type | Description |
|---|---|---|---|
| purpose* | body | string | Declared biometric processing purpose. |
| policy_version | body | string | Policy version accepted by the user (default p-2026-01). |
| evidence_ref | body | string | Opaque reference to your signed consent artifact. |
curl -X POST https://api.facecore.dev/v1/consents \
-H "Authorization: Bearer $FACECORE_KEY" \
-H "Content-Type: application/json" \
-d '{"purpose": "account_verification", "policy_version": "p-2026-01", "evidence_ref": "chk_4819"}'{
"request_id": "req_01j9m2x9kb",
"consent_id": "cns_01j9m2x9q4",
"purpose": "account_verification",
"policy_version": "p-2026-01",
"granted_at": "2026-11-14T20:15:12Z"
}/v1/galleriesBearer API KeyCreate a tenant-isolated gallery with optional template retention limits.
| Parameter | In | Type | Description |
|---|---|---|---|
| name* | body | string | Human-readable gallery name. |
| purpose | body | string | Purpose label (default verification). |
| retention_days | body | integer | Optional TTL in days (>= 1). |
curl -X POST https://api.facecore.dev/v1/galleries \
-H "Authorization: Bearer $FACECORE_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "staff-access-lagos", "purpose": "verification", "retention_days": 365}'{
"request_id": "req_01j9m2x9kc",
"gallery_id": "gal_01j9m2x9r7",
"name": "staff-access-lagos",
"purpose": "verification",
"retention_days": 365
}/v1/galleries/{gallery_id}/subjectsBearer API KeyIdempotentEnroll a consented subject into a gallery and store an encrypted embedding template.
| Parameter | In | Type | Description |
|---|---|---|---|
| gallery_id* | path | string | Target gallery ID. |
| consent_id* | form | string | Active consent ID from POST /v1/consents. |
| images* | form | file[] | 1+ clear facial samples. |
curl -X POST https://api.facecore.dev/v1/galleries/gal_01j9m2x9r7/subjects \
-H "Authorization: Bearer $FACECORE_KEY" \
-F consent_id=cns_01j9m2x9q4 \
-F images=@enrol_1.jpg{
"request_id": "req_01j9m2x9kd",
"subject_id": "sub_01j9m2x9s2",
"gallery_id": "gal_01j9m2x9r7",
"consent_id": "cns_01j9m2x9q4",
"template_id": "tpl_01j9m2x9t8",
"model_id": "arcface-r100-v1",
"model_version": "1.2.0",
"quality": 88.4,
"sample_count": 1
}/v1/galleries/{gallery_id}/identifyBearer API Key1:N search against a single tenant-isolated gallery with calibrated threshold and margin gap checks.
| Parameter | In | Type | Description |
|---|---|---|---|
| gallery_id* | path | string | Gallery ID to search. |
| image* | form | file | Probe face image. |
| profile | form | string | strict | standard | relaxed. |
curl -X POST https://api.facecore.dev/v1/galleries/gal_01j9m2x9r7/identify \
-H "Authorization: Bearer $FACECORE_KEY" \
-F image=@probe.jpg \
-F profile=standard{
"request_id": "req_01j9m2x9ke",
"decision_id": "dec_01j9m2x9u1",
"decision": "MATCH",
"candidates": [
{ "subject_id": "sub_01j9m2x9s2", "template_id": "tpl_01j9m2x9t8", "score": 0.728 }
],
"threshold": 0.452,
"margin": 0.312,
"models": { "embedder": "arcface-r100-v1@1.2.0" },
"policy_version": "p-2026-01",
"reasons": []
}/v1/subjects/{subject_id}Bearer API KeyPermanently delete a subject's templates from the database and vector index while preserving audit metadata.
| Parameter | In | Type | Description |
|---|---|---|---|
| subject_id* | path | string | Subject ID to erase. |
curl -X DELETE https://api.facecore.dev/v1/subjects/sub_01j9m2x9s2 \
-H "Authorization: Bearer $FACECORE_KEY"{
"request_id": "req_01j9m2x9kf",
"subject_id": "sub_01j9m2x9s2",
"deleted": true,
"index_entries_removed": 1
}