PowerCred Document Intelligence APIs

Upload a document (or supply a public file_url) and start extraction. Validation rules are determined by document_type — your account is configured with the schemas you need.

Request — query parameters

Name	Type	Required	Description
apikey	string	required	Your OCR API key.
reference_id	string	required	Your correlation ID for the end-user or loan application.
document_type	string	required	Document type — e.g. payslip, employment_certificate, national_id, bank_statement.
file_url	string	optional	Public URL of the document. Use instead of multipart file.
callback_url	string	optional	Webhook to receive the final payload on completion.
tamper_check	bool	optional	Run lightweight inline tamper indicators on the document.
get_image_quality	bool	optional	Include image quality assessment (blur, brightness, flash, DPI) for camera images.

Request — form data

Name	Type	Required	Description
file	binary	conditional	PDF, JPEG or PNG. Required if file_url is not provided.

Response — 202 Accepted

{
  "message": "Document parsing started",
  "id": "3b41c2e0-9d2a-4e5e-bb37-2b8e0c0fbb12"
}

Common errors

Code	Reason
400	File is not PDF/JPEG/PNG.
422	Missing required field, or document_type not configured on your account.
401	Missing or invalid apikey.

Poll with the id returned by /read. The same response shape is returned when the extraction completes via callback.

Request — query parameters

Name	Type	Required	Description
apikey	string	required	Your OCR API key.
id	string	required	The id returned by POST /read.
return_json	bool	optional	Return the raw structured JSON instead of the formatted response.
image_quality	bool	optional	Include the image quality assessment block when available.

Response — 200 OK (payslip example)

{
  "id": "3b41c2e0-9d2a-4e5e-bb37-2b8e0c0fbb12",
  "document_type": "payslip",
  "status": "COMPLETED",
  "data": {
    "employee_name": "Juan Dela Cruz",
    "employee_id": "EMP-00123",
    "employer_name": "Acme Corporation",
    "pay_period_start": "2026-05-01",
    "pay_period_end": "2026-05-15",
    "pay_date": "2026-05-20",
    "gross_pay": 35000.00,
    "basic_pay": 30000.00,
    "allowances": 5000.00,
    "total_deductions": 4750.00,
    "net_pay": 30250.00,
    "contributions": {
      "sss": 1125.00,
      "philhealth": 875.00,
      "pagibig": 100.00
    },
    "withholding_tax": 2650.00
  }
}

Status semantics

Code	Meaning	Action
200	Extraction complete; payload returned.	Consume data.
202	Extraction still in progress.	Retry after 2–3 seconds.
404	Document was unreadable.	Resubmit a clearer copy.
500	Extraction failed.	Resubmit; if persistent, contact support.

Response fields

Field	Type	Description
documents	string[]	All document type identifiers registered under your account.
count	integer	Length of documents.

Example — 200 OK

{
  "documents": ["payslip", "national_id"],
  "count": 2
}

Upload reference PDFs and let the service derive every validation rule automatically. Metadata patterns and font lists are taken directly from the PDFs:

• Single unique value across all files → exact-match regex.
• Multiple differing values → regex alternation (?:a|b|…).
• Field absent in all files → omitted (not checked).

Path parameters

Name	Type	Description
document_id	string	The document type identifier you want to register (e.g. payslip).

Form-data fields

Name	Type	Required	Description
files	binary[]	required	One or more PDFs, ≤ 5 MB each.
similarity_threshold	float	optional	Layout cosine-similarity threshold, default 0.85.

Response fields

Field	Type	Description
version_id	string	Identifier of the newly created version (e.g. v1). This version becomes active immediately.
document_id	string	Echo of the path parameter.
template_count	integer	Number of PDFs stored in the new version.
extracted_config	object	Configuration derived from the uploaded PDFs.
extracted_config.metadata_config	object<string,string>	Regex patterns per PDF metadata field (producer, title, author, creator, subject, keywords, creation_date). Fields absent from all uploads are omitted.
extracted_config.fonts	string[]	Union of font family names found across the uploaded PDFs.
extracted_config.similarity_threshold	float	Layout cosine-similarity threshold stored on the version.

