Microbatch enrichment guide

​

Overview

​

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

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"
      }
    ]
  }'

​

Per-endpoint limits

​

Synchronous response shape

{
  "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."]
      }
    }
  ]
}

• Card enrichment guide
• Transfer enrichment
• Universal data enrichment guide
• 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.