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 sales@spade.com 

​
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.
Below we’ve provided examples of sources of data and best practices for how to map that data to Spade fields:
data sourcedescriptionamount
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		amount
MX
(docs)		original_descriptionamount

set amount to (-) if type is CREDIT
Mastercard
Open Banking
(docs)		descriptionamount

set amount to (-) if type is CREDIT
Yodlee
(docs)		description.originalamount

set amount to (-) if baseType is CREDIT
Akoya
(docs)		descriptionamount

whenbalanceType
is LIABILITYset amount to (-)
Quiltt
(docs)		descriptionamount

set amount to (-) if entryType is CREDIT
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.