> ## 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.
# Transfer enrichment guide
## Overview
The transfer enrichment endpoint supports enriching ACH, Wire, ATM, P2P, and Check transactions.
This guide outlines best practices for integrating with the transfer enrichment endpoint and how to use the enriched data that is returned.
Transfer 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 recommendations for how to send data to the transfer enrichment endpoint.
The fields for this endpoint are flexible and we recommend working with the Spade team to optimize your integration for the best results.
### Description
The description field typically will include a combination of:
* A company or financial institution name (e.g. "Spade Bank")
* A description of the transaction (e.g. "AUTOPAY")
The full description you provide to Spade may exist as a single field or multiple fields within your current platform. If there are multiple fields they should be combined so that the company or financial institution name preceeds the transaction description. Below we've provided an example of how that would be provided in the API request:
` "description": "Spade Bank AUTOPAY"`
### Memo
Memo is not a required field; however, if the transaction has a memo associated with it, such as for an ATM transaction, you should include that in the request. Alternatively, if the ATM-involved transaction includes location data, you can pass it in the memo field and combine the address, city, and state like:
`"memo": "1 E FORDHAM RD BR BRONX NY"`
### Transaction type
In addition to the description, you'll need to provide a `transactionType` which will be one of:
* `ACH_DEPOSIT`
* `ACH_RETURN`
* `ACH_WITHDRAWAL`
* `ATM`
* `CHECK_DEPOSIT`
* `CHECK_PAYMENT`
* `INTERNATIONAL_WIRE_INCOMING`
* `INTERNATIONAL_WIRE_OUTGOING`
* `RTP_DEPOSIT`
* `RTP_WITHDRAWAL`
* `US_WIRE_INCOMING`
* `US_WIRE_OUTGOING`
* `OTHER_INCOMING`
* `OTHER_OUTGOING`
If you have a system that has custom transaction types that don't fall into the values required for `transactionType` work with your Spade representative for alternative options.
### Transaction amount and direction
We recommend using a negative `amount` to indicate incoming transfers, and a positive `amount` to indicate outgoing transfers. Alternatively, you can use the `direction` field to specify whether the transfer is a `credit` or `debit.`
### Using identifiers
We recommend providing a `transactionId` so that you can map our enrichment response and corresponding `enrichmentId` to your transaction-level data store. This field is required for batch transfer enrichment.
A `userId` is required for all enrichment endpoints (max 512 characters). This should not include any PII - if you don't have the concept of a user on your platform you can use any identifier that groups transactions made by the same individual or organization.
For premium features such as recurrence and category personalization a unique `userId` is required.
Additional metadata about the transaction or user can be provided in the `customAttributes` object and the enrichment response will return the original values provided.
### Example transfer enrichment requests and responses
Below are example requests and responses for different transfer transaction types:
```json ACH withdrawal request theme={null}
{
"amount": "10.00",
"userId": "user_id_123456789",
"occurredAt": "2022-06-15 18:27:51Z",
"description": "CITI CARDS ONLINE PMT",
"currencyCode": "USD",
"transactionId": "transaction_id_123456789",
"transactionType": "ACH_WITHDRAWAL"
}
```
```json ACH withdrawal response theme={null}
{
"transactionInfo": {
"type": "debt",
"subType": "payment",
"display": {
"name": "Citi",
"categoryName": "Banking and Finance",
"graphic": "https://static.v2.spadeapi.com/logos/3f971f36fe7549c29a2c494a8a990334/light.png",
"graphicSource": "counterparty"
},
"thirdParties": [],
"spendingInfo": null,
"transferInfo": {
"direction": "outgoing",
"transferMethod": "ach",
"transferType": "external",
"isAdjustmentOrRefund": false
},
"atmInfo": null,
"isAccountVerification": false,
"isPeerToPeer": false,
"isDigitalWallet": false,
"transactionId": "transaction_id_123456789",
"recurrenceInfo": null,
"irregularWebPresenceDetected": false
},
"counterparty": [
{
"id": "3f971f36-fe75-49c2-9a2c-494a8a990334",
"name": "Citi",
"legalName": "Citigroup Inc.",
"industry": [
{
"id": "001-000-000-000",
"name": "Banking and Finance",
"icon": "https://static.v2.spadeapi.com/categories/61897b3a5af545bab45ca1bf20498e65/light.png"
}
],
"location": [
{
"id": null,
"address": null,
"addressLine1": null,
"addressLine2": null,
"city": null,
"region": null,
"postalCode": null,
"country": null,
"phoneNumber": null,
"latitude": null,
"longitude": null,
"matchScore": null
}
],
"matchScore": null,
"logo": "https://static.v2.spadeapi.com/logos/3f971f36fe7549c29a2c494a8a990334/light.png",
"medianSpendPerTransaction": null,
"phoneNumber": "+16462912727",
"website": "https://www.citi.com/"
}
],
"enrichmentId": "7e40312d-91a4-4744-a987-1fac6e574bde"
}
```
```json ACH deposit request theme={null}
{
"amount": "-10.00",
"userId": "user_id_123456789",
"occurredAt": "2025-06-15 19:12:43Z",
"description": "Fanatics SptsBk ViaTrustly",
"currencyCode": "USD",
"transactionId": "transaction_id_123456789",
"transactionType": "ACH_DEPOSIT"
}
```
```json ACH deposit response theme={null}
{
"transactionInfo": {
"type": "income",
"subType": "other",
"display": {
"name": "Fanatics Sportsbook",
"categoryName": "Casinos and Gambling",
"graphic": "https://static.v2.spadeapi.com/logos/f36c7cc562c23b209af06e1e98c6d25f/light.png",
"graphicSource": "counterparty"
},
"thirdParties": [],
"spendingInfo": null,
"transferInfo": {
"direction": "outgoing",
"transferMethod": "ach",
"transferType": "external",
"isAdjustmentOrRefund": false
},
"atmInfo": null,
"isAccountVerification": false,
"isPeerToPeer": false,
"isDigitalWallet": false,
"transactionId": "transaction_id_123456789",
"recurrenceInfo": null,
"irregularWebPresenceDetected": false
},
"counterparty": [
{
"id": "f36c7cc5-62c2-3b20-9af0-6e1e98c6d25f",
"name": "Fanatics Sportsbook",
"legalName": "Fanatics Holdings, Inc.",
"industry": [
{
"id": "004-000-000-000",
"name": "Entertainment",
"icon": "https://static.v2.spadeapi.com/categories/ff2e4086c1f14e368e086aadab182b19/light.png"
},
{
"id": "004-007-000-000",
"name": "Casinos and Gambling",
"icon": "https://static.v2.spadeapi.com/categories/ff2e4086c1f14e368e086aadab182b19/light.png"
}
],
"location": [
{
"id": null,
"address": null,
"addressLine1": null,
"addressLine2": null,
"city": null,
"region": null,
"postalCode": null,
"country": null,
"phoneNumber": null,
"latitude": null,
"longitude": null,
"matchScore": null
}
],
"matchScore": null,
"logo": "https://static.v2.spadeapi.com/logos/f36c7cc562c23b209af06e1e98c6d25f/light.png",
"medianSpendPerTransaction": null,
"phoneNumber": "+18002540320",
"website": "https://www.fanaticsinc.com/"
}
],
"enrichmentId": "c4a482e3-7c25-48da-8d56-4eee7b307635"
}
```
```json ATM request theme={null}
{
"userId": "user123",
"accountId": "account123",
"transactionId": "transaction_id_123456789",
"amount": "20.00",
"transactionType": "ATM",
"occurredAt": "2025-8-15T1:42:00Z",
"currencyCode": "USD",
"memo": "1 E FORDHAM RD BR BRONX NY"
}
```
```json ATM response theme={null}
{
"transactionInfo": {
"type": "spending",
"subType": null,
"display": {
"name": "Citizens Bank - ATM",
"categoryName": "Banking and Finance",
"graphic": "https://static.v2.spadeapi.com/logos/33a58f5dfe9c3235af7cbafe781e5f85/light.png",
"graphicSource": "counterparty"
},
"thirdParties": [],
"spendingInfo": null,
"transferInfo": {
"direction": "outgoing",
"transferMethod": "unknown",
"transferType": "unknown",
"isAdjustmentOrRefund": false
},
"atmInfo": {
"ownerName": "Citizens Bank",
"sponsorName": "Fiserv"
},
"isAccountVerification": false,
"isPeerToPeer": false,
"isDigitalWallet": false,
"transactionId": "transaction_id_123456789",
"recurrenceInfo": null
},
"counterparty": [
{
"id": "33a58f5d-fe9c-3235-af7c-bafe781e5f85",
"name": "Citizens Bank",
"legalName": "Citizens Financial Group, Inc.",
"industry": [
{
"id": "001-000-000-000",
"name": "Banking and Finance",
"icon": "https://static.v2.spadeapi.com/categories/61897b3a5af545bab45ca1bf20498e65/light.png"
}
],
"location": [
{
"id": "d1bce13f-caf3-39c1-b7e2-b75c1b661858",
"address": "1 E Fordham Rd",
"addressLine1": "1 E Fordham Rd",
"addressLine2": null,
"city": "Bronx",
"region": "NY",
"postalCode": "10468",
"country": "USA",
"phoneNumber": "+17185039811",
"latitude": 40.862779,
"longitude": -73.900569,
"matchScore": null
}
],
"matchScore": null,
"logo": "https://static.v2.spadeapi.com/logos/33a58f5dfe9c3235af7cbafe781e5f85/light.png",
"medianSpendPerTransaction": null,
"phoneNumber": "+18009229999",
"website": "https://www.citizensbank.com/HomePage.aspx"
}
],
"enrichmentId": "1a6f18c3-be5f-42a2-b190-2d51c8b5dfda"
}
```
### **Batch vs real-time**
We offer both [real-time](/reference/transfer-enrichment) and [batch](/reference/batch-enrichment-guide) enrichment for transfers. If you don't need the data in real-time, we recommend batching transfer data, ideally in batches of 50k transactions at a time (see our [batch enrichment guide](/reference/batch-enrichment-guide) for more information).
### Error Handling
The most common errors result from not sending required fields or providing invalid values for fields such as `transactionType` . The error response object will include specific details to reprocess the request.
```json theme={null}
{
"transactionType": [
"Invalid value: ''. Must be one of ['ACH_DEPOSIT', 'ACH_RETURN', 'ACH_WITHDRAWAL', 'ATM', 'CHECK_DEPOSIT', 'CHECK_PAYMENT', 'INTERNATIONAL_WIRE_INCOMING', 'INTERNATIONAL_WIRE_OUTGOING', 'RTP_DEPOSIT', 'RTP_WITHDRAWAL', 'US_WIRE_INCOMING', 'US_WIRE_OUTGOING', 'OTHER_INCOMING', 'OTHER_OUTGOING']."
]
}
```
## Understanding enriched transfer data
For this guide, we will focus on enriched fields unique to transfer enrichment. More information can be found in our [understanding enriched data guide](/reference/understanding-enriched-data).
### Transaction types and subtypes
In the enrichment response we provide a `type` and if possible a `subType` which can provide more detail about the transaction.
| type | subType | description |
| :--------------------: | :----------------------------------------------------------------------------------------------------------------------------------------: | --------------------------------------------------------------------------- |
| `atm` | `deposit`
`withdrawal`
`transfer` | ATM involved transactions |
| `debt` | `bnpl`
`disbursement`
`payment`
`other` | Debt involved transactions such as paying off a loan or credit card |
| `fee` | `atm`
`cash_advance`
`nsf`
`overdraft`
`transfer`
`other` | Fee related transactions |
| `income` | `earned_income`
`payout`
`investment`
`government_benefits`
`alimony_or_child_support`
`rental`
`retirement` | Income related transactions |
| `reimbursement` | `tax_refund`
`business`
`insurance`
`other` | Reimbursement related transactions such as tax refunds or insurance payouts |
| `spending` | null | Outgoing transfers that don't fall into another type/sub-type |
| `other_money_movement` | null | Incoming transfers that don't fall into another type/sub-type |
### Transfer transaction flags
Additionally, we provide the following boolean flags which, when `true` , provide additional context about the transaction:
| flag | definition |
| ----------------------- | ------------------------------------------------------------------- |
| `isAccountVerification` | Used to denote account verification transfers such as microdeposits |
| `isPeerToPeer` | Whether the transaction is a peer-to-peer transaction (e.g. Zelle) |
| `isDigitalWallet` | Whether the transaction is to a digital wallet (e.g. Apple Wallet) |
### Using transfer data in your UI
We provide a `display` object in the response that provides our recommendation for displaying a clean merchant name, category. and logo. If you want to customize what is displayed to end users, you can use the individual data elements returned in the enrichment response.
When a transaction takes place at an ATM we will return a `display.name` that appends " - ATM" to the name of the ATM sponsor or financial institution like so:
```json theme={null}
"display": {
"name": "Spade Bank - ATM",
"graphic": "https://static.v2.spadeapi.com/logos/1234/light.png",
"categoryName": "Banking and Finance",
"graphicSource": "counterparty"
}
```
Transfer enrichments will often return a category of 'Banking and Finance' when the counterparty is a financial institution. Depending on your use case you may want to use the `transactionInfo.type` and `transactionInfo.subType` in lieu of the category.
For best practices, check out our guide on [improving user experience with Spade](/reference/improved-ux).