OpenAPI Specification
openapi: 3.1.0
info:
title: Spade Card 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: Card Enrichment
description: Enrich card transactions
paths:
/batches/transactions/cards/enrich/parse:
post:
tags:
- Card Enrichment
summary: Enrich a batch of card transactions with DE43 data
description: '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.
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: batchesTransactionsCardsEnrichParse
parameters:
- $ref: '#/components/parameters/SynchronousBatchParam'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BatchCardParseEnrichmentRequest'
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/BatchCardEnrichmentResponse'
title: Card 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:
- Card Enrichment
summary: Get metadata for the batch card parse 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: batchesTransactionsCardsEnrichParseOptions
responses:
'200':
description: Successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/BatchEndpointOptionsResponse'
/batches/transactions/cards/enrich:
post:
tags:
- Card Enrichment
summary: Enrich a batch of card transactions
description: '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.
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: batchesTransactionsCardsEnrich
parameters:
- $ref: '#/components/parameters/SynchronousBatchParam'
requestBody:
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/BatchCardEnrichmentRequest'
- 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/BatchCardEnrichmentResponse'
title: Card 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:
- Card Enrichment
summary: Get metadata for the batch card 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: batchesTransactionsCardsEnrichOptions
responses:
'200':
description: Successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/BatchEndpointOptionsResponse'
/transactions/enrich:
post:
tags:
- Card Enrichment
summary: Enrich a card transaction
description: Enrich a card transaction. Please use `/transactions/cards/enrich` instead. This endpoint now aliases to `/transactions/cards/enrich`.
operationId: cardEnrichDeprecated
deprecated: true
/transactions/enrich/parse:
post:
tags:
- Card Enrichment
summary: Enrich a card transaction with an unparsed de43
description: Enrich a card transaction. Please use `/transactions/cards/enrich/parse` instead. This endpoint now aliases to `/transactions/cards/enrich/parse`.
operationId: cardEnrichParseDeprecated
deprecated: true
/transactions/cards/enrich/parse:
post:
tags:
- Card Enrichment
summary: Enrich a card transaction with an unparsed de43
description: '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.
'
operationId: cardEnrichParse
requestBody:
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/CardEnrichmentRequest'
- type: object
properties:
de43:
type: string
maxLength: 100
description: A well formatted de43 message. If parsable the parsed data (merchantName, city, state) will take precedence over the corresponding fields in the request body. The parser expects an unedited de43, please do not remove special characters or spaces. Our parser currently only supports US transactions.
examples:
- WALMART.COM BENTONVILLE ARUS
responses:
'200':
description: Successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/CardEnrichmentResponse'
'400':
$ref: '#/components/responses/BadRequest'
'403':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalServerError'
/transactions/cards/enrich:
post:
tags:
- Card Enrichment
summary: Enrich a card transaction
description: '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.'
operationId: cardEnrich
requestBody:
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/CardEnrichmentRequest'
- type: object
required:
- merchantName
properties:
location:
type: object
required:
- city
- country
required: true
responses:
'200':
description: Successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/CardEnrichmentResponse'
'400':
$ref: '#/components/responses/BadRequest'
'403':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalServerError'
/batches/{cardEnrichmentBatchId}/results:
parameters:
- name: cardEnrichmentBatchId
in: path
description: ID of the batch card enrichment job
required: true
schema:
type: string
format: uuid
get:
tags:
- Card Enrichment
summary: Get the results of a batch card enrichment job
description: 'Get the results of a batch card enrichment job.
'
operationId: batchesCardEnrichGetResults
responses:
'200':
description: Successful operation
content:
application/json:
schema:
type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/BatchCardEnrichmentResponse'
title: Card 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/{cardEnrichmentBatchId}:
parameters:
- name: cardEnrichmentBatchId
in: path
description: ID of the batch card enrichment job
required: true
schema:
type: string
format: uuid
get:
tags:
- Card Enrichment
summary: Get the status of a batch card enrichment job
description: 'Get the status of a batch job.
'
operationId: batchesCardEnrichGetStatus
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.
BatchCardEnrichmentRequest:
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/BatchCardEnrichmentRequestItem'
callbackUrl:
type: string
description: Set this URL if you want to receive a notification when the batch job is complete.
format: url
examples:
- https://example.com/callback
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
BatchCardEnrichmentResponse:
allOf:
- $ref: '#/components/schemas/CardEnrichmentResponse'
- 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:
- currencyCode:
- This field is required.
categoryCode:
- This field is required.
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
BatchCardEnrichmentRequestItem:
allOf:
- $ref: '#/components/schemas/CardEnrichmentRequest'
- type: object
required:
- transactionId
- merchantName
properties:
location:
type: object
required:
- city
- country
transactionId:
type: string
maxLength: 512
description: Your ID representing this transaction. Required for batch requests.
examples:
- transaction_id_123456789
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.
CardEnrichmentRequest:
type: object
required:
- userId
- amount
- currencyCode
- occurredAt
- categoryCode
- location
properties:
merchantName:
type: string
maxLength: 1024
description: The raw, unmodified merchant name (including asterisks, store numbers, etc...)
examples:
- Amazon
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 info, 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
programId:
type: string
maxLength: 512
description: An identifier for the program associated with this transaction. Programs can be used to group transactions and scope action triggers at the program level.
examples:
- program_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
cardId:
type: string
maxLength: 512
description: Anonymous ID representing the card of the user.
examples:
- card_id_123456789
cardFirstSix:
type: string
minLength: 6
maxLength: 6
description: The first six digits of the card number associated with the transaction.
examples:
- '123456'
cardLastFour:
type: string
minLength: 4
maxLength: 4
description: The last four digits of the card number associated with the transaction.
examples:
- '7890'
transactionId:
type: string
maxLength: 512
description: Your ID representing this transaction
examples:
- transaction_id_123456789
acquirerId:
type: string
maxLength: 256
description: An 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)
examples:
- '000000000123456'
amount:
type:
- number
- string
maxLength: 15
description: Value of the transaction in the given currency. Negative values indicate incoming money.
examples:
- '25.23'
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'
categoryCode:
type: string
maxLength: 32
description: Category code for the given categoryType
examples:
- '5812'
categoryType:
type: string
maxLength: 32
minLength: 1
nullable: false
enum:
- MCC
default: MCC
examples:
- MCC
description: The category system that categoryCode is a part of. Optional; if omitted it defaults to `MCC`. Do not send `null` or an empty string — when the field is present it must be a valid, non-empty value (`MCC`).
location:
$ref: '#/components/schemas/CommonRequestLocation'
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'
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
CardEnrichmentResponse:
allOf:
- type: object
properties:
transactionInfo:
properties:
transferInfo:
examples:
- null
isAccountVerification:
examples:
- null
isPeerToPeer:
examples:
- null
isDigitalWallet:
examples:
- null
- $ref: '#/components/schemas/EnrichmentResponse'
BatchCardParseEnrichmentRequestItem:
allOf:
- $ref: '#/components/schemas/CardEnrichmentRequest'
- type: object
required:
- transactionId
- de43
properties:
transactionId:
type: string
maxLength: 512
description: Your ID representing this transaction. Required for batch requests.
examples:
- transaction_id_123456789
de43:
type: string
maxLength: 512
description: The de43 to parse and enrich.
examples:
- de43_123456789
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
# --- truncated at 32 KB (58 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/spade/refs/heads/main/openapi/spade-card-enrichment-api-openapi.yml