> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bunny.build/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /cpf-cnpj-generator

> Generate mathematically valid CPF and CNPJ numbers for testing and development.

## Endpoint

```
POST https://api.bunny.build/api/v1/cpf-cnpj-generator
```

## Authentication

| Header         | Required | Value                    |
| -------------- | -------- | ------------------------ |
| `X-API-Key`    | Yes      | Your API key (`bun_...`) |
| `Content-Type` | Yes      | `application/json`       |

## Overview

Generate batches of mathematically valid CPF (individual taxpayer) or CNPJ (company taxpayer) numbers for use in test environments. All generated documents pass the official checksum algorithm and can optionally be returned with standard formatting masks. These are synthetic numbers for testing only and do not correspond to real individuals or entities.

## Use cases

* Seed test databases and QA environments with realistic Brazilian document numbers
* Validate form input components in CI pipelines without using real data
* Demonstrate form validation behavior in live demos and prototypes
* Generate fixtures for unit and integration tests

## Request body

| Field       | Type    | Required | Description                                                         |
| ----------- | ------- | -------- | ------------------------------------------------------------------- |
| `type`      | string  | No       | Document type: `"cpf"` or `"cnpj"`. Default: `"cpf"`                |
| `count`     | integer | No       | Number of documents to generate (1–100). Default: `1`               |
| `formatted` | boolean | No       | Return formatted strings (e.g. `"123.456.789-09"`). Default: `true` |

### Example

```json theme={null}
{
  "type": "cpf",
  "count": 3,
  "formatted": true
}
```

## Response

### 200 OK

| Field       | Type             | Description                                                                                        |
| ----------- | ---------------- | -------------------------------------------------------------------------------------------------- |
| `type`      | string           | Document type returned (`"cpf"` or `"cnpj"`)                                                       |
| `count`     | integer          | Number of documents generated                                                                      |
| `documents` | array of objects | Each entry has `raw` (digits only) and `formatted` (masked string, omitted if `formatted: false`)  |
| `document`  | object           | First document in the batch — same shape as a `documents` entry. Shortcut for `count: 1` use cases |

**Example**

```json theme={null}
{
  "type": "cpf",
  "count": 3,
  "documents": [
    { "raw": "12345678909", "formatted": "123.456.789-09" },
    { "raw": "98765432100", "formatted": "987.654.321-00" },
    { "raw": "11122233396", "formatted": "111.222.333-96" }
  ],
  "document": { "raw": "12345678909", "formatted": "123.456.789-09" }
}
```

### 401 Unauthorized

```json theme={null}
{
  "detail": "Missing API key. Include X-API-Key header."
}
```

### 402 Payment Required

```json theme={null}
{
  "detail": "Monthly quota exceeded. Upgrade your plan."
}
```

### 422 Unprocessable Entity

```json theme={null}
{
  "detail": "'count' must be between 1 and 100."
}
```

### 429 Too Many Requests

```json theme={null}
{
  "detail": "Rate limit exceeded. Try again in 60 seconds."
}
```

## cURL example

```bash theme={null}
curl -X POST https://api.bunny.build/api/v1/cpf-cnpj-generator \
  -H "X-API-Key: bun_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"type": "cpf", "count": 3, "formatted": true}'
```