PowerCred KYC — Enterprise API Docs

🧩

Overview

The Enterprise APIs provide a full-stack KYC pipeline with persistent session storage. Every document submission creates a session that tracks OCR results, fraud signals, verification status, and selfie comparisons in one place — reviewable from the dashboard at any time.

🔍

One Call, Full Pipeline

POST /id/analyze runs OCR and triggers government verification in the background — you get the OCR results immediately, verification updates the session asynchronously.

Supports 7 Philippine ID types
File upload or URL input
Verification runs in background

📊

Session-Backed

Every API call links to a session. Sessions persist all results — OCR, quality, fraud, selfie — and are retrievable, filterable, and auditable via the dashboard.

Full revision history on every edit
Fraud status workflow (In Review → Verified / Fraud)
Manual OCR correction with audit trail

🎥

Liveness Video

Stream base64-encoded video frames from the client to build a liveness recording. The assembled video is stored and retrievable per session for manual review.

Frame-by-frame streaming
Configurable FPS and duration
Signed URL retrieval

🔔

Journey Callbacks

Register a webhook on a session and PowerCred fires it automatically when all pipeline steps (OCR, verification, selfie, fraud) are complete.

Fires immediately if already complete
Stores delivery status per session
Retries on failure

🔐

Authentication

All enterprise endpoints require an API key. Pass it as the apikey query parameter on every request.

🔑

API Key (Query Parameter)

Append ?apikey=YOUR_API_KEY to every request URL. The same API key works for both enterprise and SI APIs.

POST https://dev.powercred.io/kyc/id/analyze?user_id=user123&document_type=PH_DRIVING_LICENSE&apikey=YOUR_API_KEY

🌐

Rate Limits & Quotas

API key validation, rate limiting, and quota enforcement are handled automatically. If you receive a 429, you have exceeded your plan's request rate. Contact support to review your limits.

🌐

Base URLs

Environment	Base URL	Notes
Sandbox	https://mock.powercred.io/kyc	For integration and testing.
Production	https://dev.powercred.io/kyc	Contact PowerCred to provision production access.

ℹ️ All endpoint paths below are relative to the base URL. Example: POST https://dev.powercred.io/kyc/id/analyze?apikey=YOUR_KEY&user_id=u123&document_type=PH_DRIVING_LICENSE

🗺️

Endpoint Map

All enterprise endpoints grouped by function.

🔄

Pipeline

Submission & analysis

POST /id/analyze

POST /id/analyze/quality

POST /id/analyze/quality/body

POST /id/fraud-detection

POST /id/selfie

POST /id/record-video-frames

GET /id/liveness/{user_id}

📋

Session Management

CRUD & audit trail

GET /id/sessions

GET /id/session/{id}

PUT /id/session/{id}

GET /id/session/{id}/history

PUT /id/session/{id}/fraud-status

GET /id/session/{id}/get-session-video

DELETE /id/session/{id}/delete-session

🛠️

Operations

Corrections & callbacks

PUT /id/update

PUT /id/sessions/{id}/rerun-verification

POST /id/session/{id}/callback

📄

Supported Doc Types

Philippine government IDs

PH_DRIVING_LICENSE

PH_PASSPORT

PH_NATIONAL_ID

PH_UMID

PH_SSS_ID

PH_PRC_ID

PH_TIN

🔄

KYC Flow

A complete KYC journey — from document submission to a reviewable session. Each step is optional; call only what your product requires.

1

Submit Document

Upload ID images (file upload or URL). OCR extracts structured fields. Government verification starts in the background and updates the session when complete.

POST /id/analyze

2

Check Image Quality

Assess brightness, blur, and DPI before or after OCR. Pass the session_id from step 1 to link results to the same session.

POST /id/analyze/quality

3

Run Fraud Detection

Analyze the document image for tampering, screenshot artifacts, photocopy signs, and photo substitution. Link to session via session_id.

POST /id/fraud-detection

4

Compare Selfie

Submit the applicant's selfie. PowerCred fetches the face cropped from the document in step 1 automatically and returns a match score.

POST /id/selfie

5

Review & Decide

The completed session is visible in the dashboard. Analysts can update fraud status (Verified, Fraud, In Review), correct OCR fields, and view the full revision history.

PUT /id/session/{id}/fraud-status · PUT /id/update

Sequence diagram — Full Enterprise KYC Pipeline

