openapi: 3.1.0
info:
title: Spade Card Enrichment Transfer Enrichment API
description: Documentation for Spade's card transaction enrichment API and related endpoints. We offer sandbox and production environments on both the east coast and west coast to enable ultra low latency enrichment for realtime applications. Each environment requires different API keys. To inquire about API keys, please contact your Spade representative or reach out to <hello@spade.com>.
version: 2.7.3
servers:
- url: https://east.sandbox.spade.com
description: East coast sandbox environment
- url: https://east.api.spade.com
description: East coast production environment
- url: https://west.sandbox.spade.com
description: West coast sandbox environment
- url: https://west.api.spade.com
description: West coast production environment
- url: https://sandbox.v2.spadeapi.com
description: East coast sandbox environment (deprecated)
- url: https://v2.spadeapi.com
description: East coast production environment (deprecated)
- url: https://sandbox.west.v2.spadeapi.com
description: West coast sandbox environment (deprecated)
- url: https://west.v2.spadeapi.com
description: West coast production environment (deprecated)
security:
- ApiKeyAuth: []
tags:
- name: Transfer Enrichment
description: Enrich transfers
paths:
/batches/transactions/transfers/enrich:
post:
tags:
- Transfer Enrichment
summary: Enrich a batch of transfers
description: '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.
You can pass `?synchronous=true` to enrich smaller sets of transactions synchronously. See the [Microbatch enrichment guide](https://docs.spade.com/reference/microbatch-enrichment-guide) for details.
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.
'
operationId: batchesTransferEnrich
parameters:
- $ref: '#/components/parameters/SynchronousBatchParam'
requestBody:
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/BatchTransferEnrichmentRequest'
- type: object
required:
- transactions
required: true
responses:
'200':
description: Successful operation
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BatchSubmissionResponse'
- type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/BatchTransferEnrichmentResponse'
title: Transfer Enrichment Microbatch Results
'400':
$ref: '#/components/responses/BadRequest'
'403':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalServerError'
callbacks:
batchStatusCallback:
'{$request.body#/callbackUrl}':
post:
description: 'If you set a `callbackUrl` in the body parameters of the request to the `/batches` endpoint, Spade will send a `POST` request to that `callbackUrl` when the batch job finishes. The `requestBody` of the callback request will contain the body parameters specified below. We also include a webhook token in the X-Webhook-Token header. Use this token to verify that the callback is from Spade. Contact your Spade representative if you do not have this token. If the reported status is `completed`, you can use the [/batches/{batchId}/results](https://docs.spade.com/api-reference/transfer-enrichment/get-the-results-of-a-batch-transfer-enrichment-job) endpoint to retrieve the results of the batch job.
'
requestBody:
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/BatchCallbackApiRequest'
- type: object
required:
- batchId
- status
parameters:
- in: header
name: X-Webhook-Token
schema:
type: string
required: true
description: A token that can be used to verify the callback is from Spade. This will match the token provided to you by the Spade team.
responses:
'200':
description: Your server returns this code if it accepts the callback
'500':
description: Your server encountered an unexpected error
method: post
type: path
path: '{$request.body#/callbackUrl}'
options:
tags:
- Transfer Enrichment
summary: Get metadata for the batch transfer enrichment endpoint
description: 'Returns metadata about this endpoint, including the current `synchronousMax` — the cap on items per request when `?synchronous=true`. Can be used to fetch the current cap dynamically.
'
operationId: batchesTransferEnrichOptions
responses:
'200':
description: Successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/BatchEndpointOptionsResponse'
/transactions/transfers/enrich:
post:
tags:
- Transfer Enrichment
summary: Enrich a transfer transaction
description: '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.'
operationId: transferEnrich
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TransferEnrichmentRequest'
required: true
responses:
'200':
description: Successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/TransferEnrichmentResponse'
'400':
$ref: '#/components/responses/BadRequest'
'403':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalServerError'
/batches/{transferEnrichmentBatchId}/results:
parameters:
- name: transferEnrichmentBatchId
in: path
description: ID of the batch transfer enrichment job
required: true
schema:
type: string
format: uuid
get:
tags:
- Transfer Enrichment
summary: Get the results of a batch transfer enrichment job
description: 'Get the results of a batch transfer enrichment job.
'
operationId: batchesTransactionsTransfersEnrichGetResults
responses:
'200':
description: Successful operation
content:
application/json:
schema:
type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/BatchTransferEnrichmentResponse'
title: Transfer Enrichment Batch Results
'202':
description: Batch job is not yet complete. Results aren't currently available.
content:
application/json:
schema:
$ref: '#/components/schemas/BatchGetStatusApiResponse'
'400':
$ref: '#/components/responses/BadRequest'
'403':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/BatchJobNotFound'
'500':
$ref: '#/components/responses/InternalServerError'
/batches/{transferEnrichmentBatchId}:
parameters:
- name: transferEnrichmentBatchId
in: path
description: ID of the batch transfer enrichment job
required: true
schema:
type: string
format: uuid
get:
tags:
- Transfer Enrichment
summary: Get the status of a batch transfer enrichment job
description: 'Get the status of a batch transfer enrichment job.
'
operationId: batchesTransactionsTransfersEnrichGetStatus
responses:
'200':
description: Successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/BatchGetStatusApiResponse'
'400':
$ref: '#/components/responses/BadRequest'
'403':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/BatchJobNotFound'
'500':
$ref: '#/components/responses/InternalServerError'
components:
schemas:
ThirdParty:
type: object
properties:
id:
type: string
format: uuid
examples:
- ac48cef2-0d7f-4159-865e-e92b152262bc
name:
type: string
maxLength: 64
examples:
- Paypal
type:
type: string
enum:
- bnpl
- delivery_service
- marketplace
- payment_processor
- platform
examples:
- payment_processor
logo:
type:
- string
- 'null'
maxLength: 128
format: url
examples:
- https://static.v2.spadeapi.com/logos/9063bc0f0a3f4b1fbf644f9862e17002/light.png
description: Third party logo.
website:
type:
- string
- 'null'
maxLength: 256
format: url
examples:
- https://www.paypal.com/
description: Third party website.
BatchTransferEnrichmentResponse:
allOf:
- $ref: '#/components/schemas/TransferEnrichmentResponse'
- type: object
properties:
statusCode:
type: integer
examples:
- 200
description: The HTTP status code for this element of the response array.
errors:
type: object
description: 'This field is only present if the status code is not 200.
An object containing error descriptions for this element of the response array.
'
examples:
- userId:
- This field is required.
BatchTransferEnrichmentRequestItem:
allOf:
- $ref: '#/components/schemas/TransferEnrichmentRequest'
- type: object
required:
- transactionId
properties:
transactionId:
type: string
maxLength: 512
description: Your ID representing this transaction. Required for batch requests.
examples:
- transaction_id_123456789
TransferEnrichmentResponse:
allOf:
- type: object
properties:
transactionInfo:
properties:
type:
examples:
- debt
subType:
examples:
- payment
spendingInfo:
examples:
- null
thirdParties:
items:
allOf:
- type: object
properties:
id:
examples:
- 038b7223-91b4-30bd-a2e8-851093c2f22d
name:
examples:
- Synchrony
type:
examples:
- payment_processor
logo:
examples:
- https://static.v2.spadeapi.com/logos/038b722391b430bda2e8851093c2f22d/light.png
website:
examples:
- https://synchrony.com/
- $ref: '#/components/schemas/ThirdParty'
recurrenceInfo:
examples:
- null
counterparty:
items:
allOf:
- type: object
properties:
location:
items:
allOf:
- type: object
properties:
id:
examples:
- null
address:
examples:
- null
addressLine1:
examples:
- null
addressLine2:
examples:
- null
city:
examples:
- null
region:
examples:
- null
country:
examples:
- null
postalCode:
examples:
- null
latitude:
examples:
- null
longitude:
examples:
- null
phoneNumber:
examples:
- null
matchScore:
examples:
- null
- $ref: '#/components/schemas/ResponseLocation'
possibleCounterpartyAlternate:
examples:
- null
- $ref: '#/components/schemas/Counterparty'
- $ref: '#/components/schemas/EnrichmentResponse'
IndustryCategoryLevel:
description: A node in a tree representing a hierarchical category system
type: object
properties:
id:
type: string
maxLength: 15
examples:
- 011-000-000-000
name:
type: string
maxLength: 64
examples:
- Retail
icon:
type:
- string
- 'null'
maxLength: 128
format: url
examples:
- https://static.v2.spadeapi.com/categories/ee4ee39fd5474d31ac42f9e606b9040a/light.png
description: Category icon.
BatchCallbackApiRequest:
type: object
properties:
batchId:
type: string
format: uuid
description: Unique identifier for the batch job
status:
type: string
enum:
- completed
- failed
description: Final status of the batch job
BatchGetStatusApiResponse:
type: object
properties:
batchId:
type: string
format: uuid
description: Unique identifier for the batch job
status:
type: string
enum:
- pending
- running
- completed
- failed
description: Current status of the batch job
MobileAppInfo:
description: '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.
'
type:
- object
- 'null'
properties:
id:
type:
- string
format: uuid
examples:
- 704bbd58-fb12-4bdb-9aae-2786704ea92a
description: A unique identifier for this mobile app.
name:
type:
- string
maxLength: 512
examples:
- Roblox
description: The name of the mobile app.
url:
type:
- string
- 'null'
format: url
examples:
- https://play.google.com/store/apps/details?id=com.roblox.client
description: The URL of the mobile app in the app store.
logo:
type:
- string
- 'null'
format: url
examples:
- https://static.v2.spadeapi.com/logos/58c03a73629c46b8aa4c1e15cb4f0d0b/light.png
description: The URL of the mobile app's logo.
developerName:
type:
- string
maxLength: 256
examples:
- Roblox Corporation
description: The name of the developer of the mobile app.
developerId:
type:
- string
format: uuid
examples:
- 704bbd58-fb12-4bdb-9aae-2786704ea92a
description: The ID of the developer of the mobile app.
category:
type:
- string
enum:
- 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
examples:
- Auto and Transportation
description: The category of the mobile app.
hasGamblingOrRewards:
type: boolean
examples:
- false
description: Whether the mobile app has gambling or cash rewards.
hasSimulatedGambling:
type: boolean
examples:
- false
description: Whether the mobile app has simulated gambling.
ageRating:
type:
- string
enum:
- Children
- Teen
- Adult
- Unknown
examples:
- Teen
description: The age rating of the mobile app.
TransferEnrichmentRequest:
type: object
required:
- userId
- amount
- currencyCode
- occurredAt
- transactionType
- description
properties:
organizationId:
type: string
maxLength: 256
description: An ID representing the organization associated with this transaction. Use this field if you are enriching transactions on behalf of other organizations. Used for billing purposes and for scoping products such as action triggers and category personalizations at the organization-level. For more information, see [Supporting multiple data sources and clients](https://docs.spade.com/reference/integrate-with-spades-api#supporting-multiple-data-sources-and-clients)
examples:
- organization_id_123
userId:
type: string
maxLength: 512
description: Anonymous ID representing your user. This will be used for summary features, and recurrence flagging purposes.
examples:
- user_id_123456789
accountId:
type: string
maxLength: 512
description: Anonymous ID representing the account of the user (NOT the account number).
examples:
- account_id_123456789
transactionId:
type: string
maxLength: 512
description: Your ID representing this transaction
examples:
- transaction_id_123456789
transactionType:
type: string
maxLength: 32
description: The type of this transaction. By default, the accepted types include `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`, and `OTHER_OUTGOING`; however, this endpoint also supports a variety of other transfer types, depending on your use case and the data you have available. Please contact your Spade representative if you would like further information about supported transaction types.
examples:
- 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
transactionTypeDescription:
type: string
maxLength: 64
description: A description of the `transactionType`. This field is intended for systems in which the `transactionType` is a numeric code. In these cases, `transactionTypeDescription` should be the human-readable description of the `transactionType`.
examples:
- ACH Withdrawal
- ACH Deposit
description:
type: string
maxLength: 1024
description: The full transaction description. Typically, this will be a string containing the name of the merchant or institution involved in the transaction plus information related to the type of transaction such as "ACCT VERIFY", "WEB PMT", "ETRANSFER", etc...
examples:
- AMAZON CORP SYF PAYMNT
alternateDescription:
type: string
maxLength: 1024
description: An alternate transaction description, if available. This will often be a string containing the name of the merchant or institution involved in the transaction. Note that this field is optional and may or may not be available in your system. Please contact your Spade representative if you have any questions about field mappings.
examples:
- AMAZON CORP
memo:
type: string
maxLength: 1024
description: The transaction memo, if your system contains an additional field beyond the `description` and `alternateDescription` fields. Note that this field is optional and may or may not be available in your system. Please contact your Spade representative if you have any questions about field mappings.
examples:
- 100 PUBLIC SQUARE CLEVELAND OH
amount:
type:
- number
- string
maxLength: 15
description: Value of the transaction in the given currency. Negative values indicate incoming money.
examples:
- '283.78'
currencyCode:
type: string
maxLength: 16
examples:
- USD
occurredAt:
type: string
format: date-time
description: The time the transaction occurred. Formatted as an ISO 8601 date time.
examples:
- '2022-06-15 18:27:51Z'
direction:
type: string
maxLength: 8
description: The direction of the transaction. Will take precedence over the direction inferred from the `amount` field.
enum:
- CREDIT
- DEBIT
examples:
- CREDIT
- DEBIT
billingProfile:
type: string
enum:
- standard
- resell
description: An optional billing profile for this transaction. When set to "resell", the `organizationId` field is required. For more information, see [Supporting multiple data sources and clients](https://docs.spade.com/reference/integrate-with-spades-api#supporting-multiple-data-sources-and-clients)
examples:
- standard
customAttributes:
$ref: '#/components/schemas/CustomAttributesRequestField'
BatchTransferEnrichmentRequest:
type: object
required:
- transactions
properties:
transactions:
type: array
description: An array of transactions to enrich. Each transaction must have a unique transactionId. Maximum 50,000 transactions.
maxItems: 50000
items:
$ref: '#/components/schemas/BatchTransferEnrichmentRequestItem'
callbackUrl:
type: string
description: The URL to call when the batch job is complete.
format: url
examples:
- https://example.com/callback
ResponseLocation:
type: object
properties:
id:
type:
- string
- 'null'
format: uuid
examples:
- fdf79470-3deb-4638-956a-6859e473b9d8
description: A unique identifier for this location.
address:
type:
- string
- 'null'
maxLength: 64
examples:
- 1234 W 5th Ave Suite 100
description: Street number, name, and any secondary address information.
addressLine1:
type:
- string
- 'null'
maxLength: 64
examples:
- 1234 W 5th Ave
description: Street number and name.
addressLine2:
type:
- string
- 'null'
maxLength: 32
examples:
- Suite 100
description: Secondary address information.
city:
type:
- string
- 'null'
maxLength: 64
examples:
- New York
region:
type:
- string
- 'null'
maxLength: 64
examples:
- NY
description: Region code. Typically a two-letter code for US states, but may vary for international regions.
country:
type:
- string
- 'null'
maxLength: 3
examples:
- USA
description: Three letter country code.
postalCode:
type:
- string
- 'null'
maxLength: 12
examples:
- '10001'
description: Location postal code or zip code.
latitude:
type:
- number
- 'null'
examples:
- 45
description: Location latitude.
longitude:
type:
- number
- 'null'
examples:
- 120
description: Location longitude.
phoneNumber:
type:
- string
- 'null'
maxLength: 24
examples:
- '+18664862360'
description: Location phone number. This is a premium Spade field available depending on your product package.
matchScore:
description: '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.
'
type:
- number
- 'null'
examples:
- 93.5
CustomAttributesRequestField:
type: object
maxProperties: 30
description: 'A 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.
'
additionalProperties:
type: string
maxLength: 250
examples:
- custom_attribute_1: value_1
custom_attribute_2: value_2
CustomAttributesResponseField:
type: object
description: A dictionary containing the custom attributes that were included in the enrichment request (if any).
additionalProperties:
type: string
examples:
- custom_attribute_1: value_1
custom_attribute_2: value_2
TriggeredActionResponse:
type: object
description: A triggered action returned in the enrichment response.
properties:
id:
type: string
maxLength: 512
description: Your unique identifier for the matched trigger (as provided during registration).
examples:
- trigger-12345
type:
type: string
description: The type of trigger that matched — `merchant_trigger` for merchant-based triggers, `category_trigger` for category-based triggers.
enum:
- merchant_trigger
- category_trigger
example: merchant_trigger
examples:
- merchant_trigger
action:
type: object
description: 'The custom action data you provided during registration for this trigger.
For `BLOCK` and `ALLOW_ONLY` action types, an `authRecommendation` field is automatically added:
- `BLOCK` triggers: `authRecommendation` is set to `"BLOCK"`.
- `ALLOW_ONLY` triggers that match: `authRecommendation` is set to `"ALLOW"`.
- `ALLOW_ONLY` triggers that do not match (inverse semantics): `authRecommendation` is set to `"BLOCK"`.
'
additionalProperties: true
properties:
authRecommendation:
type: string
description: Authorization recommendation injected for `BLOCK` and `ALLOW_ONLY` action types. Not present for other action types.
enum:
- ALLOW
- BLOCK
examples:
- type: REWARD
rewardPercent: 5
offerId: offer-abc123
- type: BLOCK
reason: Gambling merchant
authRecommendation: BLOCK
- type: ALLOW_ONLY
category: approved-vendors
authRecommendation: ALLOW
scope:
type: string
description: The scope at which this trigger was registered (account, program, user, or card).
enum:
- account
- program
- user
- card
example: account
examples:
- account
source:
type:
- string
- 'null'
description: 'Indicates whether the action was triggered by the matched counterparty or third party.
This field will be set to `null` when an `ALLOW_ONLY` action trigger was set up whose condition the current transaction did not meet. The `authRecommendation` in this case will be `BLOCK`.
'
enum:
- counterparty
- third_party
- null
example: counterparty
examples:
- counterparty
categoryId:
type: string
description: The Spade category ID that matched this trigger. Only present when `type` is `category_trigger`.
examples:
- b4b0d249-b402-49ac-b744-5027d4574fc5
categoryName:
type: string
description: The name of the Spade category that matched this trigger. Only present when `type` is `category_trigger`.
examples:
- Travel
BatchSubmissionResponse:
type: object
required:
- batchId
- status
- batchSize
- submittedAt
properties:
batchId:
type: string
format: uuid
description: Unique identifier for the batch job
status:
type: string
enum:
- pending
- running
- completed
- failed
description: Current status of the batch job
batchSize:
type: integer
minimum: 1
description: Number of transactions in the batch
examples:
- 1
submittedAt:
type: string
format: date-time
description: Timestamp of when the batch was submitted
examples:
- '2024-11-21T20:07:20.213660Z'
Counterparty:
type: object
properties:
id:
type:
-
# --- truncated at 32 KB (52 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/spade/refs/heads/main/openapi/spade-transfer-enrichment-api-openapi.yml