API Reference

CREDFORT checks payslips and bank statements for tampering, broken arithmetic, missing salary and reuse across applicants. You send documents, we return a decision with the reasons behind it.

All endpoints live under one base URL and speak JSON. Every response carries an X-Request-Id header; quote it when you contact us.

__BASE__

Authentication

Send your API key as a bearer token on every /v1 call.

Authorization: Bearer cf_test_…

Create keys yourself in the dashboard: add an application for each system that calls CREDFORT, then issue it test or live keys. Keys are shown once and stored only as a hash. Keep them on your server, never in a browser or mobile app. An application can be limited to certain checks and IP addresses.

Sandbox

Sandbox keys never send documents to the extraction model. Instead, they return a realistic payslip or three-month statement for the applicant you name. Put one of these words in the filename to steer the result and test each branch of your integration:

Errors

Errors use standard HTTP status codes and one JSON shape. code is stable and safe to branch on; message is for people.

{
  "error": {
    "type": "invalid_request",
    "code": "file_not_found",
    "message": "Unknown file_id: file_8f3…",
    "field": "files",
    "request_id": "req_68c4c84f3cd441d7"
  }
}

Rate limits

Each key has a requests-per-second limit set by your plan (Starter 5, Growth 50, Enterprise 200 or more). Every response reports where you stand:

Some plans also carry a monthly quota of live cases. Sandbox cases never count toward it.

Idempotency

Send an Idempotency-Key header when creating a case, such as your application ID. If the network drops and you retry with the same key and body, you get the original case back with "replayed": true, and you are not charged twice. The same key with a different body returns 409 idempotency_mismatch.

Upload a file

Upload one payslip or bank statement as multipart/form-data. PDF or image (PNG, JPG, WEBP), up to 20 MB. Keep the returned file_id for the case.

curl __BASE__/v1/files \
  -H "Authorization: Bearer $CREDFORT_KEY" \
  -F file=@payslip.pdf

{
  "file_id": "file_3b1d9c0e5a7f42b18c6d",
  "filename": "payslip.pdf",
  "sha256": "9f2c…",
  "size_bytes": 48211,
  "encrypted": false
}

encrypted is true for a password-protected PDF. We try the applicant's ID number as the password when the case runs.

Create a case

Run checks on one applicant and up to ten files. The case runs in the background: you get 202 straight away, then poll Get a case.

curl -X POST __BASE__/v1/cases \
  -H "Authorization: Bearer $CREDFORT_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: loan-10482" \
  -d '{
  "external_ref": "loan-10482",
  "subject": {
    "full_name": "Thandi Mokoena",
    "id_number": "9001015009087",
    "employer": "Sandbox Holdings"
  },
  "files": [
    {"file_id": "file_3b1d…", "document_type": "PAYSLIP"},
    {"file_id": "file_a07c…", "document_type": "BANK_STATEMENT"}
  ],
  "consent": {
    "reference": "consent-77812",
    "captured_at": "2026-11-10T09:30:00Z",
    "channel": "web"
  }
}'

{
  "case_id": "case_5e0f2a9d1c8b47e6a3f1",
  "status": "RECEIVED",
  "modules_pending": 4,
  "poll_interval_seconds": 2
}

Get a case

Poll every couple of seconds until status is COMPLETED, PARTIAL or FAILED. Before that it is RECEIVED or PROCESSING and result is null.

{
  "case_id": "case_5e0f2a9d1c8b47e6a3f1",
  "external_ref": "loan-10482",
  "status": "COMPLETED",
  "decision": "FAIL",
  "risk_score": 60,
  "rule_version": 1,
  "sandbox": true,
  "charge": 0.0,
  "result": {
    "modules": {
      "doc.integrity": {
        "status": "COMPLETED",
        "outcome": "FAIL",
        "note": null,
        "signals": [{
          "code": "STATEMENT_RUNNING_BALANCE_BREAK",
          "severity": "HARD",
          "module": "doc.integrity",
          "file_id": "file_a07c…",
          "message": "After the 9 Sep transaction the balance should be R 12 058.28, but the statement shows R 13 558.28.",
          "evidence": { … }
        }]
      },
      "doc.forensics": { "status": "COMPLETED", "outcome": "PASS", "signals": [] }
    },
    "files": [ { "file_id": "file_a07c…", "figures": { … } } ],
    "charge": { "currency": "ZAR", "list_total": 38.0, "billed": 0.0, "lines": [ … ] }
  },
  "created_at": "2026-11-10T09:31:02Z",
  "completed_at": "2026-11-10T09:31:20Z"
}

Each module reports its own status: COMPLETED, SKIPPED (for example, no ID number for the reuse lookup; note says why) or UPSTREAM_UNAVAILABLE (extraction was down; that module counts as REVIEW and the case is PARTIAL). Only completed modules are billed.

List cases

Your most recent cases, newest first, without the result body. limit is 1–100, default 25.

Report an outcome

Tell us what you decided. outcome is one of approved, declined, confirmed_fraud or false_positive. Confirmed fraud records the case's document fingerprints, so the same documents fail if they are used again. Posting outcomes on most cases also earns the contributor discount.

curl -X POST __BASE__/v1/cases/case_5e0f…/outcome \
  -H "Authorization: Bearer $CREDFORT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"outcome": "confirmed_fraud"}'

{
  "case_id": "case_5e0f…",
  "outcome": "confirmed_fraud",
  "fingerprints_reported": 3
}

One-shot forensics

Metadata and tamper forensics on a single file, answered synchronously, with no case. Send file and optionally document_type (PAYSLIP by default) as form fields.

curl __BASE__/v1/checks/doc-forensics \
  -H "Authorization: Bearer $CREDFORT_KEY" \
  -F file=@statement.pdf \
  -F document_type=BANK_STATEMENT

{
  "module": "doc.forensics",
  "outcome": "REVIEW",
  "sha256": "c41e…",
  "signals": [ … ],
  "details": { … },
  "charge": { "currency": "ZAR", "billed": 0.0 }
}

Rules

Your rule set decides thresholds and how severe each reason code is. Defaults match how CREDFORT lends today. Each PUT replaces the whole set and creates a new version; every case records the rule_version it ran under.

Usage

Metered checks by day, module and mode, with list amounts. Sandbox rows have an amount of 0.

{ "data": [
  { "date": "2026-11-10", "module": "doc.integrity", "sandbox": false, "units": 42, "list_amount": 504.0 }
] }

Billing

Your running invoice for this month, or another month. It shows usage at list price, then tier, volume and contributor discounts, the platform fee, included credit and 15% VAT. Sandbox usage is never billed.

Decisions & scores

Every finding is a signal with a reason code and a severity:

A module with no HARD or SOFT signals passes. The case decision is the worst module outcome: FAIL over REVIEW over PASS. risk_score adds up the points, capped at 100. The decision is evidence for your credit team; the lending decision stays yours.

Reason codes

Checks are grouped into four modules. Pass any of them in modules:

Every code

Catalogue & pricing

These need no key. /v1/catalogue returns the modules and every reason code above. /v1/pricing returns per-check prices in ZAR excluding VAT, plus plan terms. /health is a liveness check.

Prefer a machine-readable spec? The OpenAPI document describes every endpoint here.