Document Forensics API Reference

Overview & lifecycle

Base URL: https://api.scam.ai/v1 (production, sk_live_ keys); sandbox is https://api-sandbox.scam.ai/v1 with an sk_test_ key — same API, unmetered, running the next release before production does (§2026-10-26). The OpenAPI spec for this API is https://docs.scam.ai/openapi.json; /openapi.json on the API host describes the Scam AI platform API (/v1/detections, account endpoints), not this one. All requests and responses are JSON except file upload (multipart) and the audit-report download (a PDF file). Analysis is asynchronous — a single-page PDF typically completes in seconds, but you should integrate against the async lifecycle, not a fixed latency.

Two integration shapes work well inside a LOS pipeline:

• Webhook-driven (recommended): submit on document sync, update your Fraud Review state when document.completed arrives.
• Long-poll: POST /documents?wait=true blocks up to 30 s and usually returns the finished verdict inline — simplest for low volume.

Changes on 2026-10-26 — the sandbox runs the next release first

The two estates no longer run the same build. Production (https://api.scam.ai/v1, sk_live_ keys) answers model_version 3.0: the docforensics engine it cut over with at 1.3, scoring every file, PNG and JPEG included. The sandbox (https://api-sandbox.scam.ai/v1, sk_test_ keys) runs the next release first: model_version 3.1, the docforensics engine 0.17 with its V10 structural model (the learned_model_score check), everything in the 2026-10-15 note below, and PNG and JPEG answered by a second engine, image-forensics. Production gets these on release. Rows marked correction fix what this page said about both estates.

Changes on 2026-10-15 — docforensics engine 0.16

The docforensics engine moves from 0.14 to 0.16 on each estate as it is deployed there: the sandbox now (it runs 0.17), production on release. One field is added, regions[].role (the regions row); no field or endpoint is removed and no existing field changes shape. One limit is new: an image over 89,478,485 pixels is refused, where it used to be scored (the image size row). Photos and scans take longer to score (the timing row). Every other row below is a value a 1.3 client already accepts, or a verdict the engine now reaches more carefully.

Changes in 1.3 (2026-09-30) — the docforensics engine

A new scoring engine, docforensics, is rolled out estate by estate (sandbox first). Everything below is additive; 1.2 clients keep working unmodified.

Changes in 1.2 (2026-09-19)

POST /v1/documents/{id}/reprocess requires the original document as the multipart file part, checked against the document's recorded sha256: no file answers 400 source_file_required, a mismatch 400 invalid_request. New error code source_file_required.

New in spec 1.1

All additions below are additive — no field removed, no enum member dropped, no existing response shape changed. A client built against 1.0 keeps working unmodified.

Changes on 2026-09-28

Two corrections to previously-wrong behaviour, and one additive field. No field or endpoint is removed.

Renamed: Verifi is now Verifit (2026-09-09)

The borrower re-capture product changed its name. Nothing about how it works changed. What changes for you, and when the old names stop working:

Changes on 2026-09-09 (post-rename fixes)

Found by the production e2e run after the rename. Two are corrections to behaviour you may have coded around; the rest tighten guarantees.

Changes on 2026-09-08

Behaviour changes shipping with the next production release of api.scam.ai. No field or endpoint is removed; one endpoint is added; two responses change for requests that were previously accepted, or answered incorrectly.

Authentication

API keys are accepted in either header — Authorization: Bearer sk_live_… or X-API-Key: sk_live_…. The two are equivalent and both work on every endpoint; use whichever suits your client. sk_test_… for sandbox, sk_live_… for production.

Headers only: the key is not a body field and not a query parameter, since GET endpoints have no body and a key in the query string ends up in access logs, browser history and referrer headers. Keys are server-side only — a request carrying a browser Origin header is rejected 401 (browser_origin_forbidden). Rotate keys in the dashboard; two keys can be live simultaneously for zero-downtime rotation.

When both headers are present, X-API-Key takes precedence. Keys must be shaped sk_live_… / sk_test_… — a malformed key, an unknown key, or a live key presented to the sandbox host all return 401 invalid_api_key with a message naming the specific problem. Rate limits apply per key.

Submit a document

Upload the file directly, or pass a pre-signed URL so bytes move straight from your document store. Attach external_ref (your loan id) to every submission — it powers listing and audit reports.

curl https://api-sandbox.scam.ai/v1/documents?wait=true \
  -H "Authorization: Bearer sk_test_…" \
  -H "Idempotency-Key: req-84620" \
  -F "file=@25 (4).pdf" \
  -F 'options={
        "external_ref": "loan_84620",
        "category": "bank_statement",
        "models": ["eva-doc"]
      }'