Example — 201 Created

{
  "version_id": "v1",
  "document_id": "payslip",
  "template_count": 2,
  "extracted_config": {
    "metadata_config": {
      "producer": "Adobe\\ PDF\\ Library\\ 15\\.0",
      "creator": "Microsoft\\ Word"
    },
    "fonts": ["Arial", "TimesNewRoman"],
    "similarity_threshold": 0.85
  }
}

Use this when you want full control over the regex patterns and font list, rather than relying on auto-extraction.

Form-data fields

Name	Type	Required	Description
files	binary[]	required	One or more PDFs, ≤ 5 MB each.
producer_pattern	string	optional	Regex matched against the PDF producer field.
title_pattern	string	optional	Regex for PDF title metadata.
author_pattern	string	optional	Regex for PDF author metadata.
creator_pattern	string	optional	Regex for PDF creator metadata.
subject_pattern	string	optional	Regex for PDF subject metadata.
keywords_pattern	string	optional	Regex for PDF keywords metadata.
creation_date_pattern	string	optional	Regex for PDF creation date.
fonts	string	optional	JSON array of font families, e.g. ["Arial","Helvetica"].
similarity_threshold	float	optional	Default 0.85.

Response fields

Field	Type	Description
version_id	string	Newly created version. Becomes active immediately.
document_id	string	Echo of the path parameter.
template_count	integer	Number of PDFs stored in the new version.

Example — 201 Created

{
  "version_id": "v1",
  "document_id": "payslip",
  "template_count": 1
}

Any field omitted is carried over from the currently active version. A new version is always created and becomes active immediately.

Form-data fields (all optional)

Name	Type	Description
files	binary[]	Additional PDFs.
file_mode	string	append (default) keeps existing PDFs; overwrite replaces them with the newly uploaded set.
producer_pattern, title_pattern, …	string	New regex for that metadata field.
fonts	string	JSON array of font families.
similarity_threshold	float	Updated threshold.

Response fields

Field	Type	Description
version_id	string	The new version created by this update. Becomes active immediately.
document_id	string	Echo of the path parameter.
template_count	integer	Total PDFs in the new version. With file_mode=append this equals existing + newly uploaded; with overwrite it equals only the newly uploaded set.

Example — 200 OK

{
  "version_id": "v2",
  "document_id": "payslip",
  "template_count": 3
}

Response fields

Field	Type	Description
document_id	string	Document type identifier.
active_version	string	The currently active version for this document type.
metadata_config	object<string,string>	Regex patterns evaluated against the PDF's metadata fields. Keys: producer, title, author, creator, subject, keywords, creation_date. Only keys with rules are present.
fonts	string[]	Font families that must appear in any matching PDF.
similarity_threshold	float	Layout cosine-similarity minimum (0.0–1.0).
template_count	integer	Reference PDFs stored in the active version.
created_at	string (ISO-8601)	When the active version was created.

Example — 200 OK

{
  "document_id": "payslip",
  "active_version": "v1",
  "metadata_config": {"producer": "Adobe PDF Library"},
  "fonts": ["Arial", "Helvetica"],
  "similarity_threshold": 0.85,
  "template_count": 2,
  "created_at": "2026-05-20T08:14:11Z"
}

Returns every version ever created for this document type, ordered by version number. Exactly one will have is_active: true.

Response fields

Field	Type	Description
document_id	string	Document type identifier.
versions	object[]	One entry per version.
versions[].version_id	string	Stable identifier (e.g. v1).
versions[].version_number	integer	Monotonic counter, useful for ordering.
versions[].created_at	string (ISO-8601)	Creation timestamp.
versions[].is_active	boolean	true for the version currently used by /check.
versions[].metadata_config	object<string,string>	Regex patterns stored on this version.
versions[].fonts	string[]	Required fonts on this version.
versions[].similarity_threshold	float	Layout threshold on this version.
versions[].template_count	integer	Reference PDFs in this version.

