Batch Merchant Matching Guide

ⓘ Reading Time: 10 mins

Batch merchant matching allows you to efficiently match a large volume of merchants to Locations and Counterparties in Spade's Database. You can submit up to 50,000 merchants in a single request and retrieve the matching results once processing is complete. In this guide, we'll use the /batches/merchants/match POST endpoint to submit a batch of merchants, the /batches/{batchId} GET endpoint to check the batch status, and the /batches/{batchId}/results GET endpoint to retrieve the results.

Getting Started

1. Submit Your Batch of Merchants

import requests

merchants = [
    {
        "id": "unique_id_123",
        "merchantName": "Amazon",
        "address": "1234 W 5th Ave",
        "city": "New York",
        "region": "NY",
        "country": "USA",
        "postalCode": "10001"
    },
    # ... more merchants ...
]

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

batch_id = response.json()["batchId"]
print(f"Batch submitted with ID: {batch_id}")

2. Receive Completion Notification or Check Status

You have two options to determine when your batch is complete:

• Option A: Receive a callback notification (recommended) Include a callbackUrl in your batch submission to receive an automated notification when processing completes.

• Option B: Poll for status Periodically check the batch status endpoint.

For detailed implementation of both methods, including callback authentication and handling, refer to the Batch Enrichment Guide. Both batch endpoints use the same callback mechanism.

3. Retrieve the Results

Once the batch is complete, retrieve the results.

response = requests.get(
    f"https://east.sandbox.spade.com/batches/{batch_id}/results",
    headers={"X-Api-Key": "<Your API Key Here>"}
)

results = response.json()["matches"]

for match in results:
    print(f"Matched Merchant ID: {match['merchantId']}")
    print(f"Counterparty Name: {match['counterpartyName']}")
    print(f"Spade's Counterparty ID: {match['counterpartyId']}")
    print(f"Merchant Similarity Score: {match['merchantSimilarity']}")
    print(f"Address Similarity Score: {match['addressSimilarity']}")

Using the Similarity Scores

We provide two similarity scores for each match; merchantSimilarity and addressSimilarity. The merchantSimilarity score is a measure of how similar the merchant name in the request is to the counterparty name in the response. The addressSimilarity score is a measure of how similar the merchant address in the request is to the counterparty address in the response.

The scores are between 0 and 100, where 100 is a perfect match. We recommend experimenting with the threshold for what constitutes a "good" match for your use case.

Handling Non-Matches

It's possible that there is either no counterparty and/or location match for a merchant given the provided input. In these cases, you can still expect a response object in the matches array. However, the counterpartyId and/or location.id will be null for the corresponding merchant.

Best Practices

For best practices regarding unique IDs, status polling, timeouts, and error handling, please refer to the Batch Enrichment Guide.