Limits: PDF/PNG/JPG · 200 MiB (209,715,200 bytes) · 200 pages · on the sandbox (production on release) images up to 89,478,485 pixels (width × height, about 89.5 megapixels). file.pages is the page count of the file. File type is detected from the file's content (PDF, PNG or JPEG signatures), not its name; content in another format (GIF, WEBP, TIFF, HEIC, BMP) → 415 unsupported_type, content matching no known format → 422 unreadable_document when the file name ends .pdf, .png, .jpg or .jpeg and 415 unsupported_type otherwise (a .txt file, no extension), over size, page or pixel limit → 413 file_too_large, empty upload → 400 missing_file. A PDF's page count is read at submit whenever the file can be parsed, so an over-limit PDF gets this 413 synchronously, on the submitting request, before any analysis runs; when the count can't be read there (encrypted, malformed), the same limit is still enforced, just after scoring — the document is accepted, then ends failed with file_too_large instead. Where the pixel limit applies, an image's width and height are read from its header at submit the same way; when its header cannot be read there, or the engine finds a file over one of its own limits (a page over 200 × 200 inches, more than 50,000 PDF objects), the document ends failed with file_too_large. A file that passes the content check but cannot be opened by the engine ends as failed with unreadable_document — or, when what stopped the engine was encryption, with file_encrypted; neither is a rejection at submit, because opening the file is the only way to find out. A PDF carrying only an owner password ("printing restricted") opens without one and is analysed normally. Byte-identical resubmissions (same SHA-256, same model set, same filename, same external_ref) return 200 with the existing Document — the cached result, or the one still processing — at no charge. A document whose analysis ended failed is not a cache hit: resubmitting it analyses the same bytes again under the same id, with the original submission's options (202; billed if the analysis completes — a repeat failure is free). To re-analyse a failed document, use a new Idempotency-Key (or none): a key replays its first response for 24 h. A JSON submission's file_url must be an absolute http(s) URL on a public host, and so must anything it redirects to — anything else is 422 url_fetch_failed. A file_url file is named from Content-Disposition, else the last URL path segment, else document.pdf — the name is not consulted for typing either; a PDF named .png is still detected and scored as a PDF. A JSON request body over 1 MB is 413 request_too_large. ?wait must be true or false; any other value is 400 invalid_request. Idempotency-Key is 64 characters at most (longer is 400 invalid_request); replays are keyed on the header value alone (24 h) and marked with an Idempotency-Replayed: true response header — never reuse a key with a different payload. The same header works on POST /v1/verifit/links and POST /v1/audit-reports.

The Document object

Risk signal → routing

Branch on verdict; use risk_score for ordering and thresholds within a band. Score bands below are observed behavior, not contractual.

An image-forensics answer (sandbox; production on release) also omits risk_score when it is CLEAN, or SUSPICIOUS on the image model's evidence alone — §Image answers. Read a missing score as "not scored", never as 0.

Example — flagged document

The single object your integration renders from. Example — a flagged bank statement (a scored document may omit several display fields; see the notes after the example):

