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.

The endpoint accepts two request styles — pick whichever is easier from your caller:

• Multipart / form-data — use when you're uploading the file bytes directly (file). Other params travel on the query string.
• JSON body — use when the document is already hosted somewhere accessible (send file_url) or when you'd rather keep everything in the request body. Set Content-Type: application/json.

Option A · Multipart form-data

Params on the query string, file in form-data.

Query parameters

Form-data

Option B · JSON body

Set Content-Type: application/json and pass the Authorization: Bearer <apikey> header. All fields move into the JSON body.

Request body

{
  "reference_id": "ref-12345",
  "document_type": "payslip",
  "file_url": "https://your-storage.example.com/payslip.pdf",
  "callback_url": "https://your-app.example.com/webhooks/ocr",
  "tamper_check": false,
  "get_image_quality": true
}

Response — 202 Accepted

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

Common errors

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

Request — query parameters

Response — 200 OK (single payslip)

When the submitted file contains a single pay period, data is a JSON object with the extracted fields.

{
  "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
  }
}

Response — 200 OK (multiple months in one file)

When the submitted file bundles payslips from multiple pay periods (e.g. the last three months in one PDF), data becomes an array — one object per detected payslip, ordered by pay date. All other top-level fields (id, document_type, status) are unchanged. Iterate over data in your client code and treat each element as a full payslip record.

{
  "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-04-01",
      "pay_period_end": "2026-04-15",
      "pay_date": "2026-04-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
    },
    {
      "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
    },
    {
      "employee_name": "Juan Dela Cruz",
      "employee_id": "EMP-00123",
      "employer_name": "Acme Corporation",
      "pay_period_start": "2026-06-01",
      "pay_period_end": "2026-06-15",
      "pay_date": "2026-06-20",
      "gross_pay": 36500.00,
      "basic_pay": 30000.00,
      "allowances": 6500.00,
      "total_deductions": 4900.00,
      "net_pay": 31600.00,
      "contributions": {"sss": 1125.00, "philhealth": 875.00, "pagibig": 100.00},
      "withholding_tax": 2800.00
    }
  ]
}

Status semantics

Permanently remove an OCR record and its stored extraction data. Useful for right-to-be-forgotten flows or purging test data. The delete is scoped to the account associated with your API key — records belonging to other customers cannot be deleted.

Request — query parameters

Response — 200 OK

{
  "message": "Data deleted successfully",
  "id": "3b41c2e0-9d2a-4e5e-bb37-2b8e0c0fbb12"
}

Response fields

Common errors

Query parameters

Response fields

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).

Query parameters

Path parameters

Option A · multipart/form-data

Option B · application/json

{
  "file_urls": [
    "https://your-storage.example.com/payslip_v1.pdf",
    "https://your-storage.example.com/payslip_v2.pdf"
  ],
  "similarity_threshold": 0.85
}

Response fields

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.

Query parameters

Option A · multipart/form-data

Option B · application/json

{
  "file_urls": [
    "https://your-storage.example.com/payslip.pdf"
  ],
  "producer_pattern": "Adobe PDF Library",
  "fonts": ["Arial", "Helvetica"],
  "similarity_threshold": 0.85
}

Response fields

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.

Query parameters

Option A · multipart/form-data (all optional)

Option B · application/json (all optional)

{
  "file_urls": ["https://your-storage.example.com/payslip_v2.pdf"],
  "producer_pattern": "Adobe PDF Library",
  "fonts": ["Arial", "Helvetica"],
  "similarity_threshold": 0.9,
  "file_mode": "append"
}

Response fields

Example — 200 OK

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

Query parameters

Response fields

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.

Query parameters

Response fields

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
    }
  ]
}

Query parameters

Response fields

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.

Query parameters

Response fields

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

Option A · multipart/form-data

Option B · application/json

{
  "file_url": "https://your-storage.example.com/payslip.pdf",
  "document_id": "payslip"
}

Response fields

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

Query parameters

Request body

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

Response fields

All three Fraud Signals endpoints (/run, /run-from-session, GET /runs/{run_id}) return the same FraudDetectionResponse shape documented below. For the full enumeration of payslip checks, per-status examples, and HTTP error responses, see Possible responses — payslip.

Category

Check

Signals

Metadata

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

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

Path parameters

Query parameters

Request body

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

Response fields

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

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

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

