> ## Documentation Index
> Fetch the complete documentation index at: https://developers.resistant.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Core integration mechanics

<Note>
  New to the API? Start with [Quickstart API](/getting-started/quickstart-api). This page is a detailed reference for production-grade integrations.
</Note>

## Base URL

Use the **stage/cell-specific** base URL for your tenant.

* Stage and cell mapping: see [Concepts](/getting-started/concepts)
* Token URL mapping: see [Getting an access token](/getting-started/getting-access-token)

***

## Step 1 — Create a submission

**`POST /v2/submission`**

Creates a new submission record and returns:

* a unique `submission_id`
* a presigned `upload_url` for uploading the file bytes

### Request headers

```text theme={null}
Authorization: Bearer <access_token>
Content-Type: application/json
```

### Request body (optional)

```json theme={null}
{
  "query_id": "your-internal-document-id",
  "pipeline_configuration": "FRAUD_ONLY",
  "enable_decision": false,
  "enable_submission_characteristics": false
}
```

| Field                               | Type            |      Default | Notes                                                                  |
| ----------------------------------- | --------------- | -----------: | ---------------------------------------------------------------------- |
| `query_id`                          | string (0–1024) |       `null` | Optional correlation ID. Must not contain PII.                         |
| `pipeline_configuration`            | enum            | `FRAUD_ONLY` | Selects which pipeline runs for this submission.                       |
| `enable_decision`                   | boolean         |      `false` | Enables Adaptive Decision (if available for your tenant).              |
| `enable_submission_characteristics` | boolean         |      `false` | If `true`, characteristics must be submitted before analysis proceeds. |

### Pipeline configuration values

| Value                 | Description                      |
| --------------------- | -------------------------------- |
| `FRAUD_ONLY`          | Run fraud analysis (default)     |
| `CLASSIFICATION_ONLY` | Run document classification only |
| `QUALITY_ONLY`        | Run quality analysis only        |

<Note>
  This enum selects a single pipeline. If you need multiple outputs, retrieve them from the corresponding endpoint(s) or use an agreed configuration provided during provisioning.
</Note>

### Response — 200 OK

```json theme={null}
{
  "submission_id": "sub_abc123xyz",
  "upload_url": "https://bucket.s3.amazonaws.com/...",
  "submission_characteristics_upload_url": "/v2/submission/sub_abc123xyz/characteristics"
}
```

| Field                                   | Description                                                                     |
| --------------------------------------- | ------------------------------------------------------------------------------- |
| `submission_id`                         | Unique identifier for this submission. Store it — used in all subsequent calls. |
| `upload_url`                            | Presigned URL for uploading the document bytes (Step 2).                        |
| `submission_characteristics_upload_url` | Present only when submission characteristics are enabled.                       |

***

## Step 2 — Upload the document bytes

Upload the original file bytes to the presigned `upload_url` using HTTP `PUT`.

### Upload request

```bash theme={null}
UPLOAD_URL="<upload_url_from_step_1>"
FILE_PATH="/path/to/your/document.pdf"

curl --request PUT \
  --url "$UPLOAD_URL" \
  --header "content-type: application/octet-stream" \
  --data-binary @"$FILE_PATH"
```

### Upload rules

* Method must be `PUT`
* `Content-Type` must be `application/octet-stream`
* Upload the **original bytes** (do not base64 encode or re-render)
* The presigned URL expires — upload promptly after creating the submission

<Tip>
  If upload fails, validate your outbound allowlist and proxy rules: see [Domains to allowlist](/getting-started/domains-to-allowlist).
</Tip>

***

## Step 3 — Submit submission characteristics (optional)

**`PUT /v2/submission/{submission_id}/characteristics`**

If you created the submission with `enable_submission_characteristics: true`, you **must** submit characteristics before analysis proceeds.

<Warning>
  Do not enable submission characteristics unless you intend to send them for every submission. When enabled, they are required for that submission.
</Warning>

This page does not document the full schema (it is extensive and evolves). See:

* [Submission characteristics](/optional-features/submission-characteristics)

### Response — 204 No Content

Characteristics accepted — analysis will proceed.

***

## Step 4 — Fetch analysis results

Results are returned asynchronously. Fetch them by calling the relevant endpoint(s) for your pipeline and feature configuration.

### Polling semantics (important)

