> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spade.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Merchant search guide

> Search Spade's merchant database to power autocomplete experiences

<Info>
  Merchant search is in beta and is not enabled by default. To request access, contact us at [sales@spade.com](mailto:sales@spade.com).
</Info>

## 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](/reference/merchant-action-triggers-guide) 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.

<CodeGroup>
  ```python Python theme={null}
  import requests

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

  print(response.json())
  ```

  ```bash cURL theme={null}
  curl -G "https://east.sandbox.spade.com/corporations" \
    --data-urlencode "name=star" \
    -H "X-Api-Key: <Your API Key>"
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "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

| Field     | Type           | Description                                          |
| --------- | -------------- | ---------------------------------------------------- |
| `name`    | string         | The merchant's name                                  |
| `logo`    | string \| null | URL of the merchant's logo, or `null` if unavailable |
| `website` | string \| null | The 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.

<Warning>
  Never send your API key to the client. This includes any client-side application code bundles (websites, mobile apps, etc.).
</Warning>

```python theme={null}
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

* [Merchant-based rewards](/reference/merchant-based-rewards) — build a rewards program on top of merchant search
* [Merchant-locked cards](/reference/merchant-locked-cards) — restrict card spending to specific merchants
* [Merchant action triggers](/reference/merchant-action-triggers-guide) — register rules that trigger custom actions during enrichment