---
title: "Submit a bulk recalls batch"
method: POST
path: "/v1/recalls-batch/submit"
tags: ["Recalls"]
---

# Submit a bulk recalls batch

`POST /v1/recalls-batch/submit`

Submit up to 10,000 VINs for asynchronous recall processing. Provide
VINs as a JSON array (`vins`), inline CSV text (`csv`), or an HTTPS
link to a CSV file (`csvUrl`). Optionally provide a `webhookUrl` that
CarsXE will POST to when the batch finishes. Poll the status endpoint
or wait for the webhook, then fetch results.

x402 submissions must use the JSON `vins` array. The `csv` and `csvUrl`
forms require CarsXE API-key authentication.

## Request body

- object
  - `vins` string[] — Array of 17-character VINs (max 10,000 per batch).
  - `csv` string — Inline CSV text containing VINs. Available with CarsXE API-key authentication only; x402 does not accept this form.
  - `csvUrl` string — HTTPS link to a CSV file of VINs (max 5 MB) hosted on a supported storage provider (e.g. S3, GCS, Firebase, Dropbox). Available with CarsXE API-key authentication only; x402 does not accept this form.
  - `webhookUrl` string — HTTPS URL for a customer webhook. CarsXE POSTs a JSON payload when the batch finishes. Must be a valid HTTPS URL allowed by CarsXE validation rules.

## Response `202`

Batch accepted and queued for processing.

- object
  - `success` boolean
  - `data` object
    - `batchId` string
    - `status` string
    - `totalVins` integer
    - `processedVins` integer
    - `batchToken` string — Opaque batch-scoped credential returned only for x402 submissions. Send it in X-CarsXE-Batch-Token on follow-up requests.
  - `message` string

## Other responses

- `400` — Invalid request body — missing VINs, invalid VINs, more than 10,000 VINs, invalid `webhookUrl`, or a `csvUrl` that is invalid / not allowed / too large.
- `401` — Missing API key, unknown/disabled API key, or inactive account.
- `405` — Method not allowed (only POST is accepted).
- `429` — API usage limit exceeded for the current billing period.
- `500` — Internal server error.
- `502` — Could not download the CSV from `csvUrl`.

---

[API](https://skmtc.net/carsxe/apis/carsxe-api.md) · [All operations](https://skmtc.net/carsxe/apis/carsxe-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/carsxe/carsxe-api/revisions/0343df02d7c4/schema)