<Note>
  A `404` can mean “result not ready yet” **or** “not found” (e.g., wrong stage/cell, wrong `submission_id`). If `404` persists, verify you’re using the correct base URL for the same stage/cell where the submission was created.
</Note>

See [Polling for results](/receiving-results/polling) for recommended exponential backoff and timeouts.

***

## Fraud analysis

**`GET /v2/submission/{submission_id}/fraud`**

Returns fraud indicators and an overall risk score.

### Query parameters

| Parameter       | Type    | Default | Description                                                                               |
| --------------- | ------- | ------: | ----------------------------------------------------------------------------------------- |
| `with_metadata` | boolean | `false` | Includes extended indicator metadata (e.g., for UI visualization / localized detections). |

### Response (example)

```json theme={null}
{
  "status": "SUCCESS",
  "score": "NORMAL",
  "indicators": [
    {
      "indicator_id": "in_transaction_cluster",
      "type": "RISK",
      "category": "...",
      "title": "...",
      "origin": "fraud"
    }
  ]
}
```

**Fraud score values:** `NORMAL`, `TRUSTED`, `WARNING`, `HIGH_RISK`\
**Status values:** `SUCCESS`, `SKIPPED`, `INVALID_INPUT`, `FAILED`

***

## Quality analysis

**`GET /v2/submission/{submission_id}/quality`**

Returns document image/scan quality assessment.

**Quality score values:** `HIGH_QUALITY`, `LOW_QUALITY`, `NOT_RELEVANT_DOCUMENT`

***

## Document classification

**`GET /v2/submission/{submission_id}/classification`**

Returns the detected document type.

**Classification score values:** `CLASSIFIED`, `NOT_CLASSIFIED`, `DOCUMENT_MISSING`

***

## Adaptive Decision (customisable layer)

**`GET /v2/submission/{submission_id}/decision`**

Returns a tenant-specific decision. Available only when `enable_decision: true` and Adaptive Decision is configured for your tenant by Resistant AI team.

### Query parameters

| Parameter | Example | Description                                                                                                          |
| --------- | ------- | -------------------------------------------------------------------------------------------------------------------- |
| `embed`   | `fraud` | Embeds the `/fraud` result (e.g., indicators). For full fraud payload (including metadata), fetch `/fraud` directly. |

***

## Content extraction (limited access)

**`GET /v2/submission/{submission_id}/content`**

Returns extracted text/structured content. This endpoint applies only to selected document types from Czechia.

***

## Downloadable PDF report

**`GET /v2/submission/{submission_id}/report`**

Returns a download URL for a human-readable PDF fraud analysis report.

### Query parameters

| Parameter          |    Type | Description                                     |
| ------------------ | ------: | ----------------------------------------------- |
| `include_decision` | boolean | Include Adaptive Decision result in the report. |

<Note>
  Returns `409 Conflict` if fraud analysis or adaptive decision was not completed successfully or was skipped.
</Note>

***

## Feedback

**`PUT /v2/submission/{submission_id}/feedback`**\
Stores analyst feedback for the submission.

**`GET /v2/submission/{submission_id}/feedback`**\
Retrieves previously stored feedback.

<Warning>
  All custom feedback must be reviewed before submission to ensure it does not contain PII.
</Warning>

***

## Delete a submission

**`DELETE /v2/submission/{submission_id}`**

Permanently deletes the submission and associated data before the configured retention period.

<Note>
  Returns `409 Conflict` if the submission is still being processed.
</Note>

***

## Common HTTP error codes

| Code  | Meaning                | Recommended action                                                   |
| ----- | ---------------------- | -------------------------------------------------------------------- |
| `400` | Bad request            | Validate request body / parameters                                   |
| `401` | Unauthorized           | Verify token is valid and not expired                                |
| `403` | Forbidden              | Verify scopes/permissions for the tenant/app                         |
| `404` | Not found / not ready  | Retry with backoff; verify stage/cell + submission\_id if persistent |
| `409` | Conflict               | Retry later (e.g., delete while processing)                          |
| `415` | Unsupported media type | Ensure correct `Content-Type`                                        |
| `429` | Too many requests      | Back off + retry (exponential backoff + jitter)                      |

<Tip>
  For retry and timeout guidance, see [Limits & quotas](/support/limit-and-quotas) and [Polling for results](/receiving-results/polling).
</Tip>