Skip to main content
Merchant search is in beta and is not enabled by default. To request access, contact us at sales@spade.com.

​
Overview

Merchant search lets you query Spade’s merchant database by name. It is designed for powering autocomplete experiences — as a user types, your application queries GET /corporations and displays matching merchants with their name, logo, and website. The endpoint returns up to five results ordered by relevance. Use the returned name and website to register merchants with Spade’s action triggers endpoint for rewards, merchant-locked cards, and other transaction-level actions.

​
Searching for a merchant

Send a GET request to /corporations with the merchant name as a query parameter. 
import requests

response = requests.get(
    "https://east.sandbox.spade.com/corporations",
    params={"name": "star"},
    headers={"X-Api-Key": "<Your API Key>"},
)

print(response.json())

​
Response

{
  "corporations": [
    {
      "name": "Starbucks",
      "logo": "https://static.v2.spadeapi.com/logos/.../light.png",
      "website": "starbucks.com"
    },
    {
      "name": "Starlink",
      "logo": "https://static.v2.spadeapi.com/logos/.../light.png",
      "website": "starlink.com"
    }
  ]
}

​
Response fields

FieldTypeDescription
namestringThe merchant’s name
logostring | nullURL of the merchant’s logo, or null if unavailable
websitestring | nullThe merchant’s website, or null if unavailable

​
Building a merchant autocomplete

​
Backend proxy

Your backend should proxy requests to Spade so that your API key is never exposed to the client.
Never send your API key to the client. This includes any client-side application code bundles (websites, mobile apps, etc.).
from flask import Flask, request, jsonify
import requests
import os

app = Flask(__name__)
spade_api_key = os.environ["SPADE_API_KEY"]

@app.get("/corporations")
def search_corporations():
    name = request.args.get("name", "")
    response = requests.get(
        "https://east.sandbox.spade.com/corporations",
        params={"name": name},
        headers={"X-Api-Key": spade_api_key},
    )
    return jsonify(response.json()), response.status_code

​
Frontend debounce

Because the endpoint is rate-limited, debounce requests from the frontend so that a request is only sent after the user pauses typing (300-400 ms is a good starting point). Most autocomplete libraries handle this automatically — if yours does not, use a utility like lodash.debounce.

​
Next steps