API Docs | New Retailer Leads

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 [email protected].

List retailers

GET/v1/{vertical}/entities

vertical is tobacco or liquor. Returns active retailers, 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 shops flagged with an enforcement action
`format`	`json` (default) or `csv`
`limit` / `offset`	Pagination (limit ≤ 1000)

Example

curl "https://api.newretailerleads.com/v1/tobacco/entities?state=TX&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.