Example — 200 OK

{
  "document_id": "payslip",
  "versions": [
    {
      "version_id": "v1",
      "version_number": 1,
      "created_at": "2026-05-20T08:14:11Z",
      "is_active": false,
      "metadata_config": {"producer": "Adobe PDF Library"},
      "fonts": ["Arial"],
      "similarity_threshold": 0.85,
      "template_count": 2
    },
    {
      "version_id": "v2",
      "version_number": 2,
      "created_at": "2026-06-04T11:02:55Z",
      "is_active": true,
      "metadata_config": {"producer": "Adobe PDF Library", "creator": "Microsoft Word"},
      "fonts": ["Arial", "Helvetica"],
      "similarity_threshold": 0.88,
      "template_count": 3
    }
  ]
}

Response fields

Field	Type	Description
message	string	Human-readable confirmation.
document_id	string	Document type identifier.
active_version	string	The version that is now active.

Example — 200 OK

{
  "message": "Version 'v2' is now active",
  "document_id": "payslip",
  "active_version": "v2"
}

Removes one PDF from the active version. A new version is created without that file and is set active.

Response fields

Field	Type	Description
version_id	string	The new version created without the deleted file. Becomes active immediately.
document_id	string	Document type identifier.
template_count	integer	Remaining reference PDFs in the new version.

Example — 200 OK

{
  "version_id": "v3",
  "document_id": "payslip",
  "template_count": 1
}

Run the authenticity checks. By default the PDF is checked against every registered document type; pass ?document_id=… to scope to a single type.

Query parameters

Name	Type	Required	Description
document_id	string	optional	Check against this document type only.

Form-data

Name	Type	Required	Description
file	binary	required	The PDF to verify (≤ 5 MB).

Response fields

Field	Type	Description
matched	boolean	Top-level verdict — true if the PDF matched at least one registered document type.
is_epdf	boolean	true for digitally-generated PDFs, false for scanned/image-only PDFs. When false, no checks run.
message	string · nullable	Optional human-readable note (e.g. why checks were skipped).
results	object[]	One entry per document type checked. Empty array for scanned PDFs.
results[].document_id	string	The document type checked against.
results[].matched	boolean	Overall match against this document type's active version.
results[].version_checked	string	Version ID used for the check.
results[].reasons.metadata.matched	boolean	Overall metadata check result.
results[].reasons.metadata.details[]	object[]	Per-field results: field (string), pattern (regex), extracted_value (string·nullable), matched (boolean).
results[].reasons.fonts.matched	boolean	Whether every required font was present.
results[].reasons.fonts.details[]	object[]	Per-font results: required_font (string), found (boolean), extracted_fonts (string[]).
results[].reasons.layout.matched	boolean	Whether layout similarity met the threshold.
results[].reasons.layout.score	float	Cosine similarity against the closest reference (0.0–1.0).
results[].reasons.layout.threshold	float	Threshold value used for the comparison.
results[].reasons.date_integrity.matched	boolean	true when modification date is consistent with creation date.
results[].reasons.date_integrity.creation_date	string · nullable	PDF creation timestamp, if present.
results[].reasons.date_integrity.mod_date	string · nullable	PDF last-modified timestamp, if present.

Example — 200 OK (ePDF, matched)

{
  "matched": true,
  "is_epdf": true,
  "results": [
    {
      "document_id": "payslip",
      "matched": true,
      "version_checked": "v1",
      "reasons": {
        "metadata": {
          "matched": true,
          "details": [
            {
              "field": "producer",
              "pattern": "Adobe PDF Library",
              "extracted_value": "Adobe PDF Library 15.0",
              "matched": true
            }
          ]
        },
        "fonts": {
          "matched": true,
          "details": [
            {"required_font": "Arial", "found": true, "extracted_fonts": ["Arial", "Helvetica"]}
          ]
        },
        "layout": {"matched": true, "score": 0.94, "threshold": 0.85},
        "date_integrity": {"matched": true, "creation_date": "2026-05-15T10:22:01Z", "mod_date": "2026-05-15T10:22:01Z"}
      }
    }
  ]
}