sequenceDiagram participant App as Client Application participant PC as PowerCred API App->>PC: POST /id/analyze
{ user_id, document_type, files } PC-->>App: { id (session_id), ocr_results, ... } Note over PC: Government verification
runs in background App->>PC: POST /id/analyze/quality
?session_id=...&user_id=...&document_type=... PC-->>App: { passed, sides: { brightness, blur, dpi } } App->>PC: POST /id/fraud-detection
?session_id=...&user_id=...&document_type=... PC-->>App: { is_tampered, risk, checks } App->>PC: POST /id/selfie
?session_id=...&user_id=...&document_type=... PC-->>App: { matched, score, is_deepfake } Note over PC: Session now has OCR + quality
+ fraud + selfie results App->>PC: GET /id/session/{id} PC-->>App: { complete session data }

💡 All four pipeline endpoints accept the same ?session_id= query parameter. If omitted, each endpoint automatically finds the most recent session for that user_id + document_type combination.

🔍

Analyze — OCR Pipeline

The main pipeline endpoint. Submits document images, runs OCR, creates a session, and triggers government verification in the background.

POST /id/analyze multipart/form-data or file_urls

Query Parameters

Parameter	Type	Required	Description
user_id	string	required	Your internal identifier for the applicant.
document_type	string	required	One of: `PH_DRIVING_LICENSE`, `PH_PASSPORT`, `PH_NATIONAL_ID`, `PH_UMID`, `PH_SSS_ID`, `PH_PRC_ID`, `PH_TIN`
verify	boolean	optional	Whether to trigger government verification in the background. Default: `true`.
batch_id	string	optional	Group multiple sessions under a shared batch identifier for reporting.

File Input — Option A: Multipart Upload

Field	Type	Required	Description
files	file[]	required*	One or two image files (front + back). Name the back image with "back" in the filename. Accepted: JPEG, PNG, PDF.

File Input — Option B: URL Array

Parameter	Type	Required	Description
file_urls	string[]	required*	Array of signed or public image URLs (max 10). Pass as repeated query params: `?file_urls=url1&file_urls=url2`

⚠️ Provide either files (multipart) or file_urls (query), not both. Front image must come before back — a back-only upload returns HTTP 422.

JSON Response 200

{
  "id":               "session-uuid",          // use as session_id in subsequent calls
  "user_id":          "user123",
  "document_type":    "PH_DRIVING_LICENSE",
  "data": {
    "PH_DRIVING_LICENSE": [
      {
        "personal_information": {
          "lastName":    "DELA CRUZ",
          "givenName":   "JUAN",
          "dob":         "1990-01-15",
          "docNumber":   "N01-23-456789",
          "expiryDate":  "2028-01-15",
          "serialNumber":"A123456789"
        }
      }
    ]
  },
  "session_info": {
    "session_id":                "session-uuid",
    "linked_to_existing_session": false
  },
  "files_processed":  2,
  "total_processing_time": 4.12   // seconds
}

ℹ️ Government verification runs in the background after the response is returned. The is_verified field on the session will update once verification completes — poll GET /id/session/{id} or register a callback via POST /id/session/{id}/callback.

🖼️

Image Quality

Assess document image quality before or after OCR. Results are stored on the session when a session_id is provided.

POST /id/analyze/quality multipart/form-data or file_urls

Same file input options as /id/analyze. Accepts user_id, document_type, and optional session_id query parameters. When session_id is supplied, quality results are merged into the existing session.

JSONResponse 200

{
  "id":         "session-uuid",
  "passed":     true,
  "sides": {
    "front": {
      "brightness":       74,
      "blur":             false,
      "taken_from_screen":false,
      "bright_spot_text": false,
      "dpi":              96,
      "resolution":       "2048 x 1536 pixels"
    }
  },
  "session_info": {
    "session_id":                "session-uuid",
    "linked_to_existing_session": true
  },
  "total_processing_time": 1.02
}

POST /id/analyze/quality/body JSON body with image URLs

Alternative to the multipart variant when images are already hosted at a URL. Accepts a JSON body with explicit front/back mapping.

Request Body

Field	Type	Required	Description
user_id	string	required	Applicant identifier.
document_type	string	required	Document type code.
front	string	optional*	URL of the front-side image.
back	string	optional*	URL of the back-side image. At least one of `front` or `back` is required.

🛡️

Fraud Detection

Analyze a document image for tampering, screenshot artifacts, photocopy signs, photo substitution, and security feature anomalies.

POST /id/fraud-detection multipart/form-data or file_urls

Query Parameters

