Authentication

Environments

Enrich your first transaction

Integrating with Spade's API

Introduction

Understanding enriched data

Overview

Batch enrichment guide

Merchant search guide

Understanding match scores

The following outlines the major concepts you will encounter while integrating with the Spade Card Transaction Enrichment API. Our goal is to enrich your transactions with high quality data, providing as much insight and clarity as possible.

Glossary

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.

Enrich a card transaction

Enrich a card transaction where parsed de43 data takes precedence over the other fields in the request body.
This otherwise endpoint is identical to `/transactions/cards/enrich` except that `city` and `merchantName` are now
optional, but only when `de43` is included. Note: Because DE43 format is not consistent between sources, we recommend parsing
your own data and using `/transactions/cards/enrich/` if possible.

Note that some response fields may not be included in your product package, please reach out to sales@spade.com with any questions.


Enrich a card transaction with an unparsed de43

Enrich a card transaction. Please use `/transactions/cards/enrich` instead. This endpoint now aliases to `/transactions/cards/enrich`.

Enrich a card transaction (deprecated)

Enrich a card transaction. Please use `/transactions/cards/enrich/parse` instead. This endpoint now aliases to `/transactions/cards/enrich/parse`.

Enrich a card transaction with an unparsed de43 (deprecated)

Submit a batch of transactions for enrichment. This endpoint will return a `batchId` which can
be used in the `/batches/{batchId}` and `/batches/{batchId}/results` endpoints to check the status of the batch job and retrieve the results.

Note that we impose a rate limit on the number of batch requests made in a rolling 12 hour window. Please reach out to
sales@spade.com with any questions.


Enrich a batch of card transactions

Submit a batch of card transactions for enrichment where de43 data in the request body takes precedence over the other fields in the request body.
Just like the `/transactions/cards/enrich/parse` endpoint, the transactions can omit `city` and `merchantName` fields if the `de43` field is present.
This endpoint returns a `batchId` which can be used in the `/batches/{batchId}` and `/batches/{batchId}/results` endpoints to check the status of the batch job and retrieve the results.

Note that we impose a rate limit on the number of batch requests made in a rolling 12 hour window. Please reach out to
sales@spade.com with any questions.


Enrich a batch of card transactions with DE43 data

Get the results of a batch card enrichment job.


Get the results of a batch card enrichment job

Get the status of a batch card enrichment job

Enrich a transfer transaction such as an ACH withdrawal, ACH deposit, or wire transfer.

When using this endpoint, take care to ensure you are using unaltered and correct data in each field.

Note that transfers enrichment is currently private, please reach out to sales@spade.com to request access.

Enrich a transfer transaction

Submit a batch of transfers for enrichment.
This endpoint will return a `batchId` which can be used in the `/batches/{batchId}` and `/batches/{batchId}/results`
endpoints to check the status of the batch job and retrieve the results.

Note that we impose a rate limit on the number of batch requests made in a rolling 12 hour window. Please reach out to
sales@spade.com with any questions.


Enrich a batch of transfers

Get the results of a batch transfer enrichment job.


Get the results of a batch transfer enrichment job

Get the status of a batch transfer enrichment job.


Get the status of a batch transfer enrichment job

Endpoint to report a card enrichment as incorrect. An `enrichmentId` and an `errorDescription` are required fields to report an enrichment. Optional request fields such as `incorrectLocation`, `incorrectLocationDescription`, `incorrectCategory`, `incorrectCategoryDescription`, `incorrectChannel`, `incorrectChannelDescription`, `incorrectCounterparty`,  and `incorrectCounterpartyDescription`, can be set to indicate what needs to be addressed in  the enrichment. Once a report has been addressed, you will receive a corrected enrichment via a callback url you set with Spade. See the callback section to learn more on how we send back a corrected enrichment.


Report a card enrichment as incorrect

An endpoint for reporting that a chargeback process has occurred on a transaction. The `state` and `chargebackNotes` properties can be used to provide information about the chargeback. The `isFraud`, `fraudType`, and `fraudNotes` are used to provide information about fraud or suspected fraud related to this chargeback. Note that this transaction must previously have been enriched to report the chargeback.


Report that a chargeback occurred

An endpoint for reporting that a card decline has occurred on a transaction. The `declineCode`, `declineDescription`, and `declineNotes` properties can be used to provide information about the decline. The `isFraud`, `fraudType`, and `fraudNotes` are used to provide information about fraud or suspected fraud related to this decline. Note that this transaction must previously have been enriched to report the decline.


Report that a card decline occurred

An endpoint for reporting that a refund has occurred on a transaction associated with an enrichment. The `refundNotes` property can be used to provide information about the refund. The `isFraud`, `fraudType`, and `fraudNotes` are used to provide information about fraud or suspected fraud related to this refund. Note that this transaction must previously have been enriched to report the refund.


Report that a refund occurred

An endpoint for reporting suspected fraud on a transaction which was not related to a chargeback, decline, or refund. If you've already indicated suspected fraud in a chargeback, decline, or refund, it's not necessary to send a request to this endpoint. The `isFraud`, `fraudType`, and `fraudNotes` fields are used to provide information about fraud or suspected fraud on this transaction. Note that this transaction must previously have been enriched to report other fraud information.


Report fraud on a transaction

Search for merchants in Spade's merchant database.

