PhotoCheck API Explorer

API Reference

REST API for photo compliance validation.

Compliance

POST /api/v1/compliance/check Run photo compliance check

Docs

Try it

Authentication

Authorization: Bearer <api_key>
Content-Type: application/json

Request body

Field	Type	Required	Description
`image_base64`	string	required	Base64-encoded JPG or PNG, up to 25MB. Send the photo as the camera took it: the server frames and compresses it once itself.
`media_type`	string	optional	image/jpeg or image/png (default: image/jpeg). The server measures the photo's size and shape itself.
`applicant_id`	string	optional	Your reference for the person, up to 256 characters. Returned in the response, saved on the audit record, shown on the dashboard, and sent with identity match webhooks. Use an internal reference rather than a licence number.
`session_id`	string	optional	Your ID for this check, up to 256 characters. It becomes the record's `request_id`. Retakes can share one. If left out, the server makes one.
`filename`	string	optional	Shown on the dashboard, up to 256 characters.
`return_processed`	boolean	optional	`true` to get the stored photo back in the response as `processed`: framed on the face like a passport photo, 1200 × 1600, 300 DPI, about 155KB. The phone SDKs ask for it, to show on their result screen.

Example response

{
  "request_id": "b7f3c1e2-4d5a-4c2b-9e1f-2a6c8d9e0f13",
  "applicant_id": "CASE-004812",
  "overall": "WARN",
  "score": 95,
  "summary": "This photo can be used, but it could be better. There is a faint shadow on the wall behind you.",
  "checks": [
    { "label": "File size",   "status": "PASS", "source": "local", "note": null, "conf": null, "meta": "212KB" },
    { "label": "Resolution",  "status": "PASS", "source": "local", "note": null, "conf": null, "meta": "1200×1600px" },
    { "label": "No glasses",  "status": "PASS", "source": "rekognition", "note": null, "conf": 99, "code": null },
    { "label": "Direct gaze", "status": "PASS", "source": "rekognition", "note": null, "conf": 92, "meta": "Yaw 3°, Pitch -2°", "code": null },
    { "label": "Background",  "status": "WARN", "note": "There is a faint shadow on the wall behind you." }
  ],
  "duration_ms": 2341
}

Response fields

Field	Meaning
`request_id`	This check's ID: your `session_id`, or one the server made. Always present. Keep it to find the check on the dashboard.
`applicant_id`	Your `applicant_id`, only present if you sent one.
`overall`	`PASS`, `WARN` (usable, with minor issues) or `FAIL`. Any single FAIL check makes the result FAIL.
`score`	0 to 100. Starts at 100, less 15 for each FAIL check and 5 for each WARN.
`summary`	Plain sentences for the person, safe to show as they are. For a WARN or FAIL it opens with the result, says what to fix (for example "remove your glasses and look straight into the camera lens") and adds anything the photo checks found. Never a list of check names.
`checks`	Every check made. Each has `label`, `status` (PASS, WARN or FAIL) and `note` (the reason, or null for a PASS). Some also have `source` (`local` for size checks, `rekognition` for face checks), `conf` (confidence, 0 to 100), `meta` (the measured value: the size for size checks, the angles for Direct gaze and Head position, for staff and troubleshooting), and `code`, a fixed code for certain problems: `GLASSES_DETECTED`, `SUNGLASSES_DETECTED`, `SMILE_DETECTED`, `MOUTH_OPEN`, `EYES_CLOSED`, `GAZE_OFFCENTER`, `RESOLUTION_TOO_LOW`, `WRONG_ASPECT_RATIO`, and `CHECK_UNAVAILABLE` when part of the assessment could not run (reported as a WARN asking the person to try again, so a photo never passes with checks missing).
`processed`	Only when you sent `return_processed: true`. The stored photo: `base64` (JPEG), `sizeKB`, `width`, `height` and `framing` (`face`, or `centre` if no face was found).
`duration_ms`	How long the check took on the server.

A photo that is far too small, or nowhere near portrait shape, fails on the size checks alone, and the face and photo checks are skipped.

Try it

API Key

Applicant ID (optional)

Session ID (optional)

Photo (JPG or PNG)

Drop photo here or click to browse

Short-lived tokens

POST/api/auth/tokenGet a token for one compliance check

