Enrich a batch of card transactions with DE43 data

curl --request POST \
  --url https://east.sandbox.spade.com/batches/transactions/cards/enrich/parse \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "transactions": [
    {
      "userId": "<string>",
      "transactionId": "transaction_id_123456789",
      "amount": 123,
      "currencyCode": "<string>",
      "occurredAt": "2023-11-07T05:31:56Z",
      "categoryCode": "<string>",
      "categoryType": "MCC",
      "location": {
        "country": "<string>",
        "address": "<string>",
        "city": "<string>",
        "region": "<string>",
        "postalCode": "<string>",
        "latitude": 123,
        "longitude": 123
      },
      "de43": "<string>",
      "merchantName": "<string>",
      "cardId": "<string>",
      "cardFirstSix": "<string>",
      "cardLastFour": "<string>",
      "acquirerId": "<string>",
      "customAttributes": {}
    }
  ],
  "callbackUrl": "<string>"
}
'

{
  "batchId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "pending",
  "batchSize": 2,
  "submittedAt": "2023-11-07T05:31:56Z"
}

Card Enrichment

Enrich a batch of card transactions with DE43 data

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 [email protected] with any questions.

POST

batches

transactions

cards

enrich

parse

Enrich a batch of card transactions with DE43 data

curl --request POST \
  --url https://east.sandbox.spade.com/batches/transactions/cards/enrich/parse \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "transactions": [
    {
      "userId": "<string>",
      "transactionId": "transaction_id_123456789",
      "amount": 123,
      "currencyCode": "<string>",
      "occurredAt": "2023-11-07T05:31:56Z",
      "categoryCode": "<string>",
      "categoryType": "MCC",
      "location": {
        "country": "<string>",
        "address": "<string>",
        "city": "<string>",
        "region": "<string>",
        "postalCode": "<string>",
        "latitude": 123,
        "longitude": 123
      },
      "de43": "<string>",
      "merchantName": "<string>",
      "cardId": "<string>",
      "cardFirstSix": "<string>",
      "cardLastFour": "<string>",
      "acquirerId": "<string>",
      "customAttributes": {}
    }
  ],
  "callbackUrl": "<string>"
}
'

{
  "batchId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "pending",
  "batchSize": 2,
  "submittedAt": "2023-11-07T05:31:56Z"
}

Authorizations

X-Api-Key

string

header

required

Body

application/json

transactions

object[]

required

An array of transactions with de43's to parse and enrich. Each transaction must have a unique transactionId. Maximum 50,000 transactions.

Maximum array length: 50000

Show child attributes

transactions.userId

string

required

Anonymous ID representing your user. This will be used for summary features, and recurrence flagging purposes.

Maximum string length: 512

transactions.transactionId

string

required

Your ID representing this transaction Your ID representing this transaction. Required for batch requests.

Maximum string length: 512

Example:

"transaction_id_123456789"

transactions.amount

required

Value of the transaction in the given currency. Negative values indicate incoming money.

transactions.currencyCode

string

required

Maximum string length: 16

transactions.occurredAt

string<date-time>

required

The time the transaction occurred. Formatted as an ISO 8601 date time.

transactions.categoryCode

string

required

Category code for the given categoryType

Maximum string length: 32

transactions.categoryType

enum<string>

required

The category system that categoryCode is a part of

Available options:

MCC

Maximum string length: 32

transactions.location

object

required

Show child attributes

transactions.location.country

string

required

Three letter country code.

Maximum string length: 256

transactions.location.address

string

Maximum string length: 256

transactions.location.city

string

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.

Maximum string length: 256

transactions.location.region

string

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

Maximum string length: 256

transactions.location.postalCode

string

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

Maximum string length: 32

transactions.location.latitude

number | null

Additional latitude data related to the transaction being enriched.

transactions.location.longitude

number | null

Additional longitude data related to the transaction being enriched.

transactions.de43

string

required

The de43 to parse and enrich.

Maximum string length: 512

transactions.merchantName

string

The raw, unmodified merchant name (including asterisks, store numbers, etc...)

Maximum string length: 1024

transactions.cardId

string

Anonymous ID representing the card of the user.

Maximum string length: 512

transactions.cardFirstSix

string

The first six digits of the card number associated with the transaction.

Required string length: 6

transactions.cardLastFour

string

The last four digits of the card number associated with the transaction.

Required string length: 4

transactions.acquirerId

string

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)

Maximum string length: 256

transactions.customAttributes

object

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.

Show child attributes

transactions.customAttributes.{key}

string

Maximum string length: 250

callbackUrl

string<url>

The URL to call when the batch job is complete.

Response

Successful operation

batchId

string<uuid>

required

Unique identifier for the batch job

status

enum<string>

required

Current status of the batch job

Available options:

pending,

running,

completed,

failed

batchSize

integer

required

Number of transactions in the batch

Required range: x >= 1

submittedAt

string<date-time>

required

Timestamp of when the batch was submitted

Enrich a batch of card transactions Get the results of a batch card enrichment job

⌘I

Card Enrichment

Transfer Enrichment

Universal Enrichment

Feedback and Reporting

Merchant Search

Merchant Matching

Category Personalization

Enrich a batch of card transactions with DE43 data

Authorizations

Body

Response