Skip to main content

​
Overview

If you believe an enrichment response may be inaccurate, you can submit a report using the /transactions/report endpoint. Our team will review your report and determine whether a correction is needed. If a correction is made, we’ll send the returned enrichment data to your callback URL so you can update your records automatically.

​
Prerequisites

Before submitting error reports, you’ll need:
  1. A callback URL — Provide an HTTPS endpoint to your Spade representative where we can deliver returned enrichments. Contact support@spade.com to configure this.
  2. A callback token — Your Spade representative will provide you with a token to validate that incoming callbacks are from Spade. Store this token securely on your server.
  3. An enrichment ID — The enrichmentId from the enrichment response you want to report.
Your callback token is a shared secret between your system and Spade. Do not expose it in client-side code, public repositories, or logs. Store it in a secure secrets manager with restricted access.

​
Submitting an error report

Send a POST request to the /transactions/report endpoint with the enrichmentId of the enrichment you want to report and a description of what you believe may be inaccurate.

​
Request fields

FieldRequiredTypeDescription
enrichmentIdrequiredstringThe enrichmentId from the enrichment response
errorDescriptionrequiredstringA description of the potential issue (max 1024 characters)
incorrectCounterpartyoptionalbooleanSet to true if you believe the counterparty information may be inaccurate
incorrectCounterpartyDescriptionoptionalstringDetails about the suspected counterparty issue (max 1024 characters)
incorrectLocationoptionalbooleanSet to true if you believe the location information may be inaccurate
incorrectLocationDescriptionoptionalstringDetails about the suspected location issue (max 1024 characters)
incorrectCategoryoptionalbooleanSet to true if you believe the category/industry may be inaccurate
incorrectCategoryDescriptionoptionalstringDetails about the suspected category issue (max 1024 characters)
incorrectChanneloptionalbooleanSet to true if you believe the channel (physical/digital) may be inaccurate
incorrectChannelDescriptionoptionalstringDetails about the suspected channel issue (max 1024 characters)
Setting the optional boolean fields and providing detailed descriptions helps our team investigate your report more efficiently. Be as specific as possible in your descriptions.

​
Example request

curl --request POST \
--url https://east.sandbox.spade.com/transactions/report \
--header 'content-type: application/json' \
--header 'X-Api-Key: SPADE-API-KEY' \
--data '{
  "enrichmentId": "050d3a73-c212-4f89-b9c0-0e75da0efeea",
  "errorDescription": "Location returned does not match the physical store location",
  "incorrectLocation": true,
  "incorrectLocationDescription": "Location returned is for Dunlawton Ave, but the actual store is on Taylor Rd"
}'

​
Example response

A successful report returns an HTTP 200 response: 
{
  "details": "Enrichment successfully reported."
}
If validation fails, you’ll receive an HTTP 400 with details about which fields are invalid: 
{
  "enrichmentId": [
    "Must be a valid UUID."
  ]
}

​
Receiving returned enrichments

If our team determines that a correction is warranted after reviewing your report, we’ll send the returned enrichment data to the callback URL you configured with your Spade representative.

​
Callback format

The callback is a POST request to your callback URL containing the returned enrichment response in the same format as the original card enrichment response. The request includes an X-Webhook-Token header that you should validate against the callback token provided by your Spade representative.

​
Validating the callback

You must verify the X-Webhook-Token header matches the token provided to you by Spade before processing the returned enrichment. This ensures the callback is genuinely from Spade and has not been tampered with.
Always validate the X-Webhook-Token before processing any callback data. Reject requests with missing or mismatched tokens.

​
Example callback handler

# Example of what the callback request from Spade looks like:
# POST https://your-domain.com/spade/corrections
# Headers:
#   Content-Type: application/json
#   X-Webhook-Token: your-callback-token-from-spade
# Body: returned card enrichment response JSON

# You can test your callback endpoint with curl:
curl --request POST \
--url https://your-domain.com/spade/corrections \
--header 'content-type: application/json' \
--header 'X-Webhook-Token: your-callback-token-from-spade' \
--data '{
  "transactionInfo": {
    "type": "spending",
    "display": {
      "name": "Walmart Neighborhood Market",
      "categoryName": "Grocery Stores"
    }
  },
  "enrichmentId": "050d3a73-c212-4f89-b9c0-0e75da0efeea"
}'
The Python example above uses Flask for illustrative purposes only. You can implement your callback handler using any web framework or language that can receive HTTP POST requests.
The returned enrichment callback body uses the same schema as the card enrichment response. Refer to the API reference for the full response object documentation.

​
Workflow summary

  1. You enrich a transaction and receive a response with an enrichmentId
  2. You believe the enrichment may be inaccurate and submit a report to /transactions/report
  3. Spade’s team reviews the report and determines whether a correction is needed
  4. If a correction is made, Spade sends the returned enrichment to your callback URL with the X-Webhook-Token header
  5. Your server validates the token and updates your records

​
Error handling

Status CodeDescription
200Report submitted successfully
400Validation error — check the response body for details on invalid fields
403Authentication failed — verify your API key
500Internal server error — retry the request after a brief delay
For questions about error reporting or to set up your callback URL, contact support@spade.com.