Skip to main content

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.

Microbatching is not enabled by default. To request access, please contact us at sales@spade.com.

​
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. 
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"
      }
    ]
  }'
callbackUrl is ignored when synchronous=true, as the response is returned inline.

​
Per-endpoint limits

Microbatch sizes are capped per endpoint. Submitting more items than the cap returns a 400.
EndpointsynchronousMax
POST /batches/merchants/enrich50
POST /batches/transactions/cards/enrich100
POST /batches/transactions/cards/enrich/parse100
POST /batches/transactions/transfers/enrich100
POST /batches/transactions/universal/enrich100
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). 
{
  "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:

​
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.