---
title: "Submit an async address-validation job (up to 50,000)"
method: POST
path: "/validate/jobs"
tags: ["Validation"]
---

# Submit an async address-validation job (up to 50,000)

`POST /validate/jobs`

## Request

- Base URL: `https://api.acuris-geo.com`
- URL: `https://api.acuris-geo.com/validate/jobs`
- Auth: one of:
  - API key in header `X-Acuris-Key`
  - HTTP bearer
  - API key in header `X-API-Key`
  - API key in query parameter `key`
  - none

Queue a large address list for **asynchronous** validation — the path for
lists larger than the 200-address synchronous `/validate/batch` cap.
Returns a `job_id` immediately (HTTP 202); poll
`GET /validate/jobs/{job_id}` for status and results, or pass `webhook_url`
and the server POSTs `{job_id, status, addresses_count}` when processing
finishes. **Billing is per row inside the worker** — each address consumes
one address-validation transaction (Stripe-plan transaction; the trial pool
decrements 1 regardless), so there is **no submit-time `402`/`403`**. If the
account runs out of transactions partway through, the remaining results carry an
error entry rather than failing the whole job. **Requires an API key.** Runs
on the main box only (the UK PAF satellite returns `503` with a redirect hint).

## Request body

- object
  - `addresses` unknown[], required: Each entry is the same shape as `POST /validate`'s `input` (or `{"input": ..., "country": ...}` per-row override).
    - unknown
  - `country` string, required: Default ISO-style country code for the job. Required.
  - `webhook_url` string: Optional http(s) URL to receive a completion callback.

## Response `202`

Job accepted and queued.

- object
  - `job_id` string
  - `status` string
  - `addresses_count` integer
  - `status_url` string: URL to poll for status / results.

## Other responses

- `400`: Empty list, more than 50,000 addresses, missing `country`, or a non-http(s) `webhook_url`.
- `401`: API key required.
- `503`: Submitted to the UK PAF satellite; resubmit to the main box (hint in body).

---

[API](https://skmtc.dev/acuris-geo/apis/acuris-geo-api.md) · [All operations](https://skmtc.dev/acuris-geo/apis/acuris-geo-api/llms.txt) · [OpenAPI document](https://skmtc.dev/acuris-geo/apis/acuris-geo-api/revisions/8547b31dd96a?raw)