Search the national FFL listing

POST

/v1/ffl/search

curl --request POST \
  --url https://api.oldsteelarsenal.com/v1/ffl/search \
  --header 'Content-Type: application/json' \
  --header 'x-client-id: <x-client-id>' \
  --header 'x-signature: <x-signature>' \
  --header 'x-timestamp: <x-timestamp>' \
  --data '{ "license_number": "example", "limit": 50, "name": "example", "radius_miles": 50, "types": [ "example" ], "zip": "example" }'

Two modes, by presence of zip:

• Geo (zip given): dealers within radius_miles of the ZIP centroid, nearest first, distance_miles populated.
• Text (zip omitted): match by name (ILIKE + trigram) and/or license_number, sorted by name, distance_miles = 0. At least one of zip / name / license_number is required.

license_number matches on the licence’s stable identity — segment 5 (the expiration code) is wildcarded, so stale or placeholder codes still resolve. Reads the monthly listing only: no live ATF call, no rate-limit spend, no real expiry dates (use verify for those). Scope: ffl:read.

Authorizations

• ClientId
• Signature
• Timestamp

Parameters

Header Parameters

x-client-id

Any of:

string

string

null

null

x-timestamp

Any of:

string

string

null

null

x-signature

Any of:

string

string

null

null

Request Body^required

Media typeapplication/json

SearchRequest

object

license_number

Any of:

string

string

null

null

limit

Limit

integer

default: 50 >= 1 <= 200

name

Any of:

string

string

null

null

radius_miles

Radius Miles

Geo radius in miles; ignored without a zip.

number

default: 50 > 0 <= 3000

types

Any of:

Array<string>

Array<string>

null

null

zip

Any of:

string

string

>= 5 characters <= 5 characters

null

null

Responses

200

Successful Response

Media typeapplication/json

SearchResponse

object

results

required

Results

Array<object>

FflResult

object

distance_miles

required

Distance Miles

Miles from the search ZIP centroid; 0.0 in text-only searches.

number

expiration_date

required

Any of:

string

string

null

null

license_name

required

Any of:

string

string

null

null

license_number

required

License Number

Canonical 6-segment licence number with the real expiration code in segment 5.

string

premise_city

required

Any of:

string

string

null

null

premise_state

required

Any of:

string

string

null

null

premise_street

required

Any of:

string

string

null

null

premise_zip

required

Any of:

string

string

null

null

trade_name

required

Any of:

string

string

null

null

type_code

required

Any of:

string

string

null

null

voice_phone

required

Any of:

string

string

null

null

stale

Stale

Mirrors /v1/sync/status staleness at response time.

boolean

Example

{
  "stale": false
}

401

Missing/invalid HMAC auth

403

Missing ffl:read

404

Zip not found in centroid table

422

No zip, name, or license_number given