---
title: "Submit a batch of CPFs for asynchronous lookup"
method: POST
path: "/cpf/bulk"
tags: ["Bulk"]
---

# Submit a batch of CPFs for asynchronous lookup

`POST /cpf/bulk`

Accepts a list of CPFs and queues them for background processing. Returns immediately with a `jobId` used to poll `/cpf/bulk/{jobId}` for status.

- Invalid-format CPFs are filtered out before processing and reported in `data.invalid`.
- Only CPFs found in the database (`found`) consume credits, same rule as `GET /cpf/{cpf}`.
- Maximum 10,000 CPFs per request (`CPF_BULK_MAX`). Exceeding it returns `400`.
- Per-CPF results are returned inline by `GET /cpf/bulk/{jobId}` once processed.

## Request body

- BulkSubmitRequest — Request body for submitting a batch of CPFs
  - `cpfs` string[], required — List of CPFs, formatted or not. Max 10,000 per request (`CPF_BULK_MAX`) — exceeding it returns 400.
  - `fileName` string — Optional reference name for the batch, shown in history.
  - `format` 'CSV' | 'TXT' | 'Texto' — Optional, informational only — origin format of the batch.

## Response `202`

Batch accepted and queued for processing

- BulkSubmitResponse — Response after a batch is accepted
  - `success` boolean, required
  - `data` object, required
    - `jobId` string, uuid — Use to poll /cpf/bulk/{jobId}
    - `status` 'processing'
    - `totalRecords` integer — Valid CPFs accepted for processing
    - `invalid` integer — CPFs discarded for invalid format

## Other responses

- `400` — Missing/non-array/empty `cpfs` field, or `cpfs.length` over the `CPF_BULK_MAX` limit (default 10,000)
- `401` — Missing or invalid API Key
- `422` — No valid CPF in the submitted list
- `429` — Rate limit exceeded
- `500` — Internal server error

---

[API](https://skmtc.net/cpfhub/apis/cpfhub-io-api.md) · [All operations](https://skmtc.net/cpfhub/apis/cpfhub-io-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/cpfhub/cpfhub-io-api/versions/0aa1f2b175ff/schema)