For a backend (for example a BFF) that hands tokens to an app, so the app never holds a long-lived API key. Send a client ID and secret set up in the server's CLIENT_CREDENTIALS; no API key is needed for this call.

POST /api/auth/token
Content-Type: application/json

{ "client_id": "bff", "client_secret": "..." }

200 { "token": "...", "expires_in": 300, "token_type": "Bearer" }

Use the token as Authorization: Bearer <token> on one compliance check. Each token works once and lasts TOKEN_TTL_SECS (5 minutes by default). A wrong client ID or secret gets 401.

HTTP Status Codes

Code	Meaning
`200`	Success: result may be PASS, WARN or FAIL
`400`	Bad request: missing `image_base64`, or an ID longer than 256 characters
`401`	Unauthorised: invalid or missing API key
`429`	Compliance check only: more than 120 requests a minute from one IP address
`500`	Server error

API Key

Enter your API key to authenticate requests from this browser. Saved locally and never sent to any third party.

API Key

Compliance Prompt

GET/api/promptView active prompt

Docs

Try it

Returns the active prompt and where it came from: saved (saved through the API), file (the prompt file deployed with the server), env (the COMPLIANCE_PROMPT setting) or default (a short built-in prompt). The first of these that exists is used.

POST/api/promptUpdate compliance prompt

Docs

Try it

Saves a new prompt, which then takes priority over the prompt file. This server uses it straight away; other servers pick it up within a minute (PROMPT_REFRESH_SECONDS). No restart needed. Requires API key.

New Prompt

DEL /api/promptReset to default

Docs

Try it

Removes the saved prompt, so the server goes back to the prompt file deployed with it. Requires API key.

Internal (UI Endpoints)

POST/api/internal/face-analysisFace detection and attribute analysis

Docs

Try it

Used internally by the UI. Analyses face attributes: expression, pose, eye state, glasses, and image quality metrics.

Field	Type	Description
`imageBase64`	string	Base64-encoded image

Photo (JPG or PNG)

Drop photo here or click to browse

POST/api/internal/photo-analysisPhoto compliance image analysis

Docs

Try it

Used internally by the UI. Analyses photo compliance: background, lighting, head coverings, clothing contrast, and image quality.

Field	Type	Description
`imageBase64`	string	Base64-encoded image
`mediaType`	string	image/jpeg or image/png

Photo (JPG or PNG)

Drop photo here or click to browse

Audit Log

Clear all audit log entries. This action is irreversible.

DEL /api/audit Clear all audit log entries

Docs

Try it

Permanently deletes all audit log entries. Requires API key. The compliance prompt record is preserved.

⚠ This will permanently delete all audit entries and cannot be undone.

Audit

GET /api/audit Audit log entries

Docs

Try it

Query param	Type	Description
`limit`	integer	Checks per page (default 50, max 1000)
`page`	integer	Page number, starting at 1 (default 1). A page past the end returns the last page.
`filter`	string	PASS, FAIL, or WARN
`from`	integer	Start time in milliseconds since 1970 (included). Leave out for no start.
`to`	integer	End time in milliseconds since 1970 (not included). Leave out for no end.

Newest first. With no from or to, all dates are included. counts gives the number of checks of each result in the date range, before filter is applied.

GET /api/audit?from=1791550800000&to=1791637200000&page=2&limit=50&filter=FAIL

{
  "entries": [ ... ],
  "total": 123,
  "page": 2,
  "pages": 3,
  "limit": 50,
  "counts": { "all": 123, "PASS": 41, "FAIL": 41, "WARN": 41 }
}

Try it

Limit

Page

Date (blank for all)

Filter

GET /api/audit/stats Aggregate statistics

Docs

Try it

{ "total": 1247, "pass": 891, "fail": 312, "warn": 44,
  "pass_rate": 71, "avg_duration_ms": 2340,
  "top_fail_reasons": [...], "volume_by_hour": {...} }

Try it

API Keys

GET /api/keys List configured API keys (masked)

Docs

Try it

{ "count": 2, "keys": ["pc_a1b2c3d4...ef12", "pc_9z8y7x6w...ab34"] }

Try it

POST /api/keys/generate Generate a new API key

Docs

Try it

{ "ok": true, "key": "pc_a1b2c3d4e5f6..." }

Keys are stored in server memory. Set the API_KEYS environment variable to persist across restarts.