Error reporting guide

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:

A callback URL — Provide an HTTPS endpoint to your Spade representative where we can deliver returned enrichments. Contact support@spade.com to configure this.
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.
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

Field	Required	Type	Description
enrichmentId	required	string	The `enrichmentId` from the enrichment response
errorDescription	required	string	A description of the potential issue (max 1024 characters)
incorrectCounterparty	optional	boolean	Set to `true` if you believe the counterparty information may be inaccurate
incorrectCounterpartyDescription	optional	string	Details about the suspected counterparty issue (max 1024 characters)
incorrectLocation	optional	boolean	Set to `true` if you believe the location information may be inaccurate
incorrectLocationDescription	optional	string	Details about the suspected location issue (max 1024 characters)
incorrectCategory	optional	boolean	Set to `true` if you believe the category/industry may be inaccurate
incorrectCategoryDescription	optional	string	Details about the suspected category issue (max 1024 characters)
incorrectChannel	optional	boolean	Set to `true` if you believe the channel (physical/digital) may be inaccurate
incorrectChannelDescription	optional	string	Details 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"
}'

import requests

response = requests.post(
    "https://east.sandbox.spade.com/transactions/report",
    json={
        "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",
    },
    headers={"X-Api-Key": "<Your API Key Here>"},
)

print(response.json())

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

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/spade/corrections', methods=['POST'])
def handle_returned_enrichment():
    # Validate the webhook token
    webhook_token = request.headers.get('X-Webhook-Token')
    expected_token = "your-callback-token-from-spade"  # Store this securely

    if not webhook_token or webhook_token != expected_token:
        return jsonify({"error": "Invalid token"}), 403

    # Process the returned enrichment
    returned_enrichment = request.json
    enrichment_id = returned_enrichment["enrichmentId"]

    # Update your records with the returned data
    update_enrichment_in_database(enrichment_id, returned_enrichment)

    return jsonify({"status": "received"}), 200

def update_enrichment_in_database(enrichment_id, returned_enrichment):
    # Save the changes to your systems as necessary
    print(f"Saving Enrichment {enrichment_id}: {returned_enrichment}")

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

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

Error handling

Status Code	Description
200	Report submitted successfully
400	Validation error — check the response body for details on invalid fields
403	Authentication failed — verify your API key
500	Internal 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.

Welcome

Enrichment Guides

Tooling Guides

More

Overview

Prerequisites

Submitting an error report

Request fields

Example request

Example response

Receiving returned enrichments

Callback format

Validating the callback

Example callback handler

Workflow summary

Error handling

​Overview

​Prerequisites

​Submitting an error report

​Request fields

​Example request

​Example response

​Receiving returned enrichments

​Callback format

​Validating the callback

​Example callback handler

​Workflow summary

​Error handling

Overview

Prerequisites

Submitting an error report

Request fields

Example request

Example response

Receiving returned enrichments

Callback format

Validating the callback

Example callback handler

Workflow summary

Error handling