Card Enrichment
- POSTEnrich a card transaction
- POSTEnrich a card transaction with an unparsed de43
- POSTEnrich a card transaction (deprecated)deprecated
- POSTEnrich a card transaction with an unparsed de43 (deprecated)deprecated
- POSTEnrich a batch of card transactions
- POSTEnrich a batch of card transactions with DE43 data
- GETGet the results of a batch card enrichment job
- GETGet the status of a batch card enrichment job
Transfer Enrichment
Universal Enrichment
Feedback and Reporting
Merchant Search
Merchant Matching
Category Personalization
- GETGet all default and custom integration-level categories
- POSTCreate a custom integration-level category
- DELDelete all custom integration-level categories
- DELDelete a custom integration-level category
- GETGet all integration-level counterparty category personalizations
- PUTCreate an integration-level counterparty category personalization
- DELDelete all integration-level counterparty category personalizations
- DELDelete a counterparty category personalization
- GETGet categories
- POSTCreate a custom user-level category
- DELDelete all custom user-level categories
- DELDelete a custom user-level category
- GETGet all user-level counterparty category personalizations
- PUTCreate a user-level counterparty category personalization
- DELDelete all user-level counterparty category personalizations
- DELDelete a user-level counterparty category personalization
curl --request POST \
--url https://east.sandbox.spade.com/transactions/cards/enrich \
--header 'Content-Type: application/json' \
--header 'X-Api-Key: <api-key>' \
--data '
{
"merchantName": "<string>",
"userId": "<string>",
"amount": 123,
"currencyCode": "<string>",
"occurredAt": "2023-11-07T05:31:56Z",
"categoryCode": "<string>",
"categoryType": "MCC",
"location": {
"city": "<string>",
"country": "<string>",
"address": "<string>",
"region": "<string>",
"postalCode": "<string>",
"latitude": 123,
"longitude": 123
},
"cardId": "<string>",
"cardFirstSix": "<string>",
"cardLastFour": "<string>",
"transactionId": "<string>",
"acquirerId": "<string>",
"customAttributes": {}
}
'{
"transactionInfo": {
"transferInfo": null,
"isAccountVerification": false,
"isPeerToPeer": false,
"isDigitalWallet": false,
"type": "account_verification",
"subType": "alimony_or_child_support",
"display": {
"name": "<string>",
"categoryName": "<string>",
"graphic": "<string>",
"graphicSource": "<string>"
},
"thirdParties": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"type": "bnpl",
"logo": "<string>",
"website": "<string>"
}
],
"spendingInfo": {
"channel": {
"value": "digital"
}
},
"atmInfo": {
"sponsorName": "<string>",
"ownerName": "<string>"
},
"transactionId": "<string>",
"recurrenceInfo": {
"intervalType": "weekly",
"intervalDays": 123,
"nextPaymentExpected": "2023-12-25",
"recentRecurrences": [
"<array>"
]
},
"riskInsights": {
"irregularWebPresenceDetected": true,
"negativeOnlineSentiment": true,
"highRiskEntity": true,
"riskyIndustry": true,
"cardAcceptanceHistory": "extensive"
}
},
"enrichmentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"counterparty": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"legalName": "<string>",
"industry": [
{
"id": "<string>",
"name": "<string>",
"icon": "<string>"
}
],
"matchScore": 123,
"location": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"address": "<string>",
"addressLine1": "<string>",
"addressLine2": "<string>",
"city": "<string>",
"region": "<string>",
"country": "<string>",
"postalCode": "<string>",
"latitude": 123,
"longitude": 123,
"phoneNumber": "<string>",
"matchScore": 123
}
],
"logo": "<string>",
"phoneNumber": "<string>",
"website": "<string>",
"possibleCounterpartyAlternate": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"similarity": 123
}
}
],
"mobileAppInfo": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"url": "<string>",
"logo": "<string>",
"developerName": "<string>",
"developerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"category": "<string>",
"hasGamblingOrRewards": true,
"hasSimulatedGambling": true,
"ageRating": "<string>"
},
"customAttributes": {}
}Enrich a card transaction
When working with this endpoint, note that several of the input fields are optional (region, acquirerId, etc.). However, we strongly recommend including all of the fields that you have available. Some optional fields can substantially improve performance.
Take care to ensure you are using unaltered and correct data in each field. Some fields go by multiple names, so if you have any questions regarding integration please feel free to reach out.
Note that some response fields may not be included in your product package, please reach out with any questions.
curl --request POST \
--url https://east.sandbox.spade.com/transactions/cards/enrich \
--header 'Content-Type: application/json' \
--header 'X-Api-Key: <api-key>' \
--data '
{
"merchantName": "<string>",
"userId": "<string>",
"amount": 123,
"currencyCode": "<string>",
"occurredAt": "2023-11-07T05:31:56Z",
"categoryCode": "<string>",
"categoryType": "MCC",
"location": {
"city": "<string>",
"country": "<string>",
"address": "<string>",
"region": "<string>",
"postalCode": "<string>",
"latitude": 123,
"longitude": 123
},
"cardId": "<string>",
"cardFirstSix": "<string>",
"cardLastFour": "<string>",
"transactionId": "<string>",
"acquirerId": "<string>",
"customAttributes": {}
}
'{
"transactionInfo": {
"transferInfo": null,
"isAccountVerification": false,
"isPeerToPeer": false,
"isDigitalWallet": false,
"type": "account_verification",
"subType": "alimony_or_child_support",
"display": {
"name": "<string>",
"categoryName": "<string>",
"graphic": "<string>",
"graphicSource": "<string>"
},
"thirdParties": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"type": "bnpl",
"logo": "<string>",
"website": "<string>"
}
],
"spendingInfo": {
"channel": {
"value": "digital"
}
},
"atmInfo": {
"sponsorName": "<string>",
"ownerName": "<string>"
},
"transactionId": "<string>",
"recurrenceInfo": {
"intervalType": "weekly",
"intervalDays": 123,
"nextPaymentExpected": "2023-12-25",
"recentRecurrences": [
"<array>"
]
},
"riskInsights": {
"irregularWebPresenceDetected": true,
"negativeOnlineSentiment": true,
"highRiskEntity": true,
"riskyIndustry": true,
"cardAcceptanceHistory": "extensive"
}
},
"enrichmentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"counterparty": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"legalName": "<string>",
"industry": [
{
"id": "<string>",
"name": "<string>",
"icon": "<string>"
}
],
"matchScore": 123,
"location": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"address": "<string>",
"addressLine1": "<string>",
"addressLine2": "<string>",
"city": "<string>",
"region": "<string>",
"country": "<string>",
"postalCode": "<string>",
"latitude": 123,
"longitude": 123,
"phoneNumber": "<string>",
"matchScore": 123
}
],
"logo": "<string>",
"phoneNumber": "<string>",
"website": "<string>",
"possibleCounterpartyAlternate": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"similarity": 123
}
}
],
"mobileAppInfo": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"url": "<string>",
"logo": "<string>",
"developerName": "<string>",
"developerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"category": "<string>",
"hasGamblingOrRewards": true,
"hasSimulatedGambling": true,
"ageRating": "<string>"
},
"customAttributes": {}
}Authorizations
Body
The raw, unmodified merchant name (including asterisks, store numbers, etc...)
1024Anonymous ID representing your user. This will be used for summary features, and recurrence flagging purposes.
512Value of the transaction in the given currency. Negative values indicate incoming money.
16The time the transaction occurred. Formatted as an ISO 8601 date time.
Category code for the given categoryType
32The category system that categoryCode is a part of
MCC 32Show child attributes
Show child attributes
The city as it appears in the transaction data; in some cases this can be a phone number or website, which are also valid inputs.
256Three letter country code.
256256Two letter code for state, province, territory, etc. For US states, ANSI codes may be provided instead (e.g. "15" for Hawaii). While standard two-letter or ANSI codes are preferred when available, full region names may also be provided (e.g. "Hawaii"). For an enhanced response, we *strongly* recommend including this field.
256A US zip code or other international postal code. In the case where a US zip code is provided and the state is missing, the state will be inferred from the zip code.
32Additional latitude data related to the transaction being enriched.
Additional longitude data related to the transaction being enriched.
Anonymous ID representing the card of the user.
512The first six digits of the card number associated with the transaction.
6The last four digits of the card number associated with the transaction.
4Your ID representing this transaction
512An alphanumeric code generally with a maximum length of 15. It is also known as "Network ID", "Card Acceptor ID", or "Merchant ID". (Found in field 42 of ISO 8583)
256A dictionary containing custom attributes that you would like to be returned in the response.
Please ensure this object does not contain any PII.
Restrictions include: customAttributes must be an object, up 30 custom attributes are allowed, each key must be a string <= 40 characters in length, and each value must be a string <= 250 characters in length.
Show child attributes
Show child attributes
250Response
Successful operation
Show child attributes
Show child attributes
Additional information about transfers. This field is null for card transactions.
Show child attributes
Show child attributes
The transfer direction.
outgoing, incoming The transfer method.
ach, cash, check, intrabank, rtp, unknown, wire The transfer type. "external" indicates that money is being sent to an external counterparty. "internal" indicates that money is being moved between accounts owned by the same entity.
external, internal, unknown Whether the transfer is an adjustment or refund.
null
Whether the transfer is an account verification. Currently only available for transfers.
false
Whether the transaction is a peer-to-peer transaction. Currently only available for transfers.
false
Whether the transaction involves a digital wallet. Currently only available for transfers.
false
The main type of the transaction. For card transactions, the type is always "spending".
account_verification, atm, debt, fee, income, other_money_movement, reimbursement, spending The more specific type of the transaction, if applicable. For card transactions, the subType is always null.
alimony_or_child_support, atm, bnpl, business, cash_advance, deposit, disbursements, earned_income, government_benefits, insurance, investment, nsf, other, overdraft, payment, payout, rental, retirement, tax_refund, transfer, withdrawal An object containing display information for the transaction. The fields in this object are pulled from other parts of the enrichment and surfaced here for convenience.
Show child attributes
Show child attributes
The best name for display.
The best category name for display.
The best graphic for display. Depending on the data available, this will be either a) the counterparty logo, b) the third party logo, or c) the category icon.
The field from which the graphic was sourced. This will be either counterparty, third_party, or category.
An array of third parties involved in the transaction, when applicable. Entities such as Toast, Square, Uber Eats, Doordash, etc. will appear here.
Show child attributes
Show child attributes
bnpl, delivery_service, payment_processor, platform Third party logo.
Third party website.
Additional information about transactions whose type is "spending". This field is null for other types of transactions.
Additional information about ATM transactions. This field is null for other types of transactions.
Your ID representing this transaction. This ID exactly matches the transactionId you provided in your enrichment request.
A recurring transaction is a repeated payment pattern to a counterparty, based on periodicty and amount. Premium Spade Signal available depending on your product package.
Show child attributes
Show child attributes
Recurrence cadence.
weekly, biweekly, monthly, quarterly, annually Number of days between recurrences.
Next expected payment date.
Array of recent recurrence objects, null if no recurrence exists.
Risk insights provide visibility into the potential risk of a transaction and the merchants involved. Premium Spade Signal available depending on your product package.
Show child attributes
Show child attributes
Has engaged in deceptive online practices or has irregular website structure or content.
Negative online consumer feedback associated with the counterparty.
The counterparty is known to engage in fraudulent practices.
Industry is correlated with increased disputes (based on Spade industries).
Counterparties with lower levels of card acceptance history have a higher likelihood of chargebacks or fraudulent activity.
extensive, established, stable, limited, very_limited, null Our ID representing the enrichment, not to be confused with your provided transactionId.
An array of counterparties matched to the transaction, ordered by descending match score.
Show child attributes
Show child attributes
A unique identifier for this counterparty, regardless of specific location.
Counterparty name.
Counterparty legal name. This is a premium Spade field available depending on your product package.
The matchScore predicts how well a transaction matches a Counterparty in our records. If no Counterparty was found, the matchScore is set to null. Otherwise, scores range between 50.00 and 100.00. We filter out results below this range to make sure that only high quality matches are returned. Generally, the higher the matchScore is the better the match between a transaction and a Counterparty. When multiple Counterparties match a transaction, matches are returned in decreasing order of matchScore. This is a premium Spade field available depending on your product package.
An array of locations matched to the transaction (and associated with this counterparty). Can currently contain only one location. This is a premium Spade field available depending on your product package.
Show child attributes
Show child attributes
A unique identifier for this location.
Street number, name, and any secondary address information.
Street number and name.
Secondary address information.
Two letter region code.
Three letter country code.
Location postal code or zip code.
Location latitude.
Location longitude.
Location phone number. This is a premium Spade field available depending on your product package.
The matchScore predicts how well a transaction matches a Location in our records. If no Location was found, the matchScore is set to null. Scores range between 0.00 and 100.0. Generally, a higher matchScore indicates a better match between a transaction and a Location. This is a premium Spade field available depending on your product package.
Counterparty logo. This is a premium Spade field available depending on your product package.
Counterparty phone number. This is a premium Spade field available depending on your product package.
Counterparty website. This is a premium Spade field available depending on your product package.
The possible alternate counterparty object represents a counterparty that may be matched to this transaction in other enrichment requests. Premium Spade Field available depending on your product package.
Show child attributes
Show child attributes
The ID of the alternate counterparty.
The similarity score indicates how closely this alternate counterparty matches the main counterparty. The score is a value between 0.0 and 100.0, where 100.0 is an exact match.
The mobile app information for the transaction. This object is only non-null if the transaction was matched to a mobile app.
This is a premium Spade field available depending on your product package.
Show child attributes
Show child attributes
A unique identifier for this mobile app.
The name of the mobile app.
The URL of the mobile app in the app store.
The URL of the mobile app's logo.
The name of the developer of the mobile app.
The ID of the developer of the mobile app.
The category of the mobile app. The possible values are:
- Auto and Transportation
- Creative and Design
- Education and Parenting
- Entertainment and Media
- Finance and Business
- Games
- Health and Lifestyle
- Shopping and Marketplaces
- Social and Communication
- Travel and Events
- Utility and Tools
Whether the mobile app has gambling or cash rewards.
Whether the mobile app has simulated gambling.
The age rating of the mobile app. The possible values are:
- Children
- Teen
- Adult