Real-time merchant matching guide
Merchant matching is not enabled by default. To request access, please contact us at .
Overview
Real time merchant matching allows you to effectively match a small volume of merchants to locations and counterparties in Spade’s database. In this guide, we’ll use the /merchants/ match
POST
endpoint to submit a real-time merchant match.
Request Schema
Tip: Latitude & longitude are the strongest disambiguators after name + address. Use them when you have them.
Performing Your First Match
1. Prepare the payload
Pick a merchant from your database — ideally one with a full postal address.
2. Send the request
A minimal cURL equivalent:
3. Inspect the response
Response Breakdown
counterparty
Field | Description |
---|---|
id | Spade Counterparty ID |
name | Canonical business name. |
similarity | 0–100 match confidence. |
location
Field | Description |
---|---|
id | Spade Location ID |
name | Location‑level business name (if distinct from brand). |
address | Cleansed, correctly cased postal address. |
city | Cleaned city corresponding to the Location |
similarity | Confidence that this physical location is the one you provided. |
Similarity vs. Match Score? For merchant matching we use similarity (string & geo distance based). Card enrichment uses matchScore (ML model across many signals). Treat them the same way: higher = better.
Handling Non‑Matches
A null counterparty
or location
means we couldn’t find an acceptable match. Typical reasons:
- Typos or missing street numbers
- Recently opened stores not yet in our DB
- PO boxes or corporate HQ addresses
What to do
- Retry with more info – add latitude/longitude if you have it.
- Store as unknown – save the original name; you can re‑run matching later.
Batch Matching (Optional)
If you have > 1000 merchants, use POST /batches/merchants/match
. Learn more in our batch merchant matching guide.
Implementation Notes
- Content‑Type must be
application/json
. Some HTTP tools fallback tomultipart/form-data
; override it explicitly. - 400 errors → invalid or missing required fields (address, city, region, postalCode, country, merchantName). Parse the response JSON for details.
- 403 errors → invalid or missing API key.
- 500 errors → Spade’s infrastructure. These are rare; exponential back‑off is recommended.
If your request includes a suite, apartment, or unit designator (e.g., “123 Main St Ste 204”) and you don’t get a satisfactory match, resend the request without the suite information. Likewise, if your original request omits the suite but still fails to match, try adding the suite/apt/unit string. Suite tags are recorded inconsistently across data providers, so toggling them on or off often nudges a borderline similarity score over the threshold.
Best Practices Checklist ✅
Done? | Recommendation |
---|---|
Send full street address and city/region/postalCode. | |
Provide latitude/longitude when available (mobile checkouts, GPS capture). | |
Store counterparty.id and location.id once → attach to every transaction. | |
Decide on a similarity threshold (e.g., drop matches <70 ). | |
Use batch matching for historical backfills and weekly sync jobs. |