​
Overview

The transfer enrichment endpoint supports enriching ACH, Wire, ATM, and P2P 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.

​
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 finanical 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_WITHDRAWAL, or ATM.
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 enrcihmentId to your transaction-level data store. This field is required for batch transfer enrichment. A userId is required for all enrichment endpoints. 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: 
{
   "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"
}

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

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

​
Batch vs real-time

We offer both real-time and batch 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 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. 
{
  "transactionType": [
    "Invalid value: ''. Must be one of ['ACH_DEPOSIT', 'ACH_WITHDRAWAL', 'ATM', 'CARD']."
  ]
}

​
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.

​
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.
typesubTypedescription
atmdeposit
withdrawal
transfer		ATM involved transactions
debtbnpl
disbursement
payment
other		Debt involved transactions such as paying off a loan or credit card
feeatm
cash_advance
nsf
overdraft
transfer
other		Fee related transactions
incomeearned_income
payout
investment
government_benefits
alimony_or_child_support
rental
retirement		Income related transactions
reimbursementtax_refund
business
insurance
other		Reimbursement related transactions such as tax refunds or insurance payouts
spendingnullOutgoing transfers that don’t fall into another type/sub-type
other_money_movementnullIncoming 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:
flagdefinition
isAccountVerificationUsed to denote account verification transfers such as microdeposits
isPeerToPeerWhether the transaction is a peer-to-peer transaction (e.g. Zelle)
isDigitalWalletWhether 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: 
"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.