# Enrollment batch

> Requests up to 500 enrollments in one call, from several merchants, in partial mode (default) or all or nothing, with the result of each item in the order sent.

Página: https://doc.rapidchargeback.com/en/canais/enrollments/lote-de-enrollments/

Requests up to **500 enrollments** in one call, from one or several merchants. Each item follows the rule of [Request enrollment](https://doc.rapidchargeback.com/en/canais/enrollments/pedir-enrollment/): the same fields, the same errors, and a repeated request comes back `existing`, without creating another.

Request each enrollment once, when the seller joins your base: do not include enrollments in a daily upload (see [Sync guide](https://doc.rapidchargeback.com/en/canais/merchants/guia-de-sincronizacao/)).

## Endpoint

```
POST https://api.rapidchargeback.com/api/v1/enrollments/batch
```

## Authentication

```
Authorization: Basic base64(client_id:client_secret)
Content-Type: application/json
```

---

## Request body

| Field | Type | Required | Description |
|---|---|---|---|
| `items` | array | Yes | From 1 to 500 requests, each with the fields of [Request enrollment](https://doc.rapidchargeback.com/en/canais/enrollments/pedir-enrollment/#request-body), including its own `merchant_id` or `merchant_ref` |
| `mode` | enum | No | `partial` (default) or `all_or_nothing` |

- Body up to **2 MB**. Above that, `413 PAYLOAD_TOO_LARGE`.
- A field other than `items` and `mode` in the envelope, or `items` empty or with more than 500: the whole batch is rejected with `422 VALIDATION_ERROR`, saving nothing.

### Modes

| `mode` | What happens |
|---|---|
| `partial` | Each item is saved or rejected on its own. `existing` counts as success |
| `all_or_nothing` | Rapid checks every item first. If any fails, nothing is saved and the batch comes back `422 ENROLLMENT_BATCH_INVALID` with the list of rejected items. `existing` does not count as a failure; `ENROLLMENT_PREVIOUSLY_REJECTED` does |

### Repeated in the same batch

The same identifier in two items of the batch (descriptor ignoring case, repeated spaces and spaces around `*`, or the same BIN + CAID): the first counts and the following ones are rejected with `ENROLLMENT_DUPLICATE_IN_BATCH`.

### Pending limit

If the batch's new requests would take your company above **20,000** enrollments waiting for approval, the whole batch is rejected with `422 ENROLLMENT_PENDING_LIMIT`, saving nothing.

---

## Request example

```bash
curl -X POST https://api.rapidchargeback.com/api/v1/enrollments/batch \
  -H "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "partial",
    "items": [
      { "merchant_ref": "PB-1001", "enrollment_type": "descriptor", "descriptor_value": "LOJA EXEMPLO", "descriptor_rule": "exact", "products": ["alert"] },
      { "merchant_ref": "PB-1002", "enrollment_type": "bin_caid", "bin": "424242", "caid": "123456789", "products": ["alert"] },
      { "merchant_ref": "PB-1002", "enrollment_type": "descriptor", "descriptor_value": "loja  exemplo", "descriptor_rule": "exact", "products": ["alert"] }
    ]
  }'
```

---

## Response

### Success

`200 OK` whenever the batch was processed, even with rejected items. Check `failed` and each item's `result`.

```json
{
  "data": {
    "total": 3,
    "succeeded": 2,
    "failed": 1,
    "counts": { "created": 1, "existing": 1 },
    "results": [
      {
        "index": 0,
        "result": "existing",
        "merchant_ref": "PB-1001",
        "enrollment": {
          "id": "00000000-0000-0000-0000-0000000000aa",
          "merchant_id": "00000000-0000-0000-0000-000000000001",
          "merchant_ref": "PB-1001",
          "enrollment_type": "descriptor",
          "descriptor_value": "loja exemplo",
          "descriptor_rule": "exact",
          "bin": null,
          "caid": null,
          "arn": null,
          "products": {
            "alert": { "status": "active", "rejection_reason": null, "approved_at": "2026-11-07T15:00:00.000Z" },
            "prevention": null
          },
          "created_at": "2026-11-06T12:00:00.000Z",
          "updated_at": "2026-11-07T15:00:00.000Z"
        }
      },
      {
        "index": 1,
        "result": "created",
        "merchant_ref": "PB-1002",
        "enrollment": { "id": "00000000-0000-0000-0000-0000000000ab", "...": "Enrollment object" }
      },
      {
        "index": 2,
        "result": "error",
        "merchant_ref": "PB-1002",
        "status": 422,
        "error": {
          "code": "ENROLLMENT_DUPLICATE_IN_BATCH",
          "message": "Descriptor \"loja  exemplo\" appears more than once in the batch",
          "params": { "identifier": "Descriptor \"loja  exemplo\"" }
        }
      }
    ]
  }
}
```

| Field | Description |
|---|---|
| `total`, `succeeded`, `failed` | Items sent, accepted (`created` or `existing`) and rejected |
| `counts` | How many of each: `created`, `existing` |
| `results` | One per item, in the order of the array sent |
| `results[].index` | Position of the item in the array sent, starting at 0 |
| `results[].result` | `created`, `existing` or `error` |
| `results[].merchant_ref` | The `merchant_ref` you sent in the item (`null` if `merchant_id` was sent) |
| `results[].enrollment` | On success: the Enrollment object, the same as in [Request enrollment](https://doc.rapidchargeback.com/en/canais/enrollments/pedir-enrollment/#created) |
| `results[].status`, `results[].error` | On error: the HTTP status the item would get on its own and the error (`code`, `message`, `params`) |

### All or nothing rejected

```
HTTP/1.1 422 Unprocessable Entity
```

```json
{
  "error": {
    "code": "ENROLLMENT_BATCH_INVALID",
    "message": "1 of 3 items were not accepted. Nothing was created.",
    "params": { "count": 1, "total": 3 },
    "details": {
      "errors": [
        {
          "index": 2,
          "code": "ENROLLMENT_DUPLICATE_IN_BATCH",
          "message": "Descriptor \"loja  exemplo\" appears more than once in the batch",
          "params": { "identifier": "Descriptor \"loja  exemplo\"" }
        }
      ]
    }
  }
}
```

### Another batch in progress

```
HTTP/1.1 429 Too Many Requests
Retry-After: 5
```

```json
{
  "error": {
    "code": "BATCH_IN_PROGRESS",
    "message": "Another batch from this account is still being processed. Try again in a few seconds."
  }
}
```

Your company runs one enrollment batch at a time. A second batch sent while the first is still being saved is rejected in full: wait for `Retry-After` and send it again.

### Whole-batch errors

| HTTP | Code | When |
|---|---|---|
| 422 | `VALIDATION_ERROR` | Invalid envelope: `items` missing, empty, with more than 500, `mode` outside the list or an unknown field in the envelope |
| 422 | `ENROLLMENT_BATCH_INVALID` | All or nothing with some item rejected (`params.count`, `params.total`, `details.errors`) |
| 422 | `ENROLLMENT_PENDING_LIMIT` | The batch would take your company above 20,000 pending (`params.limit`) |
| 413 | `PAYLOAD_TOO_LARGE` | Body above 2 MB |
| 429 | `RATE_LIMIT_EXCEEDED` | More than 60 writes per minute (each batch counts as one) |
| 429 | `BATCH_IN_PROGRESS` | Another enrollment batch from your company is still in progress |
| 403 | `KYB_NOT_APPROVED`, `COMPANY_NOT_ACTIVE`, `COMPANY_BLOCKED` | Company without an approved registration, inactive or blocked |
| 503 | `SERVICE_UNAVAILABLE` | Temporarily unavailable: repeat after `Retry-After` |

---

## Notes

- **Repeating is safe.** After a `503` or a dropped connection, send the same batch: what was already saved comes back `existing`. If you get `BATCH_IN_PROGRESS`, the previous batch is still being saved: wait and repeat.
- **Send one batch after the other**, not in parallel.
- **Auth, rate limit, error codes:** see [Authentication](https://doc.rapidchargeback.com/en/referencia/autenticacao/) and [Response codes](https://doc.rapidchargeback.com/en/referencia/codigos-de-resposta/).
