Enrich many transactions at once
50,000
transactions in a single request and retrieve the enriched results once processing is complete. Below you’ll find the data types supported and their corresponding endpoints:
transactionId
. Results are not guaranteed to be returned in the order in which they were submitted, so you can use the transactionId
to correlate transactions in the results with the original requests. Duplicate IDs will cause the batch enrichment request to fail.
Sending data in chronological order
We recommend sending your oldest transactions first as this can have an impact on the insights we can provide on transaction data such as recurrence.
Using Custom attributes
If you have additional data elements that you would like to associate to any transactions, you can use the customAttributes
object which will be passed back alongside enriched transaction data.
batchId
which you’ll use later to retrieve the enriched transactions.
batchId
to retreive enriched data, so make sure you are storing it!400
response with error details. Below is an example of an error response with duplicate transactionIds
:
pending
: The batch has been accepted but processing hasn’t started
* running
: The batch is currently being processed
* completed
: All transactions have been enriched and results are ready
* failed
: The batch encountered an error and couldn’t be processed
We provide options for updates on the batch status either via webhooks or polling the status endpoint. We strongly recommend using webhooks as this reduces integration complexity as well as unnecessary API calls.
Using webhooks
If you provided a callbackUrl
in your batch submission, we’ll send a POST request to that URL when processing completes.
The callback will include a JSON payload with:
* batchId
: The ID of the completed batch
* status
: Either “completed” or “failed”
We will also include a token in the X-Webhook-Token
header that you should compare against the callback token provided to you by your Spade representative. Contact your Spade representative if you do not have this token.
Here is an example Flask endpoint you could use to receive callbacks.
completed
status. We recommend implementing an exponential backoff strategy when polling for status.
failed
status you will need to re-send the batch for processing.
completed
you can retrieve the enriched data by calling the /results endpoint.
/batches/{batchId}/results
endpoint will only return results when the batch status is completed
. If you request results before completion, you’ll receive a 202 status code indicating that the results aren’t yet available.batchId
in addition to a results
array that includes all of the transactions sent in the batch.
Each transaction object in the results
array will contain:
transactionId
customAtrributes
provided in the transactionstatus
code (either 200
or 400
)enrichmentId
errors
object that includes detailed information that caused the error. An example is included below for a request that did not include a merchantName