Parameter	Type	Required	Description
user_id	string	required	Applicant identifier.
document_type	string	required	Document type code. Values: `passport`, `driving_license_ph`, `umid`, `national_id_ph`.
session_id	string	optional	Session ID from `/id/analyze` to link results. If omitted, the most recent session for this user is used.
is_dark_image	boolean	optional	Set `true` if the document image was captured in low-light conditions to adjust detection thresholds.

JSONResponse 200

{
  "id":            "session-uuid",
  "user_id":       "user123",
  "document_type": "PH_NATIONAL_ID",
  "results": {
    "primary": {
      "is_tampered":           false,
      "is_photocopy":          false,
      "is_taken_from_screen":  false,
      "is_photo_substitution": false,
      "is_ai_generated":       null,   // null if check did not run
      "is_deepfake":           null,   // null if check did not run
      "template_invalid":      false,
      "template_confidence":   0.9,
      "font_inconsistent":     false,
      "font_confidence":       0.85,
      "security_compromised":  false,
      "security_confidence":   0.9,
      "fraud_detected":        false,
      "risk_level":            "low",  // "low" | "medium" | "high" | "critical"
      "fraud_reason":          null
    }
  },
  "session_info": {
    "linked_to_existing_session": true,
    "session_id":                "session-uuid"
  },
  "input_method":          "multipart",
  "files_processed":       1,
  "total_processing_time": 6.08
}

Response Field Definitions

Field	Type	Description
results.primary.is_tampered	boolean	Overall tamper verdict. `true` if any individual check indicates the document has been altered.
results.primary.is_photocopy	boolean	`true` if the document appears to be a photocopy rather than an original.
results.primary.is_taken_from_screen	boolean	`true` if the image was captured by photographing a screen (monitor, phone) rather than a physical document.
results.primary.is_photo_substitution	boolean	`true` if the portrait photo on the document appears to have been replaced or swapped.
results.primary.is_ai_generated	boolean \| null	`true` if the document image is AI-generated or synthetic. `null` when this check did not run.
results.primary.is_deepfake	boolean \| null	`true` if a deepfake face is detected on the document. `null` when this check did not run.
results.primary.template_invalid	boolean	`true` if the document layout deviates from the expected template for the declared document type.
results.primary.template_confidence	number	Confidence score (0–1) for the template validity check. Higher = more confident the template is genuine.
results.primary.font_inconsistent	boolean	`true` if font styles or sizes in the printed fields appear inconsistent with an authentic document (common in digitally altered IDs).
results.primary.font_confidence	number	Confidence score (0–1) for the font consistency check.
results.primary.security_compromised	boolean	`true` if security features (hologram, lamination, microprint) appear missing, damaged, or tampered with.
results.primary.security_confidence	number	Confidence score (0–1) for the security features check.
results.primary.fraud_detected	boolean	Aggregate fraud flag. `true` if any check triggered a fraud signal.
results.primary.risk_level	string	Overall risk rating: `"low"`, `"medium"`, `"high"`, or `"critical"`.
results.primary.fraud_reason	string \| null	Human-readable explanation when `fraud_detected` is `true`. `null` when no fraud is detected.

🤳

Selfie Comparison

Compare the applicant's live selfie against the face extracted from their ID document. A valid session_id is required — PowerCred retrieves the document face automatically.

POST /id/selfie multipart/form-data or selfie_image_url

Query Parameters

Parameter	Type	Required	Description
user_id	string	required	Applicant identifier.
document_type	string	required	Document type code used in `/id/analyze`.
session_id	string	required	Session ID from `/id/analyze`. Used to retrieve the ID face for comparison.
selfie_image_url	string	optional*	URL of the selfie image. Use instead of the multipart `selfie_image` field.
check_deepfake	boolean	optional	Run deepfake detection on the selfie. Default: `true`.
check_face_duplicate	boolean	optional	Check if this face has appeared in other sessions. Result returned in `exists` field. Default: `true`.
eye_closed	boolean	optional	Set `true` if the selfie image shows the applicant with eyes closed (affects liveness signals).

File Input (Multipart)

Field	Type	Required	Description
selfie_image	file	optional*	Selfie image file. Use instead of `selfie_image_url`. JPEG or PNG.

JSONResponse 200

{
  "matched":              true,
  "score":               94.32,  // similarity %, null when not matched
  "deepfake":            false,
  "live":                true,   // liveness check result
  "exists":              null,   // true if face found in another session
  "registered_name":     null,   // name on the matched existing record, if exists
  "verification_collection": null,
  "id":                  "session-uuid",
  "user_id":             "user123"
}

Response Field Definitions