Every payslip check the pipeline can emit, one worked example body per overall_status, and the HTTP error responses shared by all three Fraud Signals endpoints. Applies to document_type = payslip with region = ph; other regions and document types have their own catalogs.

Payslip check catalog

Each check surfaces under its parent category with a stable name, a status, and — when a rule fires — one or more findings. Cross-document checks are only meaningful when two or more payslips are submitted in the same request; with a single payslip they resolve to inconclusive, which is not a negative signal. Finding code values are stable identifiers; new codes may be added as the pipeline evolves, so treat the illustrative codes in the examples below as representative rather than exhaustive.

Lender signals

The signals.lender_signals[] array carries up to ten cards summarising the payslip for underwriting. Each entry is { name, value, status, evidence? }.

Example — 200 OK · overall_status: "pass"

Single payslip; everything balances and every mandatory deduction is present. Cross-document checks resolve to inconclusive (single document) but do not affect the overall verdict because they are not evaluated in the aggregate.

{
  "run_id": "3f8c1e12-9c0a-4c17-a1b6-2b8e0c0fbb12",
  "document_type": "payslip",
  "overall_status": "pass",
  "categories": [
    { "name": "Arithmetic Integrity",  "status": "pass", "checks": [ /* … */ ] },
    { "name": "Document Credibility",  "status": "pass", "checks": [ /* … */ ] },
    { "name": "Cross-Document Checks", "status": "inconclusive", "checks": [ /* single-doc */ ] },
    { "name": "Statutory Compliance",  "status": "pass", "checks": [ /* … */ ] }
  ],
  "signals": {
    "financial_summary": {
      "gross_pay": 35000.00, "net_pay": 30250.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": "payslip_arithmetic_integrity_score", "value": 100,   "status": "pass" },
      { "name": "document_trust_score",               "value": 92,    "status": "pass" },
      { "name": "employment_formality_score",         "value": 100,   "status": "pass" },
      { "name": "mandatory_deductions_coverage_ratio","value": "3/3", "status": "pass" }
    ]
  }
}

Example — 200 OK · overall_status: "warn"

Two payslips submitted; arithmetic and statutory checks are clean, but the employer name differs cosmetically between the two documents.

{
  "run_id": "7c22a5b8-4d9f-4a1b-b7ea-9d4d1f83c001",
  "document_type": "payslip",
  "overall_status": "warn",
  "categories": [
    {
      "name": "Cross-Document Checks",
      "status": "warn",
      "checks": [
        {
          "name": "employer_consistency",
          "status": "warn",
          "findings": [
            {
              "severity": "medium",
              "code": "employer_name_fuzzy_mismatch",
              "message": "Employer names differ in formatting across payslips.",
              "evidence": { "values": ["Acme Corp", "ACME Corporation Inc."], "similarity": 0.78 }
            }
          ]
        }
      ]
    }
  ],
  "signals": {
    "lender_signals": [
      { "name": "document_trust_score", "value": 74, "status": "warn" }
    ]
  }
}

Example — 200 OK · overall_status: "fail"

Two hard failures: arithmetic does not balance, and Pag-IBIG is missing from the deductions.

{
  "run_id": "b1035e77-9e21-4c8b-8bbd-2d9f4b7c0e12",
  "document_type": "payslip",
  "overall_status": "fail",
  "categories": [
    {
      "name": "Arithmetic Integrity",
      "status": "fail",
      "checks": [
        {
          "name": "net_pay_reconciliation",
          "status": "fail",
          "findings": [
            {
              "severity": "high",
              "code": "net_pay_mismatch",
              "message": "gross_pay - total_deductions does not equal net_pay.",
              "evidence": {
                "gross_pay": 35000, "total_deductions": 4750,
                "net_pay": 31500, "expected_net_pay": 30250
              }
            }
          ]
        }
      ]
    },
    {
      "name": "Statutory Compliance",
      "status": "fail",
      "checks": [
        {
          "name": "mandatory_deductions_coverage",
          "status": "fail",
          "findings": [
            {
              "severity": "high",
              "code": "pagibig_contribution_missing",
              "message": "Pag-IBIG contribution is not present on the payslip.",
              "evidence": { "present": ["sss", "philhealth"], "missing": ["pagibig"] }
            }
          ]
        }
      ]
    }
  ],
  "signals": {
    "lender_signals": [
      { "name": "payslip_arithmetic_integrity_score", "value": 40,    "status": "fail" },
      { "name": "mandatory_deductions_coverage_ratio","value": "2/3", "status": "fail" }
    ]
  }
}

