Home / API Reference

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.

llms.txt

Authentication

Every request requires your API key in the X-API-Key header. Keys are issued per customer and scoped to the territories and categories on your plan. Keep your key secret; treat it like a password.

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

Requests are rate-limited by your plan's monthly quota. There is no anonymous access and no public bulk endpoint - the dataset cannot be scraped or re-exported. Need a key? Start with a free preview or email sales@newretailerleads.com.

Verticals

The {vertical} path segment selects a category. All nine are queried the same way; your plan controls which you can access.

tobaccoliquoralcohol_tradecannabishempketaminemethadonekratompsilocybin

Vertical key	What it covers
`tobacco`	Tobacco & vape / e-cigarette retailers (largest category)
`liquor`	Liquor / package stores and on-premise licensees
`alcohol_trade`	Breweries, wineries, distilleries, importers & wholesalers (federal TTB permits)
`cannabis`	Licensed 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 kratom brands
`psilocybin`	Licensed psilocybin service centers & facilitators (OR + CO)

List businesses

GET/v1/{vertical}/entities

vertical is any of the nine keys above (e.g. tobacco, cannabis, ketamine). Returns active businesses, newest first.

Query parameters

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)

Example

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

Get new openings 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

Prefer flat files? Add format=csv to the list endpoint, or get a recurring CSV drop on a schedule. 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.