{
  "id": "doc_9f2c1a",
  "object": "document",
  "status": "completed",
  "external_ref": "loan_84620",
  "category": "bank_statement",
  "file": { "name": "25 (4).pdf", "type": "pdf", "pages": 1,
            "size_bytes": 183296,
            "sha256": "e10c2473631cd9a7cc6ad2b268298b949b66d006d8d9c…" },
  "issuer": "Commerce Bank",          // detected source — list secondary line
  "issue_date": "2025-11-17",         // date printed on the document, OCR'd
  "capture": "native_pdf",            // native_pdf | photo | scan — measured; OMITTED if undetermined
  "model": "eva-doc",
  "model_version": "3.1",             // the estate's badge: 3.0 on production, 3.1 on the sandbox; reprocess does not change it
  "verdict": "FORGED",
  "risk_score": 87,
  "headline": "ending balance digitally altered after initial save",
  "indicators": [
    { "code": "TOUCHUP_TEXTEDIT", "severity": "high",
      "title": "Acrobat TouchUp text edit",
      "what_it_is":  "A marker Adobe Acrobat leaves behind when someone edits text…",
      "what_it_means": "Bank-generated statements are never edited in Acrobat after export…",
      "how_detected": "The piece-info dictionary contains a TouchUp_TextEdit entry…" },
    { "code": "REVISION_TEXT_DIFF",  "severity": "high",  "title": "Text changed between saved revisions", "…": "…" },
    { "code": "CROSS_TOTAL_MISMATCH","severity": "high",  "title": "Summary arithmetic does not add up",   "…": "…" }
    // Illustrative codes shown. A scored document carries the engine's
    // snake_case reason codes — touch_up_text_edit, has_piece_info,
    // font_character_remapping, create_date_mismatch, … (~90 codes),
    // severity high | medium — open enum either way, see §Versioning
  ],
  "regions": [
    { "page": 1, "x": 78.2, "y": 33.1, "w": 12.4, "h": 2.1,
      "confidence": 0.94, "severity": "high",
      "label": "$50,521.19", "indicator_code": "REVISION_TEXT_DIFF" }
  ],
  "revisions": { "count": 2, "diffs": [
    { "from_revision": 0, "to_revision": 1,
      "before": "Ending Balance on June 5 … $10,521.19",
      "after":  "$50,521.19" } ] },
  "math_checks": [
    { "formula": "beginning + deposits − withdrawals − checks = ending",
      "computed": "$10,521.19", "stated": "$50,521.19", "ok": false,
      "note": "Δ $40,000.00 appears nowhere in the transaction detail" },
    { "formula": "itemized deposits = deposits total",
      "computed": "$3,615.08", "stated": "$3,615.08", "ok": true }
  ],
  "metadata": [
    { "key": "Producer", "value": "Adobe Acrobat Pro DC 2025", "anomalous": true },
    { "key": "Creator",  "value": "Commerce Bank eStatement Services" },
    { "key": "Incremental revisions", "value": "2", "anomalous": true }
  ],
  "attribution": { "section": "asset", "field": "total_verified_assets",
                   "currency": "USD", "amount_minor": 4000000 },   // 1.1 — echoed, never inferred
  "verifit_eligible": true,            // 1.1 — a borrower re-capture would add evidence
  "created_at":   "2026-07-27T20:12:04Z",
  "completed_at": "2026-07-27T20:12:09Z"
}

Current engine build — field notes

• headline, issuer, issue_date, regions, revisions, genai_heatmap are nullable/omittable — the current engine build does not produce them for every document. Null-check before rendering; LoanSummary.top_reason is null whenever headline is.
• metadata is a fact panel whose value is a display string. A docforensics document carries up to four rows, each only when the engine reported it: Capture ("born digital", "photo"), Created with, Software kind ("office suite") and Software note. A document the earlier engine scored carries up to 10 fixed rows (Format, Pages, File size, Producer, Creator, Created, Modified, Incremental revisions, Fonts embedded, XMP metadata). anomalous is reserved — false on every row.
• math_checks on a docforensics document lists every arithmetic relation the engine ran, on any verdict: ok: true for one that held, ok: false for one that failed or could not be resolved (then computed/stated are empty and note says why). Filter on ok === false. A document the earlier engine scored lists only failing checks, on SUSPICIOUS/FORGED only. An empty array means no relation was reported, not that totals were verified. formula is a plain-language summary; computed/stated are best-effort and may be empty.
• findings can be present on a CLEAN document, with no lead_finding and no indicator for them: they did not decide the verdict. Only findings[lead_finding] decided one.
• model reports the engine that scored the document — docforensics, image-forensics (PNG and JPEG on the sandbox; production on release — §Image answers) or eva-doc (the earlier engine). The names in options.models are what you ASK for; they do not choose the engine and are not what a scored document reports back. Open enum.
• status is processing | completed | failed. Content that is not a PDF/PNG/JPEG is rejected at submit with a 4xx (415 unsupported_type, or 422 unreadable_document when the name ends .pdf, .png, .jpg or .jpeg); a file that passes that check but cannot be opened by the engine ends as failed, asynchronously, with an error object carrying the same catalogued code.
• capture is a measurement, not a restatement of the media type: photo for an image upload, native_pdf for a PDF whose page objects the structural model read, scan for a PDF whose pages are themselves images. Omitted when the class was not determined — while the document is processing, on a failed document, and on the rare completed document classified neither way. Treat absence as "not determined", never as native_pdf. Changed 2026-09-25: until then every PDF, scans included, reported native_pdf; the enum itself is unchanged.

