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

# Microbatch enrichment guide

> Submit small batches and receive enriched results inline.

<Info>
  Microbatching is not enabled by default. To request access, please contact us
  at [sales@spade.com](mailto:sales@spade.com).
</Info>

## Overview

Microbatching lets you submit a small batch to one of Spade's batch enrichment endpoints and receive the enriched results inline in the response, instead of receiving a `batchId` and polling for results once asynchronous processing finishes.

## Choosing a batch mode

* **Microbatch (`?synchronous=true`):** Processes records synchronously and returns results inline in the response.
  * Limited to each endpoint's `synchronousMax`.
  * Use when you have a small number of items (more than one, fewer than a few hundred) and need results back quickly.

* **Asynchronous (default):** Returns a `batchId` immediately and processes records in the background.
  * Supports each endpoint's full async batch size limit and supports `callbackUrl` for completion notifications.
  * Use when you need to process thousands of records and you need to optimize for overall throughput.

## Enabling microbatching

Append `?synchronous=true` to any supported batch endpoint. The request schema is identical for synchronous and asynchronous processing.

```bash theme={null}
curl https://east.sandbox.spade.com/batches/transactions/universal/enrich?synchronous=true \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: <YOUR_SANDBOX_API_KEY>" \
  -d '{
    "transactions": [
      {
        "transactionId": "48FA5E16-6870-42D2-AECE-AF393714EB1C",
        "description": "SQ* BLACK SEED BAGELS BROOKLYN NY",
        "amount": "14.25",
        "currencyCode": "USD",
        "occurredAt": "2025-09-15",
        "userId": "u-1234"
      }
    ]
  }'
```

<Note>
  `callbackUrl` is ignored when `synchronous=true`, as the response is returned
  inline.
</Note>

## Per-endpoint limits

Microbatch sizes are capped per endpoint. Submitting more items than the cap returns a `400`.

| Endpoint                                        | `synchronousMax` |
| ----------------------------------------------- | ---------------- |
| `POST /batches/merchants/enrich`                | 50               |
| `POST /batches/transactions/cards/enrich`       | 100              |
| `POST /batches/transactions/cards/enrich/parse` | 100              |
| `POST /batches/transactions/transfers/enrich`   | 100              |
| `POST /batches/transactions/universal/enrich`   | 100              |

If you'd like to fetch the current cap programmatically, each endpoint's `OPTIONS` response includes a `synchronousMax` field with the current value.

## Synchronous response shape

When `synchronous=true` is set, the response returns a `results` array. Each entry contains the same per-item shape that the endpoint's asynchronous `/results` endpoint would return — a `statusCode` plus either the enriched payload (for `200`) or an `errors` object (for `400`).

```json theme={null}
{
  "results": [
    {
      "statusCode": 200,
      "transactionId": "7866cfe1-edde-4b45-a8da-c7076dab0255"
      // ... endpoint-specific response fields ...
    },
    {
      "statusCode": 400,
      "transactionId": "1ae0922a-f343-49ab-b52b-8566a5f0bc11",
      "errors": {
        "currencyCode": ["This field is required."]
      }
    }
  ]
}
```

See each endpoint's guide for the exact per-item enrichment shape:

* [Card enrichment guide](/reference/card-enrichment-guide)
* [Transfer enrichment](/reference/transfer-enrichment)
* [Universal data enrichment guide](/reference/universal-data-enrichment)
* [Batch merchant enrichment guide](/reference/batch-merchant-enrichment-guide)

## Errors

* **400 on the submission itself** — the request is malformed (no items, duplicate IDs) or exceeds the endpoint's `synchronousMax` limit.
* **400 per item** — invalid items appear in the `results` array with `statusCode: 400` and an `errors` object describing what went wrong. Valid items in the same submission are still processed normally.
* **403** — invalid or missing API key, or microbatching is not enabled on your account.
* **500** — Spade infrastructure issue. Retry with exponential back-off before resubmitting.