API ReferenceChangelog
API Reference

Optimizing enrichment results

ⓘ Reading Time: 10 mins

Spade's enrichment API works best when it receives unaltered, correct data in each field. In this guide, you'll see how omitting or modifying data when making requests negatively impacts match rates.

⚠

If you don't currently receive all of the required fields, we recommend reaching out to your issuer / bank partner to see if they are available.

What if I omit the region?

A few of the request fields are optional, but we strongly recommend including them whenever possible. Let's see why.

The most stark example of the impact optional fields can have on enrichment quality is the region field, which is present in 99.9% of transactions; however, in order to account for the 0.1% of transactions missing region data, we don't technically require it.

Let's see what happens if we omit the region field.

import requests

raw_transaction = {
  "occurredAt": "2023-03-14T01:42:00Z",
  "acquirerId": "123456789",
  "merchantName": "SQ*WMSUPERCENTER#582",
  "transactionId": "166c5ad8-8a94-4964-a659-03cdb64525f2",
  "userId": "f841399e-d095-4e7f-b004-c39d7e3fa329",
  "categoryCode": "5469",
  "categoryType": "MCC",
  "amount": "42.00",
  "currencyCode": "USD",
  "location": {
    "city": "PORT ORANGE",
    "country": "USA"
  }
}

response = requests.post("https://east.sandbox.spade.com/transactions/enrich", json=raw_transaction, headers={"X-Api-Key": "<Your API Key Here>"})
enriched_transaction = response.json()

print(enriched_transaction)

Sending the above request returns:

{
  "transactionInfo": {
    "type": "spending",
    "thirdParties": [
      {
        "id": "8fbe0c0b-e54a-35a8-b8ff-0d982c84fc55",
        "name": "Square",
        "type": "payment_processor",
        "logo": "/logos/8fbe0c0be54a35a8b8ff0d982c84fc55/light.png"
      }
    ],
    "spendingInfo": {
      "channel": {
        "value": "physical"
      }
    }
  },
  "counterparty": [
    {
      "id": "d730906b-f1a8-49f1-9939-f27390170a6d",
      "name": "Walmart",
      "legalName": "walmart",
      "industry": [
        {
          "id": "011-000-000-000",
          "name": "Retail",
          "icon": "https://static.v2.spadeapi.com/categories/ee4ee39fd5474d31ac42f9e606b9040a/light.png"
        },
        {
          "id": "011-018-000-000",
          "name": "General Goods",
          "icon": "https://static.v2.spadeapi.com/categories/ee4ee39fd5474d31ac42f9e606b9040a/light.png"
        },
        {
          "id": "011-018-002-000",
          "name": "Department Stores",
          "icon": "https://static.v2.spadeapi.com/categories/ee4ee39fd5474d31ac42f9e606b9040a/light.png"
        }
      ],
      "matchScore": 54.9,
      "location": [
        {
          "id": null,
          "address": null,
          "city": "Port Orange",
          "region": null,
          "postalCode": null,
          "country": "USA",
          "phoneNumber": null,
          "latitude": null,
          "longitude": null
        }
      ],
      "logo": "https://v1.spadeapi.com/logos/verified/walmart.png?size=large",
      "medianSpendPerTransaction": 22.77,
      "phoneNumber": null,
      "website": "walmart.com"
    }
  ],
  "enrichmentId": "8ec4ae92-0515-4e03-ad2a-dc83772949e1"
}

This enrichment still includes third party information, but the counterparty match is much worse (the match score is only 54.9--that's low), and the enrichment no longer includes any information about the location.

⚠

Takeaway: Always send us whatever information you have for each transaction. The more information you give us, the more likely we are to return a match. Some fields that are technically optional can significantly impact match rates if they are omitted.

What if all I have for region is an ANSI code?

For US states, we accept ANSI codes! We also accept full region names (although ANSI or two-letter codes are preferred). For instance, if the region is Florida, you can send us either FL, 12 (Florida's ANSI code), or Florida. The enrichment will end up exactly the same in all three cases.

What happens if I clean the merchantName?

Any cleaning / alteration of the merchantName significantly reduces Spade's ability to match transactions to the correct counterparties. This is because some counterparties show up similarly in transactions, with only minor differences distinguishing them. Although these differences can seem insignificant, they're often needed in order to identify the correct counterparty. Thus, any cleaning / alteration of the merchantName will significantly degrade match rates.

Let's look at an example. In this example, let's clean the merchantName by replacing special characters with spaces:

import requests

raw_transaction = {
  "occurredAt": "2023-03-14T01:42:00Z",
  "acquirerId": "123456789",
  "merchantName": "SQ WMSUPERCENTER 582",
  "transactionId": "166c5ad8-8a94-4964-a659-03cdb64525f2",
  "userId": "f841399e-d095-4e7f-b004-c39d7e3fa329",
  "categoryCode": "5469",
  "categoryType": "MCC",
  "amount": "42.00",
  "currencyCode": "USD",
  "location": {
    "city": "PORT ORANGE",
    "region": "FL",
    "country": "USA"
  }
}

response = requests.post("https://east.sandbox.spade.com/transactions/enrich", json=raw_transaction, headers={"X-Api-Key": "<Your API Key Here>"})
enriched_transaction = response.json()

print(enriched_transaction)

Sending the above request returns:

{
  "transactionInfo": {
    "type": "spending",
    "thirdParties": [],
    "spendingInfo": {
      "channel": {
        "value": "physical"
      }
    }
  },
  "counterparty": [
    {
      "id": "d730906b-f1a8-49f1-9939-f27390170a6d",
      "name": "Walmart",
      "legalName": "walmart",
      "industry": [
        {
          "id": "011-000-000-000",
          "name": "Retail",
          "icon": "https://static.v2.spadeapi.com/categories/ee4ee39fd5474d31ac42f9e606b9040a/light.png"
        },
        {
          "id": "011-018-000-000",
          "name": "General Goods",
          "icon": "https://static.v2.spadeapi.com/categories/ee4ee39fd5474d31ac42f9e606b9040a/light.png"
        },
        {
          "id": "011-018-002-000",
          "name": "Department Stores",
          "icon": "https://static.v2.spadeapi.com/categories/ee4ee39fd5474d31ac42f9e606b9040a/light.png"
        }
      ],
      "matchScore": 81.8,
      "location": [
        {
          "id": null,
          "address": null,
          "city": "Port Orange",
          "region": "FL",
          "postalCode": null,
          "country": "USA",
          "phoneNumber": null,
          "latitude": null,
          "longitude": null
        }
      ],
      "logo": "https://v1.spadeapi.com/logos/verified/walmart.png?size=large",
      "medianSpendPerTransaction": 22.77,
      "phoneNumber": null,
      "website": "walmart.com"
    }
  ],
  "enrichmentId": "ca44e63f-5278-4c4f-9228-21b0484e5042"
}

This enrichment contains even less information than the enrichment we received when we omitted the region field. It no longer contains third party information, and even though Spade correctly identified the counterparty as Walmart, the match score is a bit lower (81.8 vs. 93.6), and Spade wasn't able to determine the location.

What if the city field contains a phone number or website?

We accept both phone numbers and websites in the city field. These are often just as helpful as the actual city when matching!

Conclusion

Congratulations! You've now performed your first enrichment and learned how omitting and/or modifying fields can negatively impact enrichments.

Key takeaway: Spade's enrichment API works best when it receives unaltered, correct data in each field. Some fields are flexible in what they can receive, so always make sure to check the API docs to ensure compatibility. Overall, the more information you send us, the better your enrichment will be.

Next Steps

Understanding Match Scores

API Reference

Glossary

FAQ