Example — 200 OK · overall_status: "inconclusive"

Single payslip with key fields missing — the pipeline runs to completion but cannot reach a verdict on multiple categories.

{
  "run_id": "e59f0a3e-1d4c-4e17-b2e5-52ab4c9f1b21",
  "document_type": "payslip",
  "overall_status": "inconclusive",
  "categories": [
    {
      "name": "Cross-Document Checks",
      "status": "inconclusive",
      "checks": [
        {
          "name": "employer_consistency",
          "status": "inconclusive",
          "findings": [
            {
              "severity": "low",
              "code": "single_document",
              "message": "Cross-document checks require two or more payslips.",
              "evidence": { "document_count": 1 }
            }
          ]
        }
      ]
    },
    {
      "name": "Statutory Compliance",
      "status": "inconclusive",
      "checks": [
        {
          "name": "sss_contribution",
          "status": "inconclusive",
          "findings": [
            {
              "severity": "low",
              "code": "missing_field",
              "message": "gross_pay is required to resolve the SSS bracket.",
              "evidence": { "missing": ["gross_pay"] }
            }
          ]
        }
      ]
    }
  ]
}

HTTP error responses

All three Fraud Signals endpoints share the same error surface. The body shape is { "detail": … } — either a string (validation errors) or an object with error_code and message (upstream and downstream failures).

Combined flow across all three services. Each call is independent; you can fan out steps 2 and 3 in parallel.

# 1) Submit the document for OCR
curl -X POST "https://mock.powercred.io/idp/v1/read?reference_id=ref-12345&document_type={document_type}" \
  -H "Authorization: Bearer $IDP_KEY" \
  -F "file=@./document.pdf"
# → { "id": "OCR_ID", ... }

# 2) Poll for the structured payload
curl "https://mock.powercred.io/idp/v1/get?id=$OCR_ID" \
  -H "Authorization: Bearer $IDP_KEY"
# → { "status": "COMPLETED", "data": { ... } }

# 3) Verify authenticity (run in parallel with step 2; No Auth header required, use ?apikey=)
curl -X POST "https://mock.powercred.io/idp/fraud/check?apikey=$TAMPER_KEY&document_id={document_type}" \
  -F "file=@./document.pdf"
# → { "matched": true, "is_epdf": true, ... }

# 4) Generate fraud + lender signals from the OCR session
curl -X POST "https://mock.powercred.io/cms/v1/fraud-detection/{document_type}/run-from-session?region=ph" \
  -H "Authorization: Bearer $CMS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sessions":[{"session_id":"'"$OCR_ID"'","product":"idp"}]}'
# → { "overall_status": "pass", "signals": {...}, ... }

Multi-document cross-period check

Use multiple documents in a single fraud-detection call to surface cross-period anomalies (employer mismatch, pay gaps, sudden income jumps).

curl -X POST "https://mock.powercred.io/cms/v1/fraud-detection/{document_type}/run?region=ph" \
  -H "Authorization: Bearer $CMS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "documents": [
      {"type": "{document_type}", "document_id": "p_1", "data": { /* Month 1 */ }},
      {"type": "{document_type}", "document_id": "p_2", "data": { /* Month 2 */ }},
      {"type": "{document_type}", "document_id": "p_3", "data": { /* Month 3 */ }}
    ]
  }'

Tamper template lifecycle

# Initial template — let the service derive everything (No Auth header, use ?apikey=)
curl -X POST "https://mock.powercred.io/idp/fraud/templates/{document_id}/auto?apikey=$TAMPER_KEY" \
  -F "files=@./template_v1.pdf" \
  -F "similarity_threshold=0.85"
# → { "version_id": "v1", ... }

# Update template → upload new reference, append to existing
curl -X PUT "https://mock.powercred.io/idp/fraud/templates/{document_id}?apikey=$TAMPER_KEY" \
  -F "files=@./template_v2.pdf" \
  -F "file_mode=append"
# → { "version_id": "v2", ... }

# Roll back to the previous version
curl -X PATCH "https://mock.powercred.io/idp/fraud/templates/{document_id}/versions/v1/activate?apikey=$TAMPER_KEY"