# Processor

The processor reads a deal's documents — bank statements, applications, tax returns, credit
reports and more — and answers what is still missing, how each bank statement scores for fraud,
which lenders fit, and the deal's headline financials.

## Pick the way in

| You have | Use |
| --- | --- |
| Documents arriving by email | Send them to `processor@spectersystems.io` from your workspace — no key |
| A server or script holding the files | [A processing key](/processor/create-a-key) and [the job routes](/processor/send-documents) |
| Deals already on your Deals page | [A Deals key](/processor/create-a-key) and [the deal routes](/processor/process-a-deal) |

Every way in files the same job in your workspace, so a document gives the same answer whichever
way it came.

<Callout type="warning" title="A key never goes in a browser">
  A processing key spends money and reads your deals' documents. Keep it on a server, in an
  environment variable or a secret manager.
</Callout>

## How a job runs

<Steps>
  <Step title="Declare the files">
    [`POST /v1/api/jobs`](/processor/send-documents) with each file's name, type and size. The answer carries one upload URL per file.
  </Step>
  <Step title="Upload the bytes">
    `PUT` each file straight to its URL. The bytes never pass through the API.
  </Step>
  <Step title="Start it">
    [`POST /v1/api/jobs/{id}/start`](/processor/send-documents#3-start-the-job) hands the files to the processor.
  </Step>
  <Step title="Read the results">
    [`GET /v1/api/jobs/{id}`](/processor/read-results) until `state` is final — then the findings and financials are in the same answer.
  </Step>
</Steps>

## The routes

| Route | Scope | Does |
| --- | --- | --- |
| [`POST /v1/api/jobs`](/processor/send-documents) | `processing` | Declare a job's files; answers upload URLs |
| [`POST /v1/api/jobs/{id}/start`](/processor/send-documents#3-start-the-job) | `processing` | Start processing |
| [`GET /v1/api/jobs/{id}`](/processor/read-results) | `read` | State, files, the job's progress, findings and financials — one call |
| [`GET /v1/api/jobs`](/processor/read-results#list-your-jobs) | `read` | The newest jobs on the key's page, paged |

The routes under `/v1/ingest/rows/{rowId}/…` do the same for a deal that is already on your Deals
page — see [Process a deal](/processor/process-a-deal).

Keys, errors and rate limits follow the rules every Specter route shares:
[Authentication](/authentication), [Errors](/errors), [Rate limits](/rate-limits).
