Universal Enrichment

Enrich a universal transaction

Enrich any type of transaction such as an aggregator transaction, card transaction, ACH withdrawal, ACH deposit, or wire transfer.

Note that universal enrichment is currently in beta, please reach out to sales@spade.com to request access.

Request body

organizationIdstring

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

userIdstring required

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

accountIdstring

Anonymous ID representing the account of the user (NOT the account number).

transactionIdstring

Your ID representing this transaction

descriptionstring required

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

currencyCodestring required

occurredAtstring date-time required

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

direction'CREDIT' | 'DEBIT'

The direction of the transaction. Will take precedence over the direction inferred from the amount field.

billingProfile'standard' | 'resell'

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

customAttributesCustomAttributesRequestField

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.

Example request

{
  "organizationId": "organization_id_123",
  "userId": "user_id_123456789",
  "accountId": "account_id_123456789",
  "transactionId": "transaction_id_123456789",
  "description": "AMAZON CORP SYF PAYMNT",
  "currencyCode": "USD",
  "occurredAt": "2022-06-15 18:27:51Z",
  "direction": "CREDIT",
  "billingProfile": "standard",
  "customAttributes": {
    "custom_attribute_1": "value_1",
    "custom_attribute_2": "value_2"
  }
}

Response

Successful operation

enrichmentIdstring uuid

Our ID representing the enrichment, not to be confused with your provided transactionId.

customAttributesCustomAttributesResponseField

A dictionary containing the custom attributes that were included in the enrichment request (if any).

Example response

{
  "transactionInfo": {
    "type": "spending",
    "thirdParties": [
      {
        "id": "ac48cef2-0d7f-4159-865e-e92b152262bc",
        "name": "Paypal",
        "type": "payment_processor",
        "logo": "https://static.v2.spadeapi.com/logos/9063bc0f0a3f4b1fbf644f9862e17002/light.png",
        "website": "https://www.paypal.com/"
      }
    ],
    "recurrenceInfo": {
      "intervalDays": 30,
      "nextPaymentExpected": "2024-08-07"
    },
    "display": {
      "name": "Amazon",
      "categoryName": "Online Marketplace",
      "graphic": "https://static.v2.spadeapi.com/logos/de33f8973bc934c5b368a5b27155db02/light.png",
      "graphicSource": "counterparty"
    },
    "transferInfo": {
      "direction": "outgoing",
      "transferMethod": "ach",
      "transferType": "external"
    },
    "atmInfo": {
      "sponsorName": "Fiserv",
      "ownerName": "Wells Fargo"
    },
    "transactionId": "transaction_id_123456789",
    "riskInsights": {
      "cardAcceptanceHistory": "extensive"
    }
  },
  "counterparty": [
    {
      "location": [
        {
          "id": "fdf79470-3deb-4638-956a-6859e473b9d8",
          "address": "1234 W 5th Ave Suite 100",
          "addressLine1": "1234 W 5th Ave",
          "addressLine2": "Suite 100",
          "city": "New York",
          "region": "NY",
          "country": "USA",
          "postalCode": "10001",
          "latitude": 45,
          "longitude": 120,
          "phoneNumber": "+18664862360",
          "matchScore": 93.5
        }
      ],
      "possibleCounterpartyAlternate": {
        "id": "49fd51a1-5a19-3e5d-8d28-eb056ecf8939",
        "similarity": 80
      },
      "id": "704bbd58-fb12-4bdb-9aae-2786704ea92a",
      "name": "Amazon",
      "legalName": "Amazon Inc.",
      "industry": [
        {
          "id": "011-000-000-000",
          "name": "Retail",
          "icon": "https://static.v2.spadeapi.com/categories/ee4ee39fd5474d31ac42f9e606b9040a/light.png"
        }
      ],
      "matchScore": 93.5,
      "logo": "https://static.v2.spadeapi.com/logos/de33f8973bc934c5b368a5b27155db02/light.png",
      "phoneNumber": "+18664862360",
      "website": "https://www.amazon.com"
    }
  ],
  "mobileAppInfo": {
    "id": "704bbd58-fb12-4bdb-9aae-2786704ea92a",
    "name": "Roblox",
    "url": "https://play.google.com/store/apps/details?id=com.roblox.client",
    "logo": "https://static.v2.spadeapi.com/logos/58c03a73629c46b8aa4c1e15cb4f0d0b/light.png",
    "developerName": "Roblox Corporation",
    "developerId": "704bbd58-fb12-4bdb-9aae-2786704ea92a",
    "category": "Auto and Transportation",
    "ageRating": "Teen"
  },
  "customAttributes": {
    "custom_attribute_1": "value_1",
    "custom_attribute_2": "value_2"
  },
  "actions": [
    {
      "id": "trigger-12345",
      "type": "merchant_trigger",
      "action": {
        "type": "REWARD",
        "rewardPercent": 5
      },
      "scope": "account",
      "source": "counterparty"
    }
  ]
}

Enrich a universal transaction

Request

Request body

Example request

Response 200OK

Example response

Changes

Response