Field	Type	Description
matched	boolean	`true` if the selfie and the ID document face are determined to be the same person.
score	number \| null	Face similarity percentage (0–100). Higher is more similar. `null` when `matched` is `false`.
deepfake	boolean	`true` if the selfie image is detected as a deepfake or digitally manipulated face.
live	boolean	`true` if the selfie passes liveness detection — i.e., it appears to be a live person rather than a photo or replay attack.
exists	boolean \| null	`true` if this face has been matched to a different session (possible duplicate applicant). `null` when the duplicate check did not run.
registered_name	string \| null	The name on the existing session when `exists` is `true`. `null` otherwise.
verification_collection	string \| null	Identifier of the face collection where the duplicate was found. `null` when `exists` is `false` or null.

ℹ️ Either selfie_image (multipart) or selfie_image_url (query param) must be provided. The default face match threshold is 55%. Contact support to adjust the threshold for your account.

🎥

Liveness Video

Stream liveness frames from the client and retrieve the assembled video per session.

POST /id/record-video-frames JSON body

Send base64-encoded video frames in batches. PowerCred assembles them into an MP4 file and stores it for the session. Call this endpoint repeatedly as frames are captured.

Request Body

Field	Type	Required	Description
session_id	string	required	Session ID from `/id/analyze`.
frames	string[]	required	Array of base64-encoded image frames (max 100 per call).
target_fps	number	optional	Desired output video FPS. Range: 5–15. Default: `10`.
target_duration	number	optional	Force exact video duration in seconds. Range: 3–10.

GET /id/liveness/{user_id} Path parameter

Retrieve liveness videos for a user. Returns signed URLs (10-minute expiry) for all recorded attempts. Works independently of sessions — useful when liveness is captured before /id/analyze is called.

JSONResponse 200

{
  "user_id":          "user123",
  "number_of_retries": 2,
  "videos": [
    {
      "retry_number": 1,
      "video_url":    "https://storage.googleapis.com/...?sig=...",
      "size_bytes":   1048576,
      "created_at":   "2024-05-01T10:30:00Z"
    }
  ]
}

GET /id/session/{id}/get-session-video Path parameter

Retrieve the liveness video attached to a specific session. Returns a signed URL valid for 10 minutes.

📋

List Sessions

GET /id/sessions Optional date + user filters

Query Parameters

Parameter	Type	Required	Description
from_date	string	optional	Start date filter. Format: `YYYY-MM-DD`.
to_date	string	optional	End date filter. Format: `YYYY-MM-DD`.
user_id	string	optional	Filter sessions by a specific applicant.

Returns an array of session summary objects. Each object includes the session ID, user ID, document type, completion status, fraud status, and timestamps.

📄

Get Session

GET /id/session/{id} Full session with all pipeline results

Returns the complete session document including OCR results, image quality, fraud detection, selfie comparison, government verification status, and edit history metadata.

JSONResponse 200 (abbreviated)

{
  "id":              "session-uuid",
  "user_id":         "user123",
  "document_type":   "PH_DRIVING_LICENSE",
  "fraud_status":    "In Review",  // "In Review" | "Verified" | "Fraud"
  "is_verified":     true,          // gov verification result
  "edit_status": {
    "edited":     false,
    "edited_by": "unedited",
    "description": null
  },
  "completion_status": {
    "ocr_completed":          true,
    "fraud_check_completed":  true,
    "image_quality_completed":true,
    "selfie_completed":       true
  },
  "data": { /* full OCR + quality + fraud + selfie results */ },
  "created_at":     "2024-05-01T10:30:00Z",
  "last_updated":   "2024-05-01T10:31:22Z"
}

✏️

Update Session

PUT /id/session/{id} Replace session data, stores revision

Replace the data section of a session and store the previous version in revision history. Every call creates a new immutable revision entry.

Request Body

Field	Type	Required	Description
data	object	required	The complete data payload to replace the existing session data with.
edited	boolean	optional	`true` if data was manually modified.
edited_by	string	optional	One of: `"unedited"`, `"edited by borrower"`, `"edited by analyst"`.
description	string	optional	Short note describing the reason for this edit.

🕒

Revision History

GET /id/session/{id}/history Full audit trail

Returns all revisions for a session in chronological order. The last entry (is_current: true) is always the live state.

JSONResponse 200

{
  "session_id":     "session-uuid",
  "total_revisions": 3,
  "revisions": [
    {
      "revision_id": "revision-1",
      "is_current":  false,
      "created_at":  "2024-05-01T10:30:00Z",
      "session_data": { /* snapshot at this point in time */ }
    },
    {
      "revision_id": "current",
      "is_current":  true,
      "created_at":  "2024-05-01T11:02:14Z",
      "session_data": {
        "fraud_status":    "Verified",
        "edit_status":     { "edited": true, "edited_by": "edited by analyst" },
        "data":           { /* current OCR data */ }
      }
    }
  ]
}

