Create import job
Import up to 10,000 transactions, invoices, counterparties, or payment methods in the background.
Stages the items and answers 202 with a job id right away. Rows are processed in the background; follow them with Get import job. This is the recommended way to push data in volume, and it replaces Ingest transactions.
items takes the same fields as the single-record call for that entity: an Ingest transactions row for transaction, the Create invoice body for invoice (issued invoices by default), a Bulk import counterparties row for counterparty, and a Bulk import payment methods row for payment_method. Transaction rows are validated before the job is created: if any row is invalid, nothing is staged and the call returns 400 with up to 20 row errors.
The key needs ingest:write and the write scope of the entity. Send an Idempotency-Key header so a retried request does not create a second job. Limited to 20 requests per minute per key.
See also
- Get import job (GET
/api/v1/import-jobs/:id). Follow the job and read per-row errors. - Ingest transactions (deprecated) (POST
/api/v1/ingest/transactions). Older synchronous call for small transaction batches. - Retries and rate limits . Retry safely with Idempotency-Key.
Body parameters
| Name | Type | Required |
|---|---|---|
entityWhat the items are. | string No maximum | Required |
Allowed values transactioninvoicecounterpartypayment_method | ||
itemsRecords to import, 1 to 10,000. Fields depend on entity (see above). Example: [{"sourceId":"bank:2026-09-12:TX-8891","amount":1000,"direction":"in","transactionDate":"2026-09-12"}] | array | Required |
fileNameLabel shown on the job. Default Example: september-bank-lines.json | string Max 255 | Optional |
Errors
This operation can return the following errors in addition to generic HTTP failures.
| Error | HTTP code | Description |
|---|---|---|
Missing Bearer token | 401 | The Authorization header is missing or is not a Bearer token. |
Invalid or revoked API key | 401 | The API key is unknown, malformed, expired, or has been revoked. |
API key is missing scope ingest:write | 403 | The key does not include ingest:write. A write scope does not imply the matching read scope. |
Too many requests, please try again later | 429 | More than 100 requests in one minute from this API key or IP address. Wait for the Retry-After header (seconds) and retry. |
Too many import requests, please try again later | 429 | POST /import-jobs is limited to 20 requests per minute per API key, on top of the general limit. Retry-After is in seconds. |
API key is missing scope … | 403 | Besides ingest:write, the key needs the write scope of the entity: ingest:write for transactions, invoices:write, counterparties:write, or payment_methods:write. code is missing_scope. |
Invalid import request | 400 | entity is unknown, items is empty or has more than 10,000 entries, or the body has extra fields. details lists field and message. |
Some transactions are invalid | 400 | At least one transaction row failed validation. details lists up to 20 rows with their messages. Nothing was staged. |
Tenant context required | 400 | The authenticated credential is not bound to a tenant. |
Internal server error | 500 | Unexpected server error. The JSON body includes correlationId. Retry with backoff. |
Idempotency-Key must be 8-255 characters: letters, digits, ".", "_", ":" or "-". | 400 | The Idempotency-Key header is present but malformed. |
A request with this Idempotency-Key is still being processed. | 409 | The first request with this key has not finished. Retry after it completes. code is idempotency_in_progress. |
This Idempotency-Key was already used with a different request body. | 422 | Send a new key for a different request. code is idempotency_key_reuse. |