Document Integrity API

Endpoints for detecting tampered, forged, or manipulated documents. For the concept and what each check does, see the Document Integrity guide.

Base path: /ocr

There are three ways to run a check:

1. During upload — set enable_fraud_check=true on /ocr/upload; fetch results later.
2. On an existing job — /ocr/jobs/{job_id}/trigger-fraud-check.
3. Standalone — /ocr/verify, no OCR extraction.

---

Get integrity results

GET /ocr/jobs/{job_id}/fraud-analysis

Fetches the integrity report for a job. Because checks run in the background, poll this after an upload with enable_fraud_check=true.

curl "https://netraocr.shivicx.com/api/v1/ocr/jobs/8f3c…/fraud-analysis" \
  -u "ak_live_xxxxxxxx:sk_live_xxxxxxxx"

Response 200 OK

{
  "job_id": "8f3c…",
  "fraud_check_status": "completed",
  "fraud_analysis": {
    "file_hash": "sha256:…",
    "risk_score": 18,
    "risk_level": "low",
    "is_suspicious": false,
    "requires_manual_review": false,
    "indicators": [
      { "name": "ela_tampering_detected", "detected": false, "risk_level": "low", "description": "Error Level Analysis" }
    ],
    "detected_issues": [],
    "summary": "No tampering indicators found.",
    "analyzed_at": "2026-06-16T10:31:00Z",
    "analysis_time_ms": 4200
  }
}

fraud_check_status	Meaning
pending	Queued, not started
processing	Running — poll again shortly
completed	Report available in fraud_analysis
failed	Errored
not_requested	No check was enabled for this job

Risk report fields

Field	Description
risk_score	Overall score, 0–100
risk_level	low / medium / high / critical
is_suspicious	true if the document appears tampered
requires_manual_review	true if human review is recommended
indicators	All checks analyzed
detected_issues	Only checks that flagged an issue
summary	Human-readable summary

---

Trigger a check on an existing job

POST /ocr/jobs/{job_id}/trigger-fraud-check

Runs an integrity check on a job that was processed without one. The original file is retrieved from storage and analyzed in the background; poll /fraud-analysis for the result.

curl -X POST "https://netraocr.shivicx.com/api/v1/ocr/jobs/8f3c…/trigger-fraud-check" \
  -u "ak_live_xxxxxxxx:sk_live_xxxxxxxx"

Returns a status payload (initially pending) while the check runs.

---

Verify a document (standalone)

POST /ocr/verify

Analyzes a document for tampering without running OCR extraction. Returns the risk report directly (synchronous).

curl -X POST "https://netraocr.shivicx.com/api/v1/ocr/verify" \
  -u "ak_live_xxxxxxxx:sk_live_xxxxxxxx" \
  -F "file=@suspicious.pdf"

The response is a risk report with the same risk_score, risk_level, indicators, and detected_issues fields as above.

---

List available checks

GET /ocr/fraud-checks/available

Returns the available integrity checks, grouped by category, with their default enabled state. Use the IDs to selectively disable checks when uploading (via disabled_fraud_checks).

curl "https://netraocr.shivicx.com/api/v1/ocr/fraud-checks/available" \
  -u "ak_live_xxxxxxxx:sk_live_xxxxxxxx"

Response 200 OK

{
  "pdf":   [ { "id": "pdf_metadata_mismatch", "name": "PDF metadata mismatch", "default": true } ],
  "image": [ { "id": "copy_move_forgery", "name": "Copy-move forgery", "default": true },
             { "id": "ela_tampering_detected", "name": "ELA tampering", "default": true } ],
  "ai":    [ { "id": "ai_visual_analysis", "name": "AI visual analysis", "default": true } ]
}

Category	Covers
pdf	PDF metadata & structure checks
image	Image forensics (ELA, copy-move, noise)
ai	AI-powered visual analysis

Disabling checks on upload

{
  "file_base64": "JVBERi0xLjQ…",
  "filename": "invoice.pdf",
  "enable_fraud_check": true,
  "disabled_fraud_checks": ["copy_move_forgery"]
}