ℹ️ Each revision stores a complete snapshot of the session data, not a diff. This makes it straightforward to restore any prior version by passing its session_data.data to PUT /id/session/{id}.

🔖

Fraud Status

Set the analyst decision on a session. Changing this also creates a revision history entry.

PUT /id/session/{id}/fraud-status JSON body

Request Body

Field	Type	Required	Description
fraud_status	string	required	New status. Common values: `"Verified"`, `"Fraud"`, `"In Review"`.
fraud_description	string	optional	Reason or note for this decision.
edited	boolean	optional	`true` if the record was manually modified.
edited_by	string	optional	One of: `"unedited"`, `"edited by borrower"`, `"edited by analyst"`.

JSONRequest

{
  "fraud_status":      "Verified",
  "fraud_description": "All checks passed. Document is authentic.",
  "edited":            true,
  "edited_by":         "edited by analyst"
}

✍️

Correct OCR Fields

Deep-merge field corrections into an existing session. The full corrected result is returned immediately, with an optional webhook notification.

PUT /id/update JSON body + session ID query param

Query Parameters

Parameter	Type	Required	Description
id	string	required	Session ID to update.
callback_url	string	optional	Webhook URL. If provided, the updated result is POSTed asynchronously after the response is returned.

Request Body

Field	Type	Required	Description
data	object	required	Partial or full OCR data. Deep-merged with existing session data. Matches the structure of the `data` field in the `/id/analyze` response.
edited	boolean	optional	`true` to mark this session as manually edited.
edited_by	string	optional	One of: `"unedited"`, `"edited by borrower"`, `"edited by analyst"`.
description	string	optional	Short note about this correction.

JSONRequest — correct a first name and birthdate

{
  "data": {
    "PH_DRIVING_LICENSE": [
      {
        "personal_information": {
          "givenName": "JUAN CARLOS",
          "dob":       "1990-03-15"
        }
      }
    ]
  },
  "edited":     true,
  "edited_by": "edited by analyst",
  "description": "Corrected OCR misread on given name and date of birth"
}

⚠️ Only the fields you include in data are updated — everything else is preserved. If is_verified is false after a correction, use PUT /id/sessions/{id}/rerun-verification to re-check the updated fields.

🔁

Rerun Verification

PUT /id/sessions/{id}/rerun-verification No request body required

Re-run Philippine government verification using the session's current OCR data. Typically called after an analyst corrects OCR fields via PUT /id/update and the initial verification failed.

ℹ️ Show the "Rerun Verification" button in your UI when is_verified == false (or null) and edit_status.edited == true. Hide it once is_verified == true — there is no reason to re-verify a passing result.

JSONResponse 200

{
  "session_id":    "session-uuid",
  "is_verified":   true,
  "failure_reason": null,
  "document_type": "PH_DRIVING_LICENSE"
}

🔔

Journey Callback

POST /id/session/{id}/callback JSON body

Register a webhook URL for a session. If all pipeline steps (OCR, verification, selfie, fraud) are already complete, the callback fires immediately. Otherwise PowerCred stores the URL and triggers the callback automatically when the last step completes.

Request Body

Field	Type	Required	Description
callback_url	string	required	HTTPS URL that will receive a POST with the full session payload when the journey completes.

💡 The callback payload is the same JSON structure returned by GET /id/session/{id}. PowerCred retries up to 3 times with exponential backoff if your endpoint returns a non-2xx response.

📄

Document Types

All document type codes used in the document_type parameter across all endpoints.

Code	Document	Gov Verification	MRZ Support
PH_DRIVING_LICENSE	Philippine Driver's License	✓ docNumber + serialNumber + expiry	—
PH_PASSPORT	Philippine Passport	✓ passportNumber + name + dob	✓ MRZ parsed automatically
PH_NATIONAL_ID	Philippine National ID (PhilSys)	✓ name + dob	✓ QR code verification
PH_UMID	Unified Multi-Purpose ID	✓ CRN + name	—
PH_SSS_ID	Social Security System ID	✓ SSS number + name	—
PH_PRC_ID	Professional Regulation Commission ID	✓ PRC number + name + dates	—
PH_TIN	Tax Identification Number card	✓ TIN number	—

🗂️

Session Model

Key fields present on every session document returned by GET /id/session/{id}.

