GET /dealers/search · FFL Monkey Docs

Query parameters

Needs FFL dealers: Read, a permission of FFL Checkout stores. Say where with a zip or a point (latitude and longitude), never both, or which with a name or a license_number. At least one of them is required.

Parameter	Type	Meaning
zip	string	A 5-digit ZIP, or ZIP+4, to search around. Refused with a point.
latitude	number	With `longitude`: a point to search around, more precise than a ZIP. -90 to 90.
longitude	number	With `latitude`. -180 to 180.
name	string	The start of the dealer's business name or licence name, or of any word in it, in any case. 3 to 120 characters.
license_number	string	A licence number in any form: printed, with or without separators. Finds that dealer or nothing. Up to 32 characters.
radius_m	integer	How far to search from a ZIP or a point, in metres: 1 to 321869 (200 miles). Default 80467 (50 miles).
limit	integer	How many dealers at most: 1 to 100. Default 25.
only_on_file	boolean	`1` or `true`: only dealers your store already holds paperwork for. `0` or `false` does not filter. `true` and `false` are read in any letter case; anything else is refused.
sot_only	boolean	`1` or `true`: only dealers with an SOT in force, who can receive NFA items: the class from the dealer's approved SOT stamp, until its tax year ends on 30 June. `0` or `false` does not filter. `true` and `false` are read in any letter case; anything else is refused.
verified_only	boolean	`1` or `true`: only dealers the registry has seen accept a transfer, from a store's FFL transfer report. `0` or `false` does not filter. `true` and `false` are read in any letter case; anything else is refused.

The search FFL Monkey's dealer picker runs, with its rules. Only dealers whose licence is current (active, and expiring today or later, UTC) and of a type a firearm may be transferred to are found, and only those the registry could place on a map.
By a ZIP or a point, nearest first, within radius_m. A ZIP the registry cannot place answers no dealers with meta.zip_known false: "we do not know that ZIP", not "nobody near it".
By name or licence number, measured from the ZIP or point when you send one too, nearest first, otherwise by name. radius_m and only_on_file are for a ZIP or a point only.
sot_only and verified_only filter before limit, on every kind of search, so the dealers they leave are still the nearest ones.
Caps are refused, never cut down: a radius_m over 321869 or a limit over 100 is 422.
Searches share your checkout's limits: 120 a minute from one address, across every key and dealer picker searching from it, and 5,000 a day for the store. A search by license_number with limit=1 is outside the daily limit.

What it answers

data is a list of dealers, meta says what was searched, and map names the map FFL Monkey's dealer picker draws, its style and the tiles it falls back to, so a map you draw on the results can use the same ones. Each dealer:

Field	Meaning
license_number	The licence number as the registry holds it, usually as printed on the licence.
license_key	The licence without its expiry group, such as `1-62-037-01-01187`: the same when the licence is renewed, so the value to keep, and to look the dealer up by again with GET /dealers/{licenseNumber}. Null only for a number that cannot be read.
business_name	The dealer's business name.
licensee_name	The name on the licence, often a person's. Sent for a search by name or licence number; null for a search by ZIP or by a point.
address	The licensed premises, below.
phone	The dealer's phone number, or null.
latitude	Where to put the dealer on a map, in WGS84 degrees.
longitude	The same, east to west.
distance_meters	From the ZIP or point searched from, in metres; null when the search had no origin.
expiration_date	When the licence expires, the last day of its month, or null.
sot_class	The Special Occupational Tax class, for NFA items, when the dealer pays it, such as `3`; otherwise null.
on_file	Whether your store already holds this dealer's paperwork, from a completed FFL order or an upload FFL Monkey approved. Your store's own: another store gets its own answer.
document	The registry holds a current copy of the dealer's licence, below, or null.
sot_document	The same for its SOT stamp, or null.

`address`	Meaning
line_1	The street address, as ATF's list or the approved licence gives it.
line_2	A second line, or null.
city	The city.
state	The two-letter state code.
zip	The ZIP.

`document`, `sot_document`	Meaning
available	Always `true` when the object is there. Availability only, never a link to the document.
kind	`ffl` or `sot`.
expires_on	When the copy held stops covering the dealer: the licence's expiry, or the end of the SOT tax year.

`meta`	Meaning
zip	The 5-digit ZIP searched from; null for a search by a point, or by name or licence number without a ZIP.
zip_known	`false` only when the ZIP could not be placed, so an empty answer means "unknown ZIP" rather than "nobody within the radius".
count	How many dealers `data` holds.

`map`	Meaning
tile_url	A tile URL template with `{z}`, `{x}` and `{y}`.
attribution	The tile provider's credit, as HTML, to show on the map as its terms ask.
max_zoom	The deepest zoom the tiles go to.
style_url	A MapLibre style the picker draws in place of the tiles, or `null` when it draws the tiles. The tiles stay its fallback.
style_attribution	The style's credit, as HTML, to show on the map while the style draws. `null` when `style_url` is.

A page with a Content Security Policy must allow the tile host in img-src, and, to draw the style, its host in connect-src and what MapLibre itself needs (blob: workers and images).

Returns

200The dealers found in data, nearest first when there is an origin, with meta and map. No dealer is still a 200.
422validation_failed: no ZIP, point, name or licence number; a ZIP and a point together; or a parameter that broke a rule.

This endpoint can also answer 401 invalid_api_key, 403 license_not_active, 403 product_not_included, 403 insufficient_scope and 429 rate_limited.

GET`/dealers/search`

Query parameters

What it answers

Returns

Example