These merchants show up as counterparties and/or third parties in enrichment responses. Whether a merchant shows up as a counterparty or a third party within a given enrichment is based on the role it is playing in the transaction.

Note that merchant `ids` are relatively stable; however, they may change over time due to real-world changes (e.g. mergers and acquisitions) as well as general improvements to our merchant database which can cause a small percentage of these `ids` to shift over time.

This endpoint currently supports only a subset of Spade's merchants (mostly larger, frequently transacted merchants), with more merchants being added over time.

To learn more about merchant search, please read the [Merchant Search Guide](https://docs.spade.com/reference/merchant-search-guide).

Get detailed merchant information (beta)

Match a merchant to a Spade Counterparty and Location.


Match a merchant

Submit a batch of merchants for matching.
This endpoint will return a `batchId` which can be used in the `/batches/{batchId}` and `/batches/{batchId}/results`
endpoints to check the status of the batch job and retrieve the results.

Note that we impose a rate limit on the number of batch requests made in a rolling 12 hour window. Please reach out to
sales@spade.com with any questions.


Match a batch of merchants

Get the results of a batch merchant matching job.


Get the results of a batch merchant matching job

Get the status of a batch merchant matching job.


Get the status of a batch merchant matching job

Fetch categories from Spade's database.

This endpoint returns a list containing Spade's default categories, plus any custom integration-level categories you've created.

To learn more about category personalization, please read the [Category Personalization Guide](https://docs.spade.com/reference/category-personalization-guide).

Get all default and custom integration-level categories

Create a custom integration-level category.

This category will be available to all users of your integration.

To learn more about category personalization, please read the [Category Personalization Guide](https://docs.spade.com/reference/category-personalization-guide).

Create a custom integration-level category

Delete all custom integration-level categories.

To learn more about category personalization, please read the [Category Personalization Guide](https://docs.spade.com/reference/category-personalization-guide).

Delete all custom integration-level categories

Delete a custom integration-level category.

To learn more about category personalization, please read the [Category Personalization Guide](https://docs.spade.com/reference/category-personalization-guide).

Delete a custom integration-level category

Fetch counterparty category personalizations from Spade's database.

This endpoint returns a list containing all integration-level counterparty category personalizations for your integration.

To learn more about category personalization, please read the [Category Personalization Guide](https://docs.spade.com/reference/category-personalization-guide).

Get all integration-level counterparty category personalizations

Create an integration-level counterparty category personalization.

This personalization will apply to all enrichments that take place at the given `counterpartyId` for your integration.

To learn more about category personalization, please read the [Category Personalization Guide](https://docs.spade.com/reference/category-personalization-guide).

Create an integration-level counterparty category personalization

Delete all integration-level counterparty category personalizations.

To learn more about category personalization, please read the [Category Personalization Guide](https://docs.spade.com/reference/category-personalization-guide).

Delete all integration-level counterparty category personalizations

Delete a counterparty category personalization.

To learn more about category personalization, please read the [Category Personalization Guide](https://docs.spade.com/reference/category-personalization-guide).

Delete a counterparty category personalization

Fetch custom user-level categories from Spade's database.

This endpoint returns a list containing all custom categories that the user with the given `userId` has created.

To learn more about user category personalization, please read the [User Category Personalization Guide](https://docs.spade.com/reference/user-category-personalization-guide).

Get categories

Create a custom user-level category.

To learn more about user category personalization, please read the [User Category Personalization Guide](https://docs.spade.com/reference/user-category-personalization-guide).

Create a custom user-level category

Delete all custom user-level categories.

To learn more about user category personalization, please read the [User Category Personalization Guide](https://docs.spade.com/reference/user-category-personalization-guide).

Delete all custom user-level categories

Delete a custom user-level category.

To learn more about user category personalization, please read the [User Category Personalization Guide](https://docs.spade.com/reference/user-category-personalization-guide).

Delete a custom user-level category

Fetch user-level counterparty category personalizations from Spade's database.

This endpoint returns a list containing all user-level counterparty category personalizations for the user with the given `userId`.

To learn more about user category personalization, please read the [User Category Personalization Guide](https://docs.spade.com/reference/user-category-personalization-guide).

Get all user-level counterparty category personalizations

Create a user-level counterparty category personalization.

This personalization will apply to all enrichments that take place at the given `counterpartyId` for the user with the given `userId`.

To learn more about user category personalization, please read the [User Category Personalization Guide](https://docs.spade.com/reference/user-category-personalization-guide).

Create a user-level counterparty category personalization

Delete all user-level counterparty category personalizations.

To learn more about user category personalization, please read the [User Category Personalization Guide](https://docs.spade.com/reference/user-category-personalization-guide).

Delete all user-level counterparty category personalizations

Delete a user-level counterparty category personalization.

To learn more about user category personalization, please read the [User Category Personalization Guide](https://docs.spade.com/reference/user-category-personalization-guide).

Welcome

Enrichment Guides

Tooling Guides

More

Integrating with Spade's API

Authentication

Environments

Sandbox & Production

East & West

Enrich your first transaction

Configuration

Make the Postman request

Configuration

Make the Postman request

Welcome

Enrichment Guides

Tooling Guides

More

​Authentication

​Environments

Sandbox & Production

East & West

​Enrich your first transaction

​Configuration

​Make the Postman request

​Configuration

​Make the Postman request

Authentication

Environments

Enrich your first transaction

Configuration

Make the Postman request

Configuration

Make the Postman request