Getting Started

Verify your first document in under five minutes using the trial sandbox or API key.

1. Get access

• Trial UI: open /try — upload a file, inspect JSON + evidence lifecycle
• API key: request via /api-trial — key sent by email

2. Authenticate

Production integrations use Bearer auth:

Authorization: Bearer YOUR_API_KEY

Trial multipart uploads may also pass api_key form field or X-API-Key header.

3. First request (image)

curl -s -X POST "https://api.plicaforensic.com/api/v1/verify" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "image=@passport_scan.jpg" \
  -F "detail_level=detailed" \
  -F "preserve_exif=true" \
  -F "document_type=passport"

4. First request (document scan via messaging app)

curl -s -X POST "https://api.plicaforensic.com/api/v1/verify" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "image=@whatsapp_scan.jpg" \
  -F "detail_level=detailed" \
  -F "preserve_exif=true" \
  -F "document_type=utility_bill"

preserve_exif=true is required for document-scan routing (Layer 1 edit maps, sterile EXIF handling). Trial sandbox (/try) sends this automatically.

5. First request (PDF)

curl -s -X POST "https://api.plicaforensic.com/api/v1/verify" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "image=@bank_statement.pdf" \
  -F "detail_level=detailed" \
  -F "document_type=bank_statement"

image field accepts JPEG, PNG, HEIC, WebP, and PDF (max size per server config).

6. Read the response

Key fields to integrate first:

• verdict, fraud_score, confidence
• analyst_summary.verdict_tier — presentation tier for HITL routing
• analyst_summary.policy_actions — typed actions for agents
• forensic_view.claim_lists — critical / review / clean triage
• forensic_view.risk_signals — human-readable tag explanations
• forensic_view.risk_tags — flat machine tag list
• details.tamper_regions — localized edit candidates (document scans)
• evidence_lifecycle — custody manifest

Details: Response format

7. Bulk / async (batch)

For multiple files or long-running PDFs, use async jobs instead of holding a sync connection:

curl -s -X POST "https://api.plicaforensic.com/api/v1/jobs/batch" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "files=@doc1.pdf" \
  -F "files=@doc2.pdf" \
  -F "detail_level=basic" \
  -F 'additional_info={"case_ref":"48291"}'

Poll GET /api/v1/jobs?batch_id=… or fetch each result at GET /api/v1/jobs/{job_id}/result. Full cookbook: Async /jobs (cURL + Python).

8. Optional: policy webhooks

Dispatch policy_actions to Slack or n8n after verification. See repo guide policy-enforcement-integration-guide.md.

Limits (typical trial)