---
title: "Submit a coding job"
method: POST
path: "/api/v1/codeiq/coding-jobs"
tags: ["CodeIQ"]
---

# Submit a coding job

`POST /api/v1/codeiq/coding-jobs`

## Request

- Base URL: `https://api.reconcileiq.com`
- URL: `https://api.reconcileiq.com/api/v1/codeiq/coding-jobs`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Runs the real CodeIQ coding pipeline over caller-supplied transactions against a caller-supplied chart of accounts. Async; poll `poll_url`.

**Strict format** (HTTP **422 `invalid_request_format`** on any deviation, with section/row/field detail):
- `transactions[]`: `{ date: 'YYYY-MM-DD' (real calendar date), description: 1..500, amount: signed finite number (money out negative), merchant?: <=200, reference?: <=100 }`.
- `chart_of_accounts[]`: `{ code: 1..50, name: 1..200, type: one of INCOME, EXPENSE, ASSET, LIABILITY, EQUITY (case-insensitive; REVENUE is accepted as an alias of INCOME) }`.
- `vat_codes[]` (optional): `{ code: 1..50, name: 1..200, rate: 0..100 }`. If omitted, the default UK universal set (ST/RR/ZR/EX/NV) is used.
- `options` (optional): `{ allowOverage?: boolean (default false), businessContext?: string <=2000 }`.

VAT codes returned are universal codes: `NV`, `ST`, `RR`, `EX`, `ZR`.

**Credits.** Cost equals the number of transactions, charged only on a successful completed run. Unaffordable at submit time returns 402 synchronously. Requires scope `codeiq:write`.

**Data minimisation.** The transient working session and the submitted transactions are deleted after the result is extracted; only the coded result is retained for polling.

## Request body

- CodingJobRequest
  - `transactions` object[], required
    - `date` string, date, required: Exact YYYY-MM-DD, real calendar date.
    - `description` string, required
    - `amount` number, required: Signed finite number; money out is negative.
    - `merchant` string
    - `reference` string
    - `bank_account` string: The account this line came from. Optional, but send it on every line whenever a batch covers more than one account: a transfer between two of your own accounts can only be identified when the two sides are distinguishable, so without it transfer detection cannot run and your transfers will be coded as ordinary income and expense. Up to 40 distinct accounts per job.
  - `chart_of_accounts` object[], required
    - `code` string, required
    - `name` string, required
    - `type` string, required: One of INCOME, EXPENSE, ASSET, LIABILITY, EQUITY (case-insensitive). REVENUE is accepted as an alias of INCOME.
  - `vat_codes` object[]: Optional. If omitted, the default UK universal set (ST/RR/ZR/EX/NV) is used.
    - `code` string, required
    - `name` string, required
    - `rate` number, required
  - `options` object
    - `allowOverage` boolean
    - `businessContext` string
  - `invoices` object[]: Outstanding sales invoices and bills for the period. Optional, but send them whenever the batch contains customer receipts or supplier payments: without them a payment that settles an invoice is coded as ordinary income or expense, and nothing in the result says matching was never attempted.
    - `invoice_number` string, required
    - `type` 'sales' | 'purchase', required: sales = owed to you; purchase = a bill you owe.
    - `amount` number, required: Gross amount outstanding.
    - `date` string, date, required
    - `due_date` string, date
    - `contact_name` string
    - `currency` string

## Response `202`

Coding job queued.

- object
  - `coding_job_id` string, required
  - `status` 'queued', required
  - `poll_url` string, required

## Other responses

- `400`: Structurally invalid request (Zod). Distinct from the 422 format-contract gate.
- `401`: Missing, invalid, or revoked API key.
- `402`: Not enough credits to run/charge the job.
- `403`: Authenticated but the key lacks the required scope.
- `422`: CodeIQ / IQ Books strict-format contract violation.
- `429`: Per-key rate limit exceeded (120 requests / 60s window).
- `503`: The serial job queue for this product is full; retry shortly.

---

[API](https://skmtc.dev/reconcileiq/apis/reconcileiq-public-api.md) · [All operations](https://skmtc.dev/reconcileiq/apis/reconcileiq-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/reconcileiq/apis/reconcileiq-public-api/revisions/5401beef8653?raw)