Response — 200 OK (scanned/image PDF)

{
  "matched": false,
  "is_epdf": false,
  "message": "PDF appears to be scanned/image-based; tamper checks skipped.",
  "results": []
}

Use this when you already hold the structured document data (typically the response body from OCR).

Path parameters

Name	Type	Description
document_type	string	payslip or employment_certificate.

Query parameters

Name	Type	Required	Description
apikey	string	required	Your Fraud Signals API key.
region	string	optional	Region code for statutory rules. Defaults to ph.

Request body

{
  "documents": [
    {
      "type": "payslip",
      "document_id": "payslip_1",
      "data": { /* extracted JSON, typically from OCR */ }
    }
  ]
}

Field	Type	Required	Description
documents	array	required	At least one document. Every item's type must match the path.
documents[].type	string	required	Document type; must equal {document_type}.
documents[].document_id	string	optional	Your identifier. Defaults to doc_0, doc_1, …
documents[].data	object	required	Extracted structured data for the document.

Response fields

All three Fraud Signals endpoints (/run, /run-from-session, GET /runs/{run_id}) return the same FraudDetectionResponse shape documented below.

Field	Type	Description
run_id	string (UUID)	Unique identifier for this evaluation. Persist this — you can refetch the result later with GET /runs/{run_id}.
document_type	string	payslip or employment_certificate. Echoes the path parameter.
timestamp	string (ISO-8601)	When the run was executed (UTC).
overall_status	enum	Worst status across all categories: pass, warn, fail, or inconclusive.
categories[]	object[]	One entry per category evaluated. See Category below.
signals	object	Lender-ready summary derived from the document. See Signals below.
gcs	object<string,string>	Internal storage references for the audit trail; safe to ignore in client code.
metadata	object	Request context and processing details. See Metadata below.
session_data	object[] · nullable	Present only for /run-from-session. Lists the upstream sessions resolved: session_id, product, document_type.

Category

Field	Type	Description
name	string	Category label (e.g. Arithmetic Integrity, Document Credibility, Cross-Document Checks, Statutory Compliance).
description	string	What this category evaluates.
status	enum	Worst status across this category's checks.
checks[]	object[]	Individual checks. See Check below.

Check

Field	Type	Description
name	string	Stable check identifier (e.g. net_pay_reconciliation).
description	string	Plain-English explanation.
status	enum	pass, warn, fail, or inconclusive.
checks_performed	string[]	Sub-checks executed within this check.
findings[]	object[]	Issues raised by the check. Each finding has: severity (high/medium/low), code (stable identifier), message (description), evidence (object with relevant raw values).

Signals

Field	Type	Description
signals.financial_summary	object	Normalised financial figures pulled from the document. Each field is nullable.
financial_summary.gross_pay	number	Gross compensation for the period.
financial_summary.net_pay	number	Take-home amount.
financial_summary.basic_pay	number	Base salary component.
financial_summary.total_deductions	number	Sum of all deductions.
financial_summary.sss_contribution	number	SSS contribution (PH).
financial_summary.philhealth_contribution	number	PhilHealth contribution (PH).
financial_summary.pagibig_contribution	number	Pag-IBIG contribution (PH).
financial_summary.withholding_tax	number	Withholding tax for the period.
financial_summary.takehome_ratio	number	net_pay / gross_pay — useful for affordability scoring.
signals.lender_signals[]	object[]	Cards summarising the document for underwriting. Each entry has: name (identifier), value (any), status (pass/warn/fail/inconclusive), evidence (object · nullable).

Metadata