Field	Type	Description
id	string	Unique session identifier (hex UUID).
user_id	string	Your internal applicant identifier.
document_type	string	Document type code (e.g. `PH_DRIVING_LICENSE`).
fraud_status	string	`"In Review"` \| `"Verified"` \| `"Fraud"`. Set manually by analysts.
is_verified	boolean	Result of Philippine government verification. `null` while verification is in progress.
verification_status	string	`"pending"` \| `"completed"` \| `"not applicable"`.
edit_status	object	`{ edited, edited_by, description }`. Tracks manual OCR corrections.
completion_status	object	`{ ocr_completed, fraud_check_completed, image_quality_completed, selfie_completed }`. Each flag is set when the corresponding pipeline step completes.
data	object	All pipeline results — OCR fields, image quality, fraud detection, selfie match score.
batch_id	string	Optional. Groups sessions submitted together. `null` for standalone submissions.
created_at	timestamp	UTC timestamp when the session was created.
last_updated	timestamp	UTC timestamp of the last write to this session.

📋

OCR Field Reference

Every field returned in a session response — OCR extracted data, fraud signals, selfie results, supporting extractions, and session metadata. Fields marked N/A were not detected or are not applicable to the document type.

Session Fields

Top-level fields on every object returned by GET /id/session/{id}.

Field	Type	Description
id	string	Unique session identifier (32-char hex UUID). Use this to reference the session in all subsequent API calls.
user_id	string	Your internal applicant identifier, passed at submission time.
document_type	string	Document type code declared at submission (e.g. `PH_NATIONAL_ID`, `PH_DRIVING_LICENSE`).
created_at	string	UTC timestamp when the session was first created (`YYYY-MM-DD HH:MM:SS`).
last_updated	string	UTC timestamp of the most recent write to this session (OCR, fraud check, selfie, or manual edit).
status	string \| null	Internal processing status. `null` once processing completes successfully.
fraud_status	string	Analyst-set verdict: `"In Review"` (default), `"Verified"`, or `"Fraud"`. Updated via `PUT /id/session/{id}/fraud-status`.
fraud_description	string \| null	Optional analyst note recorded alongside the fraud status update. `null` if no note was provided.
is_verified	boolean \| null	Result of the Philippine government verification check. `true` = verified, `false` = not verified, `null` = verification still in progress or not applicable.
verification_failure_reason	string \| null	Human-readable reason when `is_verified` is `false` (e.g. `"Record not found"`). `null` when verified or in progress.
verification_status	string	`"pending"` — verification running in background. `"completed"` — result available. `"not applicable"` — no government check for this document type.
batch_id	string \| null	Groups sessions submitted together in a batch. `null` for standalone submissions.
mrz	string \| null	Raw machine-readable zone string extracted from the document. Populated for passports only. `null` for all other document types.
liveness_video	object \| null	Liveness video analysis result when video frames were submitted. `null` when no video was provided.

OCR Data Fields

Fields within ocr.results.[DOCUMENT_TYPE][0]. All string fields return "N/A" when the value was not detected or is not printed on the document.

Field	Type	Documents	Description
documentType	string	All	Document type code echoed back (e.g. `PH_NATIONAL_ID`).
issuing_country	string	All	ISO 3166-1 alpha-2 country code of the issuing authority (e.g. `"PH"`).
fullName	string	All	Complete name as printed on the document, including given name, middle name, and last name.
givenName	string	All	First name(s) as printed on the document. May include multiple given names.
middleName	string	All	Middle name or mother's maiden surname as printed. `"N/A"` if not present on the document.
lastName	string	All	Family/surname as printed on the document.
suffix	string	All	Name suffix (e.g. `Jr.`, `Sr.`, `III`). `"N/A"` if not present.
gender	string	All	`"M"` for Male, `"F"` for Female as printed on the document.
dateOfBirth	string	All	Date of birth in `YYYY-MM-DD` format.
placeOfBirth	string	National ID, Passport	City and region of birth as printed on the document.
nationality	string	National ID, Passport	Nationality as printed (e.g. `"Filipino"`).
address	string	National ID, Driving License	Full registered address as printed on the document.
profession	string	PRC ID, National ID	Profession or occupation as printed. `"N/A"` if not present on the document type.
mobileNumber	string	National ID	Mobile number if printed on the document. `"N/A"` for most document types.
docNumber	string	All	Primary document number. For National ID this is the PCN (e.g. `4602-7594-8291-8347`); for Driving License it is the license number; for Passport it is the passport number.
serialNumber	string	National ID, DL, UMID, SSS, PRC	Secondary reference number printed on the card (e.g. the PSA serial on the National ID, or control number on a Driving License).
issuanceDate	string	All	Date the document was issued, in `YYYY-MM-DD` format. `"N/A"` if not printed.
expiryDate	string	All	Document expiry date in `YYYY-MM-DD` format. `"N/A"` for non-expiring documents (e.g. Philippine National ID).
mrz	string	Passport	Raw MRZ (Machine Readable Zone) string from the document. `"N/A"` for non-MRZ documents.
is_verified	boolean \| null	All	Government verification result for this specific document record. Mirrors the session-level `is_verified` field.
qr_code	object	National ID, UMID	QR code extraction result (see QR Code Fields below). `{ found: false }` when no QR code detected.
faces	object \| null	All	Face image(s) cropped from the document — `{ face_1: "data:image/jpg;base64,..." }`. `null` when no face was detected.

