Reading fraud and control checks

Gate downstream work on the document's integrity signals.

Goal. Read the fraud-detection signals attached to a completed extraction, and use them to decide whether downstream processing should continue.

Fraud rules are configured in the portal. The API does not expose rule management — but a completed extraction record carries the results, which is what an automated gate actually needs.

Before you start

• An API key, exported as $DOCAI_API_KEY.

• A completed asynchronous extraction and its _id — see Extract asynchronously and poll. The record retrieved by GET /document-extractions/{id} carries fraud results; the synchronous response does not.

• Fraud rules configured for the document type — see Fraud Detection.

Step 1 — Retrieve the extraction record

curl -s "https://api-docai-uat.uptiq.ai/document-extractions/$ID" \
  -H "X-Api-Key: $DOCAI_API_KEY" -o record.json

jq '.extraction.fraudResults' record.json

{
  "fraudId": "d40f8b63-15ce-42a9-b806-9f37c2e6a851",
  "extractionId": "3f2a91c4-7b58-4e12-9d63-0a5e8c1b74df",
  "documentType": "BalanceSheet",
  "fraudStatus": "processing",
  "analysisStatus": "pending",
  "preflight": {
    "phase": "pre_ocr",
    "overallScore": 100.0,
    "genericRulesEvaluated": 15,
    "processingTimeMs": 25549,
    "categoryScores": {
      "compliance":         { "total": 6, "passed": 0, "failed": 0, "skipped": 6, "score": 0.0 },
      "social_engineering": { "total": 3, "passed": 1, "failed": 0, "skipped": 2, "score": 33.33 },
      "visual_forensic":    { "total": 9, "passed": 4, "failed": 0, "skipped": 5, "score": 44.44 }
    },
    "results": [ ],
    "errors": []
  }
}

Step 2 — Wait for fraud analysis to finish

This is the part that catches people out.

Processed on the extraction does not mean fraud analysis is done. In our test run, the extraction reached Processed while fraudStatus still read processing and analysisStatus still read pending. Fraud analysis continues after extraction completes.

Reading fraudResults the moment the extraction goes terminal gives you a partial answer — and a partial answer that looks complete, because the object is fully populated with preflight data.

Check the fraud state separately from the extraction state:

jq -r '.extraction.fraudResults | "\(.fraudStatus)/\(.analysisStatus)"' record.json

Treat fraudStatus values other than a terminal one as "not yet decided", and re-poll the record. If your gate cannot wait, fail closed — hold the document for review rather than passing it on an incomplete signal.

Step 3 — Read the category scores

Preflight checks are grouped into three categories:

Category	Looks for
visual_forensic	Tampering evidence — inconsistent fonts, edited regions, missing print or export artifacts
compliance	Whether the document carries what its type is required to carry
social_engineering	Patterns associated with documents constructed to deceive

Each reports total, passed, failed, skipped and a score.

A low score is not evidence of fraud. In the run above, compliance scored 0.0 with all six rules skipped — nothing failed. Rules skip when the document lacks what they need to evaluate, which is common for sparse or synthetic documents.

Gate on failed, not on score. A score depressed by skips means "could not assess", which is a different decision from "assessed and failed".

Step 4 — Read individual rule results

jq '.extraction.fraudResults.preflight.results[] | {ruleId, status, category}' record.json

{
  "ruleId": "bs-export-footprints-timestamps",
  "status": "SKIP",
  "category": "visual_forensic",
  "name": "Export Footprints: Printed/Export Timestamps Consistency",
  "details": {
    "explanation": "No 'Date Printed' or 'Time Exported' stamps are visible on page 1, so consistency cannot be evaluated.",
    "fieldsUsed": ["footer area", "header area", "all visible text"],
    "actualValues": { "visual_evidence": "No export or print timestamps present" },
    "expectedValues": {},
    "missingFields": [],
    "riskFactors": []
  }
}

status is PASS, FAIL or SKIP. details.explanation is written for a human — surface it in your review queue rather than paraphrasing it, and keep riskFactors where a reviewer can see them.

Step 5 — Build the gate

FAILED=$(jq '[.extraction.fraudResults.preflight.results[]
              | select(.status == "FAIL")] | length' record.json)

if [ "$FAILED" -gt 0 ]; then
  echo "$FAILED fraud rule(s) failed — holding for review"
  jq -r '.extraction.fraudResults.preflight.results[]
         | select(.status == "FAIL")
         | "  \(.ruleId): \(.details.explanation)"' record.json
  exit 1
fi

A defensible policy has three outcomes rather than two: pass when nothing failed and coverage was adequate, review when rules failed or too many skipped to be meaningful, and reject only on the failures your risk team has agreed warrant it.

What you cannot do through the API

Not available	Do it here
Create or edit fraud rules	Document Types → Fraud Detection — see Fraud Detection
Enable or disable rules per document type	Same screen
Export a certification report	Document Types screen
Query fraud results independently of an extraction	Retrieve the extraction record

There is no fraud endpoint in the published API. Everything above reads results that ride along on the extraction record.

Related pages

• Fraud Detection — configuring the rules these results come from.

• Extract asynchronously and poll — obtaining the record in the first place.

• Extraction API — GET /document-extractions/{extraction_id}.