> ## Documentation Index > Fetch the complete documentation index at: https://docs.spade.com/llms.txt > Use this file to discover all available pages before exploring further. # Universal data enrichment guide ## 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](mailto: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. * 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 source** | **description** | **amount** | direction | | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | | **Plaid**
([docs](https://plaid.com/docs/api/products/transactions/#transactionsget)) | `original_description`

Note: when calling /transactions/sync set the flag `options.include_original_descritption`to `true`

Alternatively use the `name` field if `original_description` is not available | `amount` | optional: set direction to `credit` for negative values and `debit` for positive values | | **MX**
**(**[**docs**](https://docs.mx.com/api-reference/platform-api/reference/list-transactions)**)** | `original_description` | `amount ` | use the `type` field from MX to set `credit` or `debit` | | **Mastercard**
**Open Banking**
([docs](https://developer.mastercard.com/open-banking-us/documentation/api-reference/?view=api#GetCustomerAccountTransactions)) | `description` | `amount` | use the `type` field from Mastercard to set `credit` or `debit` | | **Yodlee**
**(**[**docs**](https://developer.yodlee.com/resources/yodlee/data-model/docs/transactions)**)** | `description.original` | `amount` | use the `baseType` field from Yodlee to set `credit` or `debit` | | **Akoya**
**(**[**docs**](https://docs.akoya.com/reference/transactions#supported-data-elements)**)** | `description` | `amount`

when`balanceType`
is `LIABILITY`set amount to (-) | | | **Quiltt**
**(**[**docs**](https://www.quiltt.dev/api/core-resources/transactions)**)** | `description` | `amount` | use 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 per async batch or up to **100** transactions per microbatch (`?synchronous=true`). See the [Microbatch enrichment guide](/reference/microbatch-enrichment-guide) for details. For best practices on sending transactions in batches, see our [batch enrichment guide](/reference/batch-enrichment-guide). ### Example request and response Below we've provided an example request to the `/transactions/universal/enrich` endpoint: ```json theme={null} { "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. ```json expandable theme={null} { "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. ```json theme={null} { "currencyCode": [ "This field is required." ] } ``` ## Understanding enrichment results When enriching transaction data through this endpoint, we always return a cleansed counterparty name and if matched to a verified merchant in our database, we will return a `counterparty.id` along with details about the merchant. Because this endpoint supports all transaction types, the fields that are populated will vary by the type of transaction you are enriching. For example, if the transaction is an ACH payment the `transferInfo` object will be populated. For more information on For more information on interpreting enrichment responses, see our guide on [understanding enriched data](/reference/understanding-enriched-data).