QR Code Fields

Returned as qr_code on the session and within each OCR result object.

Field	Type	Description
found	boolean	`true` if a QR code was detected and decoded in the document images.
data	string \| null	Raw decoded QR payload as a string. For Philippine National IDs this is a JSON string containing the PSA-signed subject data and EDDSA signature. `null` when `found` is `false`.
source	string \| null	Which image the QR was found on: `"front"` or `"back"`. `null` when not found.

Face Extraction Fields

Returned as the top-level face_extraction object on the session.

Field	Type	Description
faces	object	Map of cropped face images extracted from the ID document. Keys are `face_1`, `face_2`, etc. Each value is a base64 data URI (`data:image/jpg;base64,...`). Used by `/id/selfie` as the reference face automatically.
faces_count	number	Number of faces detected in the document image.
_filename	string	Filename of the source image from which the face was extracted (e.g. `"front.jpg"`).
_status	string	Extraction status: `"success"`, `"face_detection_failed"`, `"no_front_image"`, or `"error"`.

Fraud Detection Fields

Returned under fraud.primary on the session. See Fraud Detection for the full endpoint reference.

Field	Type	Description
fraud_detected	boolean	Aggregate fraud flag. `true` if any individual check triggered a fraud signal.
risk_level	string	Overall risk rating: `"low"`, `"medium"`, `"high"`, or `"critical"`.
fraud_reason	string \| null	Human-readable explanation when `fraud_detected` is `true`. `null` when no fraud detected.
is_tampered	boolean	`true` if any check indicates the document has been altered after issuance.
is_photocopy	boolean	`true` if the image appears to be a photocopy rather than an original document.
is_taken_from_screen	boolean	`true` if the image was captured by photographing a screen rather than a physical document.
is_photo_substitution	boolean	`true` if the portrait photo on the document appears to have been replaced.
is_ai_generated	boolean \| null	`true` if the document image is detected as AI-generated or synthetic. `null` when this check did not run.
is_deepfake	boolean \| null	`true` if a deepfake face is detected on the document image. `null` when this check did not run.
template_invalid	boolean	`true` if the document layout deviates from the expected template for this document type.
template_confidence	number	Confidence score (0–1) for the template validity check. Higher = more confident the layout is genuine.
font_inconsistent	boolean	`true` if font styles or sizes appear inconsistent with an authentic document — common indicator of digital alteration.
font_confidence	number	Confidence score (0–1) for the font consistency check.
security_compromised	boolean	`true` if security features (hologram, lamination, microprint) appear missing, damaged, or tampered with.
security_confidence	number	Confidence score (0–1) for the security features check.

Selfie Fields

Returned under selfie on the session after POST /id/selfie completes. See Selfie Comparison for the endpoint reference.

Field	Type	Description
matched	boolean	`true` if the selfie and the ID document face are the same person above the match threshold (default 55%).
score	number \| null	Face similarity percentage (0–100). Higher = more similar. `null` when `matched` is `false`.
deepfake	boolean	`true` if the selfie image is detected as a deepfake or digitally manipulated face.
live	boolean	`true` if the selfie passes liveness detection — appears to be a live person rather than a printed photo or replay attack.
exists	boolean \| null	`true` if this face has been matched to a different existing session (possible duplicate applicant). `null` when the duplicate check did not run.
registered_name	string \| null	The name on the existing session when `exists` is `true`. `null` otherwise.
verification_collection	string \| null	Identifier of the face collection where the duplicate was found. `null` when `exists` is `false` or null.

Files & Supporting Fields