Field	Type	Description
metadata.app_id	string	Your application ID.
metadata.developer_email	string	Developer email tied to the API key.
metadata.app_name	string	Your application name.
metadata.document_type	string	Echo of the path parameter.
metadata.processing_time_ms	number	End-to-end processing time in milliseconds.
metadata.request_ip	string · nullable	Originating IP, if available.
metadata.user_agent	string · nullable	Originating user agent, if available.

Example — 200 OK

{
  "run_id": "3f8c…",
  "document_type": "payslip",
  "timestamp": "2026-06-16T09:12:33Z",
  "overall_status": "pass",
  "categories": [
    {
      "name": "Arithmetic Integrity",
      "description": "Net pay calculations, cross-field consistency, and income stability",
      "status": "pass",
      "checks": [
        {
          "name": "net_pay_reconciliation",
          "description": "gross - deductions = net",
          "status": "pass",
          "checks_performed": ["sum_deductions", "net_pay_match"],
          "findings": []
        }
      ]
    },
    { "name": "Document Credibility",   "status": "pass", "checks": [] },
    { "name": "Cross-Document Checks",  "status": "pass", "checks": [] },
    { "name": "Statutory Compliance",   "status": "pass", "checks": [] }
  ],
  "signals": {
    "financial_summary": {
      "gross_pay": 35000.00,
      "net_pay": 30250.00,
      "basic_pay": 30000.00,
      "total_deductions": 4750.00,
      "sss_contribution": 1125.00,
      "philhealth_contribution": 875.00,
      "pagibig_contribution": 100.00,
      "withholding_tax": 2650.00,
      "takehome_ratio": 0.864
    },
    "lender_signals": [
      { "name": "income_stability",   "value": "stable",   "status": "pass" },
      { "name": "statutory_coverage", "value": "complete", "status": "pass" }
    ]
  },
  "metadata": {
    "app_id": "app_xxx",
    "developer_email": "dev@example.com",
    "app_name": "my-app",
    "document_type": "payslip",
    "processing_time_ms": 412.0
  }
}

Overall status values

Status	Meaning
pass	All checks passed; document looks legitimate.
warn	One or more soft anomalies; review recommended.
fail	At least one hard rule failed; treat as suspicious.
inconclusive	Not enough information to decide.

Skip uploading data — point at an existing PowerCred session (e.g. the OCR id) and we fetch the document data for you.

Request body

{
  "sessions": [
    { "session_id": "3b41c2e0-9d2a-4e5e-bb37-2b8e0c0fbb12", "product": "idp" }
  ]
}

Field	Type	Required	Description
sessions	array	required	At least one upstream session reference.
sessions[].session_id	string	required	The upstream identifier — typically the OCR id.
sessions[].product	string	required	The upstream product key. Errors include the list of supported values.

Response fields

Same FraudDetectionResponse shape as POST /run, with the session_data field populated.

Field	Type	Description
session_data	object[]	One entry per resolved upstream session.
session_data[].session_id	string	The session ID supplied in the request.
session_data[].product	string	The upstream product key (e.g. idp).
session_data[].document_type	string	Document type of the fetched record. Must match the path parameter.

All other fields (run_id, overall_status, categories, signals, metadata) are identical to the /run response.

Example — 200 OK

{
  "run_id": "3f8c…",
  "document_type": "payslip",
  "timestamp": "2026-06-16T09:14:02Z",
  "overall_status": "pass",
  "session_data": [
    {
      "session_id": "3b41c2e0-9d2a-4e5e-bb37-2b8e0c0fbb12",
      "product": "idp",
      "document_type": "payslip"
    }
  ],
  "categories": [ /* same shape as /run */ ],
  "signals":    { /* same shape as /run */ },
  "metadata":   { /* same shape as /run */ }
}

Refetch a previously executed run by run_id.

Path parameters

Name	Type	Description
run_id	string (UUID)	The run_id returned by a previous /run or /run-from-session call under the same account.

Response fields

Returns the same FraudDetectionResponse shape as POST /run. If the original run was session-based, session_data will be populated as well.

Errors

Code	Reason
404	No run with that run_id exists under your account.