Document Forensics API Reference

Overview & lifecycle

Base URL: https://api.scam.ai/v1 (production, sk_live_ keys); sandbox is https://api-dev.scam.ai/v1 with an sk_test_ key — same API, same engine, unmetered. 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.

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.

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.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. 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, over size or page 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. 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 cached verdict at no charge. 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.

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 ("photo upload" label)
  "model": "eva-doc",
  "model_version": "2.6",             // the UI's V2.6 badge; changes on reprocess
  "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 of up to 10 fixed rows (Format, Pages, File size, Producer, Creator, Created, Modified, Incremental revisions, Fonts embedded, XMP metadata) whose value is a display string ("1.4 MB", "All 7 embedded"). anomalous is reserved — currently false on every row.
• math_checks is produced only for SUSPICIOUS/FORGED documents and only failing checks are emitted — an empty array means no contradiction was reported, not that totals were verified. formula is a plain-language summary; computed/stated are best-effort and may be empty.
• model reports the engine that scored the document — pdf-native-forensics or docforge-v14. The product names eva-doc / docforge are what you ASK for in options.models; they 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); 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 currently assigned from the file type — PDFs are native_pdf, images are photo; scan is reserved.

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

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.

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). Returns 202, status back to processing; the prior verdict stays readable until the new one lands. 409 file_not_retained if the bytes are not held. Resubmit instead.

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, 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 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. 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.1 is the current example: 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 same forensics engine production uses. 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 it is scored on a GPU. ?wait=true behaves as documented in both cases.
• POST /documents/{id}/reprocess re-scores the document; one whose bytes are not held answers 409 file_not_retained, 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, and models: ["docforge"] for photos and scans — eva-doc is the default and is the wrong model for a phone photo of a statement.
• 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.