Quickstart

Submit a document, get an id, and poll until analysis completes.

Detect forged, tampered, and AI-generated documents. Upload a PDF or image and get back a decision (clear / pending / suspicious / fraudulent), a risk_level, a plain-language summary, and a list of structured flags.

Analysis takes longer than a normal HTTP request (often 10-60s), so the API is async by default: submit returns an id immediately, then you poll until it finishes.

1. Create an API key

   Sign in, open Settings, and generate an API key for your workspace.

2. Submit a document

   POST /api/v1/document-checks/ with either a multipart file or a JSON url. The response is 201 with an id and status: "processing".

3. Poll until complete

   GET /api/v1/document-checks/{id}/ until status is completed or failed.

Example

# 1. Submit
curl https://api.sphinxhq.com/api/v1/document-checks/ \
  -H "Authorization: Bearer $SPHINX_API_KEY" \
  -F file=@statement.pdf \
  -F mode=normal

Response (201):

{
  "id": "dc_01jq8x...",
  "object": "document_check",
  "status": "processing",
  "decision": null,
  "flags": [],
  "document": { "filename": "statement.pdf", "mime_type": "application/pdf" }
}

# 2. Poll
curl https://api.sphinxhq.com/api/v1/document-checks/dc_01jq8x.../ \
  -H "Authorization: Bearer $SPHINX_API_KEY"

When status is completed, the same object is filled in with decision, summary, and flags. See The result model.

Alternatives to polling

Option	When to use
Poll GET /{id}/	Default path.
webhook_url on submit	We POST the completed check to your URL. See Webhooks.
?wait=true on submit	Blocks the submit request for up to 55s.

Modes

Mode	Behavior
normal	Default. Balanced precision/recall.
strict	More aggressive: prefer catching fraud over false clears.
lenient	Prefer clears when signals are weak.

Listing checks

GET /api/v1/document-checks/ returns your checks newest first, in a data array with a has_more boolean. Page with limit (1-100, default 20) and starting_after:

curl "https://api.sphinxhq.com/api/v1/document-checks/?limit=20" \
  -H "Authorization: Bearer $SPHINX_API_KEY"

# next page: pass the last id from the previous one
curl "https://api.sphinxhq.com/api/v1/document-checks/?limit=20&starting_after=dc_01jq8x..." \
  -H "Authorization: Bearer $SPHINX_API_KEY"

Next

• Authentication
• Rules
• Flag reference
• Webhooks