Field	Type	Description
files.original	string[]	Array of signed Google Cloud Storage URLs for the original document images uploaded to this session. URLs are time-limited (expires in ~7 days).
files.selfie	string[]	Signed GCS URLs for the selfie image(s) submitted to this session.
edit_status.edited	boolean	`true` if any OCR field on this session has been manually corrected via the dashboard or API.
edit_status.edited_by	string	Email or identifier of the analyst who made the last manual edit. `"unedited"` when no edits have been made.
edit_status.description	string \| null	Optional note recorded by the analyst when the edit was saved.
verification_summary.is_ai_generated	boolean	Consolidated AI-generated image check result (from fraud detection).
verification_summary.is_deepfake	boolean	Consolidated deepfake detection result (from fraud detection).
verification_summary.selfie_matched	boolean	Mirrors `selfie.matched`. Provided at the top level for easy access without traversing the selfie object.
verification_summary.selfie_score	number \| null	Mirrors `selfie.score`.
verification_summary.selfie_live	boolean	Mirrors `selfie.live`.
verification_summary.selfie_deepfake	boolean	Mirrors `selfie.deepfake`.
verification_summary.selfie_exists	boolean \| null	Mirrors `selfie.exists`.
verification_summary.selfie_registered_name	string \| null	Mirrors `selfie.registered_name`.

Field Coverage by Document Type

Which OCR fields are populated for each Philippine document type. Fields not in this matrix default to "N/A".

Field	National ID	Driving License	Passport	UMID	SSS ID	PRC ID	TIN
fullName / givenName / lastName	✓	✓	✓	✓	✓	✓	—
middleName / suffix	✓	✓	✓	✓	✓	✓	—
gender	✓	✓	✓	✓	✓	✓	—
dateOfBirth	✓	✓	✓	✓	✓	✓	—
docNumber	✓ PCN	✓ License No.	✓ Passport No.	✓ CRN	✓ SSS No.	✓ PRC No.	✓ TIN
serialNumber	✓	✓	—	✓	✓	✓	—
expiryDate	—	✓	✓	—	—	✓	—
issuanceDate	✓	✓	✓	✓	✓	✓	—
address	✓	✓	—	—	—	—	—
nationality / placeOfBirth	✓	—	✓	—	—	—	—
profession	—	—	—	—	—	✓	—
mrz	—	—	✓	—	—	—	—
qr_code	✓	—	—	✓	—	—	—

✓ = field populated | — = field returns "N/A" or is not printed on this document type

⚠️

Error Reference

All errors return a JSON body with a detail field.

HTTP Status	When it happens	Common fix
400	Missing required query param, invalid field value, or conflicting inputs (e.g. both `files` and `file_urls` provided).	Check that all required parameters are present and only one file input method is used.
401	Missing or invalid `apikey` query parameter.	Ensure your API key is correct and appended as `?apikey=YOUR_KEY`.
404	Session not found (GET / PUT / DELETE on a non-existent session ID).	Verify the session ID. Check that the session was created by the same API key.
422	Back-only upload detected (`/id/analyze`) or no face detected in image (`/id/selfie`).	Ensure front image is present and passes quality checks before calling the selfie endpoint.
500	Internal processing error — OCR failure, verification timeout, or image decoding error.	Retry with exponential backoff. Contact support with the session `id` if the error persists.

JSONError body

{ "detail": "user_id is required" }

// Or with session context:
{ "detail": { "id": "session-uuid", "error": "please upload the front id card first", "reason": "back_only_detected" } }

EnterpriseKYC APIs

Overview

One Call, Full Pipeline

Session-Backed

Liveness Video

Journey Callbacks

Authentication

Base URLs

Endpoint Map

KYC Flow

Submit Document

Check Image Quality

Run Fraud Detection

Compare Selfie

Review & Decide

Analyze — OCR Pipeline

Query Parameters

File Input — Option A: Multipart Upload

File Input — Option B: URL Array

Image Quality

Request Body

Fraud Detection

Query Parameters

Response Field Definitions

Selfie Comparison

Query Parameters

File Input (Multipart)

Response Field Definitions

Liveness Video

Request Body

List Sessions

Query Parameters

Get Session

Update Session

Request Body

Revision History

Fraud Status

Request Body

Correct OCR Fields

Query Parameters

Request Body

Rerun Verification

Journey Callback

Request Body

Document Types

Session Model

OCR Field Reference

Session Fields

OCR Data Fields

QR Code Fields

Face Extraction Fields

Fraud Detection Fields

Selfie Fields

Files & Supporting Fields

Field Coverage by Document Type

Error Reference

Enterprise
KYC APIs