Region coordinates — drawing tamper overlays

Each entry in regions[] locates a tampered/suspect area. Origin is the page's top-left; x/w are percentages (0–100) of rendered page width, y/h of rendered page height — resolution-independent, so the same box fits any zoom level:

// place an overlay div on a rendered page of size pageW × pageH px
left:   region.x / 100 * pageW
top:    region.y / 100 * pageH
width:  region.w / 100 * pageW
height: region.h / 100 * pageH
// region.confidence (0..1) and region.severity drive the badge (94% · high)
// region.indicator_code links the box back to its explanation card
// region.role (since 2026-10-15, arithmetic contradictions only): "result" is the figure the
// calculation is checked against, "operand" a figure it reads; neither says which was edited

A CLEAN document (a paystub at risk 5/100, say) has an empty indicators array and instead lists checks_passed — revision history, TouchUp scan, producer-pipeline match, font-embedding consistency, overlay/script scan, timestamp consistency — so processors see what ran, not just an absence of flags.

Image answers — image-forensics (sandbox now; production on release)

On the sandbox a PNG or JPEG upload is answered by model: "image-forensics": an image model that looks for edits and AI generation, beside the docforensics checks, which still run on the same file. PDFs, scanned ones included, stay with docforensics; on production every file is still scored by docforensics. An image answer differs from a docforensics one here:

• verdict — the image model can raise a document to SUSPICIOUS, never to FORGED: FORGED comes only from the docforensics checks. CLEAN needs every image check to complete with nothing found.
• risk_score — present only when the docforensics checks themselves found the image SUSPICIOUS or FORGED. Omitted on CLEAN, on a SUSPICIOUS the image model raised alone, and on INSUFFICIENT_EVIDENCE. A loan rollup counts an unscored flag at its band floor and in documents_unscored.
• confidence — only on FORGED.
• review_tier — review on every SUSPICIOUS, including one the image model raised alone; it does not mean two independent checks agreed.
• next_step — omitted on CLEAN; present on every other verdict.
• indicators — the docforensics indicators, plus IMAGE_EDIT_REVIEW (title "Possible image edit or AI generation", severity medium, no identifier) when the image model found a possible edit. Model evidence asks for review; it never confirms forgery.
• reason_codes — adds IMAGE_EDIT_REVIEW when the image model found a possible edit, IMAGE_ASSESSMENT_INCOMPLETE when the image checks could not all complete and found nothing, and IMAGE_COVERAGE_LIMITED when the image is a digitally created document (a screenshot, an exported page). When the image checks complete and the docforensics checks flagged nothing, REQUEST_NATIVE_PDF and NO_TEXT_LAYER are left out.
• A digitally created document received as an image is never CLEAN. With nothing found it is INSUFFICIENT_EVIDENCE carrying IMAGE_COVERAGE_LIMITED, and next_step asks for the original, usually a PDF; a clean result on such an image is not evidence that it is genuine. With a finding it is SUSPICIOUS like any other image.
• When the image checks could not all complete and nothing was found, the verdict is INSUFFICIENT_EVIDENCE with IMAGE_ASSESSMENT_INCOMPLETE.
• checks_passed — on CLEAN, the docforensics checks that passed plus image_assessment.
• capture is photo; model_version is the estate's badge (3.1 on the sandbox).
• If the image model stays unavailable through every retry, the document ends failed with server_error, as for any scorer outage.

Retrieve & list

Returns the Document in any status. Poll at ≥ 2 s intervals if not using webhooks.

Cursor-paginated (limit 1–100, default 25; starting_after), newest first. Filter by external_ref or verdict — this is the query behind a "View flagged docs" screen. Returns slim DocumentSummary rows by default (view=summary) — id, name, verdict, risk_score, issuer, issue_date, capture, headline, review disposition — i.e. exactly one list row per object. view=full returns complete Documents.

UI → field mapping

Every element in the Fraud Review UI maps to one contract field — nothing in the interface requires client-side inference:

Review, reprocess & loan rollups

Records the human disposition from the review queue: {"disposition": "in_review" | "cleared" | "escalated" | "confirmed_fraud", "note", "reviewer"}. The disposition is echoed on the Document, clears the doc from the loan's flagged count when cleared, appears in later Fraud Audit Reports, and — de-identified — feeds scoring calibration. Idempotent per document; a later call replaces the earlier one.

in_review is new in 1.1 — a "someone is looking at it" state, so you need no parallel store keyed on our document ids. The three existing values are unchanged.

