Skip to main content
This page explains the core concepts you’ll see throughout the Documents API documentation.

Quickstart API

Create a submission → upload → retrieve results.

Get an access token

OAuth2 client credentials across stages and cells.

Receiving results

Polling (default) or optional notifications (SQS / webhooks).

View results in the UI

Web UI and Offline iFrame viewer options.

​
End-to-end integration model

The typical lifecycle looks like this:
If you’re integrating for the first time, follow the Quickstart API. It walks you through the full flow end-to-end.

​
Key identifiers

​
submission_id

A server-generated identifier returned when you create a submission. It is the primary identifier used to:
  • fetch results (fraud / quality / classification / decision)
  • deep link into the Web UI
  • delete a submission

​
query_id

An optional, customer-defined identifier you provide at submission creation time. Use it to correlate results with your internal system (e.g., case ID or document record ID).
Ensure query_id does not contain PII. Use opaque internal IDs (UUIDs) instead of emails, names, phone numbers, etc.

​
Environments

​
Stage

  • Production: live processing
  • Testing: used to validate integration behavior before go-live (limited to EU region)

​
Cell

A short identifier used in hostnames to indicate the deployment “cell”, such as:
  • eu-1 (no hostname prefix)
  • us-1, ca-1, ap-2, ap-3 (appear as hostname prefixes)
Example:
  • EU prod API: api.documents.resistant.ai
  • US prod API: api.us-1.documents.resistant.ai

​
AWS region (storage endpoints)

S3 upload/download endpoints use standard AWS region identifiers (e.g., eu-west-1, us-east-1).
Always keep your API base URL, token URL, and allowlist aligned to the same stage + cell.

​
Pipelines and results

When creating a submission, you choose which analysis pipeline to run via pipeline_configuration:
  • FRAUD_ONLY: run fraud pipeline (default)
  • CLASSIFICATION_ONLY: run classification only
  • QUALITY_ONLY: run quality only
Results are retrieved from these endpoints (depending on what you enabled/consume):
  • Fraud result: GET /v2/submission/{submission_id}/fraud
  • Quality result: GET /v2/submission/{submission_id}/quality
  • Classification result: GET /v2/submission/{submission_id}/classification
  • Adaptive Decision result: GET /v2/submission/{submission_id}/decision
  • PDF report: GET /v2/submission/{submission_id}/report

​
Result status model (terminal states)

Result endpoints return a response with a status field. Treat these as terminal states:
  • SUCCESS: results are available
  • FAILED: processing failed during backend analysis
  • INVALID_INPUT: document could not be processed (e.g., unsupported or malformed)
  • SKIPPED: the step did not run (commonly due to pipeline configuration)
Your integration should stop polling once a terminal status is returned and handle the outcome in your workflow (e.g., manual review on FAILED/INVALID_INPUT).
Adaptive Decision responses may also include INVALID_PIPELINE_CONFIG when a required pipeline input is missing.

​
Receiving results: polling vs notifications

​
Polling (default)

Most customers retrieve results by polling the relevant endpoint(s) until a terminal status is returned. Recommended approach:
  • exponential backoff
  • cap interval at 45 seconds
  • stop after 15 minutes (hard analysis timeout)

​
Optional notifications

Instead of polling, some customers use:
  • Amazon SQS event notifications (optional add-on)
  • Webhooks via Svix (optional add-on)
These options notify your system when processing completes and include a pointer (URL/endpoint) to fetch full results.

​
Viewing results

​
Web UI

A hosted browser-based UI used by investigators/analysts to review results, indicators, and document previews. Deep link format 
https://<tenant>-<org>.documents.resistant.ai/analysis/<submission_id>
See: View results in the UI

​
Offline iFrame viewer

A self-hosted viewer that renders results in your environment. You provide:
  • the original file bytes (ArrayBuffer)
  • result payloads via postMessage():
    • fraud (required)
    • decision (optional)
    • classification (optional)
The Offline iFrame viewer requires provisioning and is enabled by agreement. Do not treat it as a public, self-serve asset.
See: View results in the UI

​
Optional features that affect the model

​
Submission characteristics

Submission characteristics are optional metadata attached to a submission (device, identity, transaction context, etc.). Important behavior:
  • if you set enable_submission_characteristics=true at submission creation time, then providing characteristics becomes required for that submission to be analyzed.

​
Payload encryption

Optional end-to-end encryption of uploaded file bytes (JWE) for additional protection beyond TLS. It changes the upload payload format but does not change the submission/result flow.

​
Delete submission

You can delete a submission via:
  • DELETE /v2/submission/{submission_id}
Use this to delete data earlier than your configured retention period.

​
Common misunderstandings

No. You upload the file bytes to the presigned upload_urlreturned from “Create submission” using HTTP PUT with Content-Type: application/octet-stream
No. Upload the original file bytes.
Don’t. Reuse the token until it expires (expires_in) to avoid unnecessary token endpoint load.
Yes. Token URLs are environment-specific. Always use the token URL provided for your stage + cell.