# Send documents

Three calls: declare the files, upload each one, start the job.

## 1. Declare the files

`POST /v1/api/jobs` · scope `processing`

```bash
curl -X POST https://neo-app-api-prod-836053680024.us-central1.run.app/v1/api/jobs \
  -H "Authorization: Bearer $SPECTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"files": [
        {"name": "march.pdf", "contentType": "application/pdf", "sizeBytes": 482113,
         "documentType": "bank_statement", "periodStart": "2026-03-01", "periodEnd": "2026-03-31"},
        {"name": "application.pdf", "contentType": "application/pdf", "sizeBytes": 91244}
      ]}'
```

A `201` answers the job's `id` and one upload URL per file. Nothing is processed yet — the bytes
aren't there.

```json
{"data": {"id": "5b1c2f0e-…", "state": "awaiting_start",
          "files": [{"id": "9f0e6a2b-…", "name": "march.pdf", "contentType": "application/pdf",
                     "sizeBytes": 482113, "documentType": "bank_statement",
                     "uploadUrl": "https://storage.googleapis.com/…"}, "…"]}}
```

| Field | Rules |
| --- | --- |
| `files` | 1–25 files. |
| `files[].name` | Required. |
| `files[].sizeBytes` | Required, more than 0. |
| `files[].contentType` | The file's type. Blank is `application/octet-stream`. |
| `files[].documentType` | Optional — what it is, if you know: `bank_statement`, `tax_return`, `application`, `credit_report`, `voided_check`, `drivers_license`, `id`, `contract`, `agreement`, `offer_letter`, `payoff_letter`, `invoice`, `statement_analysis`, `stip`, `signed_application`, `merchant_questionnaire`, `plaid_report`, `financials`, `profit_and_loss`, `balance_sheet`, `ucc_filing`, `business_license`, `articles_of_incorporation`, `insurance`, `lease`, `ar_report` or `other`. Leave it out and the processor classifies the file. |
| `files[].periodStart`, `files[].periodEnd` | Optional, `YYYY-MM-DD` — the span a statement covers. |
| `cells` | Optional — values for the deal's own columns, as strings, keyed by column label or id, as on [Boards](/boards/read-and-write). |

The file rules below are checked before anything is written, so a list they refuse leaves nothing behind.

| Refusal | Means |
| --- | --- |
| `at least one file is required` | `files` is empty. |
| `at most 25 files per job` | Split the documents across jobs, or send the most recent. |
| `every file needs a name and a positive sizeBytes` | A file is missing its name or size. |
| `documentType must be one of …` | An unknown type; the message lists the accepted ones. |

## 2. Upload each file

`PUT` the bytes to the file's `uploadUrl`, with the **same `Content-Type`** you declared — the URL
is signed for it, and a different type is refused. Each URL works for 15 minutes.

```bash
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: application/pdf" \
  --data-binary @march.pdf
```

The upload goes straight to storage; the key isn't sent and isn't needed.

## 3. Start the job

`POST /v1/api/jobs/{id}/start` · scope `processing`

```bash
curl -X POST https://neo-app-api-prod-836053680024.us-central1.run.app/v1/api/jobs/$JOB_ID/start \
  -H "Authorization: Bearer $SPECTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"productType": "mca"}'
```

Start only after every upload has finished: the processor fetches the files when it begins.

| Field | Rules |
| --- | --- |
| `productType` | Optional. The deal type — `mca`, `term_loan`, `line_of_credit`, `sba`, or one your workspace named. It picks what the processor counts as missing. |
| `idempotencyKey` | Optional. Your own key for this start. |
| `replace` | Optional. Consent to replace fields a person entered by hand — see `409` below. |

The body is optional; a bare `POST` starts the job.

| Status | Means |
| --- | --- |
| `201` | Started. `data` is `{id, state, created: true, job}`. |
| `200` | This job was already started with these files — `created: false`, and `job` is the one already running. Safe to call again. |
| `400` | The job has no documents to process. |
| `409` | `would_supersede`: processing would replace fields a person entered by hand. The answer lists them in `superseded`; send `"replace": true` to go ahead. |

Starting twice with the same files never starts a second job: without an `idempotencyKey` the job
is keyed by its files, so a retry answers the job already running. A retry that sends a *different*
`idempotencyKey` starts a second job — reuse the key, or leave it out.

Then [read the results](/processor/read-results).