Re-runs analysis with the current model (the UI's "Re-process" action). Attach the original document as the multipart file part; the bytes must match the document's recorded sha256 (no file: 400 source_file_required; mismatch: 400 invalid_request). Returns 202, status back to processing; the prior verdict stays readable until the new one lands. One still queued or running answers 409 analysis_in_progress.

Aggregate rollup for a queue row and the loan banner: loan-level risk_score, verdict_counts (clean/suspicious/forged), documents_flagged / documents_total / documents_processing / documents_unscored, models used, estimated_review_minutes_saved (display-only heuristic), top_reason (headline of the highest-risk unresolved document), and the flagged DocumentSummary rows so expanding a queue row costs no extra call. A SUSPICIOUS or FORGED document with no score counts toward risk_score at its verdict's band floor — SUSPICIOUS 40, FORGED 70 — and documents_unscored counts how many of the loan's completed documents have no score this way. An INSUFFICIENT_EVIDENCE document has no score by design and is no flag: it counts as 0 and is counted in documents_unscored. A cleared review removes a document from the flagged count — the queue drains as reviewers work.

1.1 adds four fields to the same object: coverage (§Coverage), flagged_amount (§Attribution), review_state and assignee (§Queue).

Fraud Review queue

A queue is a cross-loan view, so 1.1 exposes loans as a listable, filterable, sortable collection with their own triage state. Previously a queue could only be assembled by listing documents and grouping them client-side.

Returns LoanSummary rows for every external_ref with at least one completed document. Filters: has_unresolved (at least one flagged document without a cleared disposition), min_risk_score, review_state, assignee. Sort by -risk_score (default), risk_score, ±updated_at. Cursor-paginated with limit and starting_after.

{ "review_state": "in_review",
  "assignee": "dana.whitfield@example.com",   // opaque to us — never resolved to a person
  "note": "Requested re-capture of the June statement" }

review_state ∈ open · in_review · cleared · escalated, defaulting to open once any document in the loan is flagged. It is loan-level workflow state, distinct from the per-document disposition — so the queue can be worked without holding a second state store keyed on our identifiers. An explicit null clears assignee or note; omitting the key leaves the current value alone. Idempotent; a later call replaces the earlier state.

Coverage attestation

"Every document was screened" is only meaningful if it can be reconciled. The API knows the documents it received; it cannot know about one that was never sent. 1.1 closes that by letting you declare the expected set up front.

{ "expected_total": 36,
  "items": [                                   // optional itemisation
    { "key": "bank_stmt_jun", "name": "June bank statement", "category": "bank_statement" },
    { "key": "paystub_2",     "name": "Paystub 2",           "category": "paystub" }
  ] }

Submit each document with the matching expected_key and the declared item resolves. LoanSummary.coverage then reports against the declaration:

To take a declaration back, DELETE /v1/loans/{external_ref}/expected-documents withdraws it: expected_total, unscreened and complete become absent again and missing empties. PUT can only replace a declaration with another, and expected_total: 0 asserts complete: true — a stronger claim than none. Idempotent; returns the rollup.

"coverage": {
  "expected_total": 36, "submitted": 36, "screened": 36,
  "processing": 0, "failed": 0, "unscreened": 0,
  "complete": true, "missing": []
}

Flagged-amount attribution

Counts answer "how many documents are flagged"; underwriting asks "how many dollars rest on them". Tell us what each document substantiates and we compute the exposure server-side, so the figure in your UI and the figure in the audit report cannot drift apart.

// on submit
"attribution": { "section": "asset", "field": "total_verified_assets",
                 "currency": "USD", "amount_minor": 4000000 }

// on GET /v1/loans/{external_ref}
"flagged_amount": {
  "currency": "USD", "amount_minor": 4000000,
  "basis": "Total verified assets substantiated by documents that are SUSPICIOUS or FORGED and not cleared",
  "contributing_document_ids": ["doc_9f2c1a", "doc_3b71e4"]
}

section ∈ asset · income · liability · property · identity · other, and it is required — currency defaults to USD and amount_minor to 0, so an attribution naming only a section is valid. Every attributed document on one loan must agree on currency; a second currency is refused at submit with 422 attribution_currency_conflict, because a rollup that cannot add is worse than a submission that fails. field is your own field id. Amounts are integer minor units (cents) rather than decimals so sums are exact — elsewhere the API uses display strings for money (math_checks.computed), but those are never arithmetic operands and these are.

Attribution is never inferred. A document with no attribution contributes nothing to the sum, and flagged_amount is absent when no document in the loan carried one. Clearing a document's review removes it from the total.

Verifit — verified borrower re-capture

When a document is unreadable, a photo of a screen, or contradicted by its own arithmetic, the strongest next step is a fresh capture of the source document taken under provenance. Verifit mints a single-use link that opens a mobile capture page; the photo is C2PA-signed on the device, analyzed by the normal pipeline, and reconciled against the original submission.

{ "document_id": "doc_9f2c1a",
  "borrower": { "display_name": "J. Sample", "phone": "+19705550147", "locale": "en-US" },
  "message": { "template_id": "quality",
               "body": "The resolution on your {document} wasn't high enough for us to process…" },
  "delivery": "sms",                // sms | email | link_only (no PII required)
  "expires_in": "PT48H" }           // default PT48H, max P7D, must be positive

→ 201
{ "id": "vfl_4c81", "object": "verifit_link", "status": "pending",
  "url": "https://verifit.scam.ai/claim/<token>", "qr_png_url": "…",
  "message_audit": { "safe": true, "matched_terms": [], "acknowledged_disclosure": false },
  "expires_at": "2026-07-29T20:32:00Z" }

GET /v1/verifit/templates returns presets (quality, routine, missing) that pass the validator, as {object: "list", data: […], has_more: false}; {document} is the only interpolation token. Custom copy is accepted and validated identically. GET /v1/verifit/links/{id} and POST /v1/verifit/links/{id}/revoke manage a link; status ∈ pending · consumed · expired · revoked. In production the link is backed by the live Verifit service and the GET reflects its live status — a session consumed or abandoned out of band shows up on the next read; in the sandbox a deterministic fixture stands in for that service.

image/png — the QR encoding the link's url, for printing or for a desktop hand-off to the claimant's phone. This is what qr_png_url points at. Authenticated like every other endpoint; an unknown link is 404 not_found.

{ "id": "vfc_77a2", "object": "verifit_capture", "status": "completed",
  "link_id": "vfl_4c81",
  "document_id": "doc_9f2c1a",              // the ORIGINAL submission
  "recaptured_document_id": "doc_be40f2",   // an ordinary Document — GET /v1/documents/{id}
  "captured_at": "2026-07-27T20:32:07Z", "response_time": "PT6M14S",
  "device": "iPhone 15 Pro · rear camera", "photo_count": 2,
  "headline": "Authentic capture — and it contradicts the submitted upload",
  "c2pa": { "spec_version": "2.3", "validation_state": "Trusted",
            "signature_alg": "ES256", "timestamp_authority": "RFC3161",
            "edits_since_capture": 0, "manifest_url": "…" },
  "signal_groups": [
    { "id": "provenance",       "signals": [ { "label": "Signature", "value": "ECDSA P-256 · valid", "status": "pass" } ] },
    { "id": "device_integrity", "signals": [ … ] },
    { "id": "forensics_rerun",  "signals": [ … ] },
    { "id": "reconciliation",   "signals": [ { "label": "Ending balance — re-captured", "value": "$10,521.19", "status": "flag" } ] }
  ],
  "contradicts_original": true }

application/json — the same object as VerifitCapture.c2pa on its own, so an auditor can fetch the provenance without the reconciliation around it. This is what c2pa.manifest_url points at. Authenticated; an unknown capture is 404.

The four signal_groups ids are stable; signals within a group are additive, and each carries status ∈ pass · flag · unavailable. validation_state uses C2PA's own vocabulary so it can be checked against that spec rather than against our wording.

Webhooks

Configure an HTTPS endpoint in the dashboard (or per-request via webhook_url). The payload embeds the full object — no follow-up GET needed.

POST /your/endpoint
X-ScamAI-Signature: t=1785182400,v1=5f8a…c21

{ "id": "evt_7d31", "type": "document.completed",
  "created_at": "2026-07-27T20:12:09Z",
  "data": { "id": "doc_9f2c1a", "verdict": "FORGED", "…": "…" } }

Verify before trusting: recompute HMAC-SHA256 of <t>.<raw body> with your signing secret, compare to v1 in constant time, and reject if |now − t| > 300 s.

const [t, v1] = sig.split(",").map(kv => kv.split("=")[1]);
const expect  = crypto.createHmac("sha256", process.env.SCAMAI_WEBHOOK_SECRET)
                      .update(`${t}.${rawBody}`).digest("hex");
const valid   = crypto.timingSafeEqual(Buffer.from(expect), Buffer.from(v1))
                && Math.abs(Date.now()/1000 - t) < 300;

Current build: only document.completed, audit_report.completed, verifit.capture.completed and loan.coverage_complete are emitted — the *.failed and verifit.link.expired events are defined for forward compatibility. loan.coverage_complete fires from the expected-documents declaration. Treat the webhook as a nudge and GET the object for its final state rather than trusting the embedded payload to be terminal.

Audit reports & evidence

Aggregates a loan file's completed documents into the exportable Fraud Audit PDF (documents screened, findings, hashes, math checks). Pass {"external_ref": "loan_84620"} or an explicit document_ids array. Returns 202; if no completed documents match, 400 invalid_request — nothing to report on. Accepts Idempotency-Key: a replay returns the stored report with Idempotency-Replayed: true rather than minting a second one. On completion, download_url points at the download endpoint below and does not expire. coverage appears only on reports created with external_ref.

1.1 adds format ∈ pdf (default, unchanged response) · json · both. The JSON forms carry the same evidence the PDF prints, machine-readable:

POST /v1/audit-reports   { "external_ref": "loan_84620", "format": "both" }

→ { "id": "rpt_2a71", "object": "audit_report", "status": "completed",
    "documents_screened": 36, "documents_flagged": 3, "pages": 5,
    "generated_at": "2026-07-27T21:04:11Z",
    "models": [ { "name": "eva-doc", "version": "2.6" },
                { "name": "docforge", "version": "2.6" } ],
    "coverage": { "expected_total": 36, "screened": 36, "unscreened": 0, "complete": true },
    "findings": [ { "document_id": "doc_9f2c1a", "verdict": "FORGED", "risk_score": 87,
                    "headline": "ending balance digitally altered after initial save",
                    "indicators": [ … ], "math_checks": [ … ],
                    "metadata_anomalies": [ … ], "review_disposition": "escalated" } ],
    "manifest": [ { "document_id": "doc_9f2c1a", "name": "25 (4).pdf", "category": "bank_statement",
                    "verdict": "FORGED", "risk_score": 87, "sha256": "e10c2473…" } ],
    "manifest_digest": "9d4f…",
    "manifest_digest_algorithm": "sha256-of-sorted-sha256-newline-joined",
    "download_url": "https://api.scam.ai/v1/audit-reports/rpt_2a71/download?sig=9d4f…" }

• findings[] carries exactly the indicators, math checks and metadata anomalies the Document carried — nothing is re-derived for the report, so a reviewer cross-checking the PDF against the evidence panel sees identical values.
• manifest[] lists every document in the report, including those with no findings. That is the coverage attestation; coverage states it against the declared set.
• manifest_digest folds the file set into one value a loan buyer can recompute independently.

The digest construction is specified exactly, because a value that cannot be recomputed is not evidence:

It is independent of generation time: regenerating a report over the same file set with the same model versions reproduces the same digest.

The file download_url points at. Authenticated like every other endpoint — send your key. Served as application/pdf with Content-Disposition: attachment; filename="<report id>.pdf".

The sig query parameter is the first 16 hex characters of manifest_digest. It is derived from the document digests, so it is stable, non-secret and does not expire: it names the file set, it does not authorise the download. A report is a fraud finding about a borrower, so the key is required and the link cannot be forwarded to someone outside the account.

Errors

Every error response is this envelope — one error member, nothing at the top level. type is the coarse class, code the stable machine key to branch on.

{ "error": { "type": "invalid_request",
             "code": "message_would_disclose_flag",
             "message": "…",
             "doc_url": "https://docs.scam.ai/errors/message_would_disclose_flag",
             "matched_terms": ["fraud"] } }

doc_url is always present. Context keys (e.g. matched_terms) are added inside error, alongside the standard four — read them from body.error.matched_terms, never from body.matched_terms.

Rate limits

Each key is a token bucket: 600 requests per minute sustained with a burst of 1,200 (per the commercial agreement; raised on request). A key that has been idle can send 1,200 requests at once, then 10 per second — the allowance refills continuously, so a caller holding under 10/s never sees a 429.

X-RateLimit-Limit reports the burst capacity, not the per-minute refill: it is the most the key can spend at one instant. X-RateLimit-Remaining is what is left in the bucket and X-RateLimit-Reset the seconds until it is full again (on a 429, the seconds until the next request will be accepted). Every response also carries X-CheckReality-Env (sandbox | production) and X-Response-Time-Ms, plus X-Request-Id, X-Correlation-Id and, usually, X-Trace-Id; quote X-Request-Id (and the doc_ id) when you contact us about a request. On 429, back off per Retry-After; submissions are safe to retry with the same Idempotency-Key.

Versioning & forward compatibility

The path version (/v1) changes only for breaking changes, with ≥ 6 months of parallel support. Within v1, changes are additive — spec 1.3 is the latest example (a new verdict value and new response fields). Additive means new paths, new optional request fields, new response fields and new enum members, with nothing removed or reshaped. Build your client to these three rules and new detectors will never break you:

1. Tolerate unknown fields — new response fields may appear at any time.
2. Treat enums as open — new indicator.code, error.code, and model values will ship; render unknown indicators generically from title + severity.
3. Contract vs. copy — code, severity, verdict, risk_score, and coordinates are stable machine surface; what_it_is / what_it_means / how_detected / headline are display copy and may be reworded without notice. Never parse them.

Sandbox & go-live

Sandbox keys score real documents with the real engines — the next release, before production gets it (§2026-10-26). There is no sample corpus and file names carry no meaning: a file called 25 (4).pdf is scored, not recognised, and renaming a document never changes its verdict. Send your own documents — that is what the sandbox is for.

Sandbox-only helper: POST /v1/verifit/links/{id}/simulate-capture produces a completed borrower capture end-to-end and answers 201, so you can integration-test verifit.capture.completed and GET /v1/verifit/captures/{id} without a phone. Where the deployment is backed by the live Verifit service it answers 409 sandbox_only ("This endpoint is only available in the sandbox environment.") and creates nothing. A link already used is 409 link_already_consumed; one past expires_at is 410 link_expired.

Current sandbox build limitations

Contract semantics unchanged — these will close before GA:

• Every document is queued and scored by a worker — sandbox and production alike. A native PDF of a few pages is usually completed within seconds; a scanned or photographed page takes longer because the engine first reads its text with OCR. ?wait=true behaves as documented in both cases.
• POST /documents/{id}/reprocess re-scores from the file supplied with the request: attach the original document as multipart file — no file answers 400 source_file_required, a sha256 mismatch 400 invalid_request — and one still queued or running answers 409 analysis_in_progress — wait for completed or failed, then reprocess.
• VerifitLink.qr_png_url and c2pa.manifest_url serve the sandbox fixture's QR and manifest — deterministic stand-ins, not a real capture.
• Sandbox state is durable (Postgres + object storage, as in production): ids, verdicts and loans survive a redeploy.

Go-live checklist:

• Webhook endpoint verifies signatures and dedupes on event id; unknown event types are ignored rather than rejected.
• external_ref attached to every submission — without it, listing, loan rollups and audit reports cannot group documents. This is the single most important field.
• category sent where known. Leave models at its default: the file's content chooses the engine, not this option.
• Unknown indicator codes render generically from title + severity — never branch on a closed code list.
• 429/5xx retries use Idempotency-Key.
• Score-routing thresholds signed off by your compliance team — routing is client-side policy (§Queue).

If you are adopting the 1.1 surface, two additions are worth wiring at the same time: call PUT /v1/loans/{external_ref}/expected-documents when the loan's document checklist is known, or the coverage claim stays unevidenced; and send attribution on submissions that substantiate an asset or income figure, or flagged_amount is never present.

Questions during implementation: dennisng@scam.ai · shared Slack channel to be set up at kickoff.

Code reference

The codes a Document can carry, listed here so you need not call anything to read them. Both lists are open: tolerate a code you do not know, and render an unknown indicator from its title and severity.

Reason codes (reason_codes)

UPPERCASE routing codes: what to ask for and why — never a finding. "Where" says which estate emits it.

Indicator codes (indicators[].code, checks_passed)

One public code per docforensics check, with the engine's identifier. Severity is what an indicator carries on a flagged document; beside a CLEAN verdict, and on a note saying what kind of document this is, it is low. Titles are the sandbox engine's — three read differently on production (§2026-10-15); render the title the response carries. checks_passed uses the same codes, plus image_assessment on a CLEAN image-forensics answer. Documents scored by the earlier engine (eva-doc) carry that engine's own codes, which are not listed here.