Skip to main content

​
Overview

This guide outlines best practices for integrating with the universal data enrichment endpoint. This endpoint is designed to support transaction data acquired from an outside source, such as:
  • Aggregated transaction data
  • Consumer transaction panel data
  • Accounting software (Quickbooks, Xero, etc.)
  • Dispute data
  • Other external data sources
Universal data enrichment is currently in beta; request and response fields may change as the product evolves. For access, please contact [email protected] 

​
Best practices

Below we’ve outlined how to send data to the universal data enrichment endpoint. Regardless of the type of data you’re sending, providing raw, unaltered data yields the best results.

​
Sending universal data

Universal data enrichment relies primarily on two fields: description and amount.
  • For the description field, pass the transaction’s original description.
  • For the amount field, a negative value (-) indicates a credit or incoming transfer, while a positive value (+) indicates a debit or outgoing transfer.
    • Alternatively use the direction field to specify whether the transaction is a credit or debit
Below we’ve provided examples of sources of data and best practices for how to map that data to Spade fields:
data sourcedescriptionamountdirection
Plaid
(docs)		original_description

Note: when calling /transactions/sync set the flag options.include_original_descritptionto true

Alternatively use the name field if original_description is not available		amountoptional: set direction to credit for negative values and debit for positive values
MX
(docs)		original_descriptionamount use the type field from MX to set credit or debit
Mastercard
Open Banking
(docs)		descriptionamountuse the type field from Mastercard to set credit or debit
Yodlee
(docs)		description.originalamountuse the baseType field from Yodlee to set credit or debit
Akoya
(docs)		descriptionamount

whenbalanceType
is LIABILITYset amount to (-)
Quiltt
(docs)		descriptionamountuse the entryType from Quiltt field to set credit or debit
If your data source is not listed here, please work with your Spade team to help map your data to the required fields
Additionally, we require the following fields:
  • currencyCode - the currency of the transaction, e.g., USD.
  • userId — associated with a user or organization; used for recurrence, category, and counterparty personalization.
  • occurredAt — the timestamp of the transaction in date-time format.
  • transactionId — required for batch enrichment and recommended for all integrations to associate with your internal transaction identifier.

​
Batch vs real-time

We support enriching individual or multiple transactions via API:
  • For real-time enrichment, use the /transactions/universal/enrich endpoint.
  • For non-real-time enrichment, use the /batches/transactions/universal/enrich endpoint. This endpoint supports up to 50,000 transactions at once.
For best practices on sending transactions in batches, see our batch enrichment guide.

​
Example request and response

Below we’ve provided an example request to the /transactions/universal/enrich endpoint: 
{
   "description": "SQ* BLACK SEED BAGELS BROOKLYN NY",
   "amount": "14.25",
   "currencyCode": "USD",
   "occurredAt": "2025-09-15",
   "userId": "u-1234",
   "transactionId": "48FA5E16-6870-42D2-AECE-AF393714EB1C"
}
And a successful enrichment response, identifying the counterparty “Black Seed Bagels” as well as providing detailed location information for where the transaction occurred. 
{
  "transactionInfo": {
    "type": "spending",
    "subType": null,
    "display": {
      "name": "Black Seed Bagels",
      "categoryName": "Bakeries",
      "graphic": "https://static.v2.spadeapi.com/logos/f6c2a3614b92313cb06e9a19e8a7cfbd/light.png",
      "graphicSource": "counterparty"
    },
    "thirdParties": [],
    "spendingInfo": {
      "channel": {
        "value": "digital"
      }
    },
    "transferInfo": null,
    "atmInfo": null,
    "isAccountVerification": false,
    "isPeerToPeer": false,
    "isDigitalWallet": false,
    "transactionId": "166c5ad8-8a94-4964-a659-03cdb64525f2",
    "recurrenceInfo": null
  },
  "counterparty": [
    {
      "id": "f6c2a361-4b92-313c-b06e-9a19e8a7cfbd",
      "name": "Black Seed Bagels",
      "legalName": null,
      "industry": [
        {
          "id": "005-000-000-000",
          "name": "Food and Drink",
          "icon": "https://static.v2.spadeapi.com/categories/18785677534e4e3a8ec37e4dc7dc34d9/light.png"
        },
        {
          "id": "005-001-000-000",
          "name": "Bakeries",
          "icon": "https://static.v2.spadeapi.com/categories/18785677534e4e3a8ec37e4dc7dc34d9/light.png"
        }
      ],
      "location": [
        {
          "id": "4f41c8c6-2d57-3dd4-9c48-364456d8500c",
          "address": "214 Berry St",
          "addressLine1": "214 Berry St",
          "addressLine2": null,
          "city": "Brooklyn",
          "region": "NY",
          "postalCode": "11249",
          "country": "USA",
          "phoneNumber": "+16468762257",
          "latitude": 40.716225,
          "longitude": -73.961818,
          "matchScore": null
        }
      ],
      "matchScore": null,
      "logo": "https://static.v2.spadeapi.com/logos/f6c2a3614b92313cb06e9a19e8a7cfbd/light.png",
      "medianSpendPerTransaction": null,
      "phoneNumber": "+13329006050",
      "website": "http://blackseedbagels.com"
    }
  ],
  "enrichmentId": "1dcee2b3-2c16-40e3-bdaf-5dd2f248a692",
  "mobileAppInfo": null
}

​
Error handling

The most common errors result from missing required fields. In a 400 response, we return specific details needed to reprocess the request. 
{
  "currencyCode": [
    "This field is required."
  ]
}

​
Understanding enrichment results

When enriching transaction data through this endpoint, we always return a cleansed counterparty name. For more information on interpreting enrichment responses, see our guide on understanding enriched data.