# New Retailer Leads — API Reference

A simple REST API over the New Retailer Leads dataset: 556,000+ verified, newly licensed US businesses across nine regulated verticals. JSON or CSV, filterable by territory and category, with real-time webhooks for new openings.

Base URL: `https://api.newretailerleads.com`

## Authentication
Every request requires your API key in the `X-API-Key` header. Keys are per-customer and scoped to your plan's territories and categories. There is no anonymous access and no public bulk endpoint — the dataset cannot be scraped or re-exported.

```
curl https://api.newretailerleads.com/v1/tobacco/entities \
  -H "X-API-Key: YOUR_API_KEY"
```

## Verticals
The `{vertical}` path segment selects a category. All nine are queried identically; your plan controls which you can access.

| Vertical key | Covers |
|---|---|
| `tobacco` | Tobacco & vape / e-cigarette retailers (largest category) |
| `liquor` | Liquor / package stores & on-premise licensees |
| `alcohol_trade` | Breweries, wineries, distilleries, importers & wholesalers (federal TTB permits) |
| `cannabis` | Dispensaries, cultivators, manufacturers & distributors |
| `hemp` | Hemp / CBD producers & retailers (state programs + USDA) |
| `ketamine` | Ketamine clinics & ketamine-assisted-therapy providers |
| `methadone` | Methadone & opioid-treatment programs (OTP) |
| `kratom` | Kratom vendors & GMP-qualified brands |
| `psilocybin` | Licensed psilocybin service centers & facilitators (OR + CO) |

## List businesses
`GET /v1/{vertical}/entities` — returns active businesses, newest first.

Query params:

| Param | Description |
|---|---|
| `state` | Two-letter state code, e.g. `TX` |
| `type` | Category contains, e.g. `vape` |
| `q` | Business or DBA name contains |
| `since` | Only records first seen on/after this date (`YYYY-MM-DD`) |
| `risk` | `true` = only businesses flagged with an enforcement action |
| `format` | `json` (default) or `csv` |
| `limit` / `offset` | Pagination (limit ≤ 1000) |

```
curl "https://api.newretailerleads.com/v1/cannabis/entities?state=CA&since=2026-06-01&limit=50" \
  -H "X-API-Key: YOUR_API_KEY"
```

Response fields: `natural_key`, `first_seen_at`, `licensee`, `dba`, `license_type`, `status`, `address`, `city`, `state`, `zip`, `county`, `owner`, `phone`, `lat`, `lng`, `maps_url`. Add `format=csv` for a flat file.

## New-opening events
`GET /v1/{vertical}/events` — a stream of change events: `retailer_licensed` (new), `retailer_closed`, `status_changed`. Poll with `since`, or subscribe to a webhook to receive them in real time.

```
curl "https://api.newretailerleads.com/v1/liquor/events?type=retailer_licensed&since=2026-06-29T00:00:00Z" \
  -H "X-API-Key: YOUR_API_KEY"
```

## Webhooks
New openings are pushed to your endpoint the moment they are added, with an HMAC signature for verification. Configure target URLs with our team. Payload contains the event type, timestamp, and the verified record (never any sourcing detail).

## CSV export
Add `format=csv` to the list endpoint, or get a recurring scheduled CSV drop. Grab a free 100-row sample to see the shape.

## Errors & limits
Standard HTTP status codes. `401` = missing/invalid key. `403` = key not scoped to that vertical or territory. `429` = plan quota exceeded (retry after the window resets). Response bodies are JSON with an `error` message.

---

Contact: sales@newretailerleads.com · Pricing starts at $149/mo (Starter), $399/mo (Pro).