---
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`

## Request

- Base URL: `https://api.carsxe.com`
- URL: `https://api.carsxe.com/v1/recalls-batch/submit`
- Auth: one of:
  - API key in query parameter `key`
  - API key in header `PAYMENT-SIGNATURE`
  - none
- TypeScript: <https://skmtc.dev/carsxe/apis/carsxe-api/docs/v1/recalls-batch/submit/post.ts> (a function with typed inputs; its response is checked against the schema)

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.


Credit plans: Bulk Recalls uses 2 credits per unique VIN submitted in an accepted batch, whether or not recalls are found. Duplicate VINs count once. Failed lookups and no-data errors do not use credits. See https://carsxe.com/pricing.md.

## 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.dev/carsxe/apis/carsxe-api.md) - [All operations](https://skmtc.dev/carsxe/apis/carsxe-api/llms.txt) - [OpenAPI document](https://skmtc.dev/carsxe/apis/carsxe-api/revisions/ed8f6c024239?raw)