Concepts

Background jobs

Work that takes longer than a request, and how to know when it's done.

Reading a receipt, matching a bank line or preparing an export can take longer than one request should. Actions that start this kind of work answer right away with the job's ID and its current status, and the work carries on in the background.

uploads.confirm response

{
  "data": {
    "submissionId": "4d5e6f7a-8b9c-4d0e-8f1a-2b3c4d5e6f7a",
    "jobId": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
    "generation": 1,
    "status": "queued"
  }
}

Following a job

There are two ways to know when a job finishes:

Ask. Call the job's status action, such as jobs.get for receipts, every few seconds until status is completed or failed. Wait a little longer between each check.
Listen. Subscribe to a webhook, such as receipt.processed, and Oatmilk tells you when it's done.

{
  "data": {
    "id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
    "submission_id": "4d5e6f7a-8b9c-4d0e-8f1a-2b3c4d5e6f7a",
    "status": "queued",
    "stage": "preserve",
    "generation": 1,
    "attempts": 0,
    "error_code": null,
    "next_attempt_at": "2026-09-30T14:00:05Z"
  }
}

{
  "data": {
    "id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
    "submission_id": "4d5e6f7a-8b9c-4d0e-8f1a-2b3c4d5e6f7a",
    "status": "processing",
    "stage": "extract",
    "generation": 1,
    "attempts": 1,
    "error_code": null,
    "next_attempt_at": "2026-09-30T14:00:05Z"
  }
}

{
  "data": {
    "id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
    "submission_id": "4d5e6f7a-8b9c-4d0e-8f1a-2b3c4d5e6f7a",
    "status": "completed",
    "stage": "match",
    "generation": 1,
    "attempts": 1,
    "error_code": null,
    "next_attempt_at": "2026-09-30T14:00:05Z"
  }
}

What the statuses mean

Status	Means
`queued`	Accepted and waiting its turn. Nothing is finished yet.
`processing`	Being worked on now. `stage` says which step.
`completed`	Done. Read the record to see the result.
`failed`	Stopped after its retries. `error_code` says why; a person can retry it in Oatmilk.