Live ATF EZ Check verification

POST

/v1/ffl/{license_number}/verify

curl --request POST \
  --url https://api.oldsteelarsenal.com/v1/ffl/example/verify \
  --header 'Content-Type: application/json' \
  --header 'x-client-id: <x-client-id>' \
  --header 'x-signature: <x-signature>' \
  --header 'x-timestamp: <x-timestamp>' \
  --data '{ "force": false }'

Cache-first verification against ATF’s public EZ Check form, shared by every client of this service.

• Cache: answers fresher than the TTL (default 24h) are served with cached: true and cost nothing. Cache lookup uses the stable licence identity. NotFound answers are cached too.
• Budget: only real calls to ATF spend budget, and it is charged in two tiers — your tenant’s hourly allowance (default 30/h) and a service-wide ceiling shared by all tenants (default 120/h). Either one exhausted → 429, with the detail naming which tier (tenant … vs service …); retry next hour or accept the cached answer.
• force: true: skip the cache read (still refreshes it) — the only way a cached licence spends budget.
• Returns the real expiry date and a structured premise address (street/street2/city/state/zip) parsed server-side.
• ATF unreachable or unparsable → 502; fall back to your own cached copy.

Scope: ffl:verify.

Authorizations

• ClientId
• Signature
• Timestamp

Parameters

Path Parameters

license_number

required

License Number

string

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

Media typeapplication/json

Any of:

VerifyRequest

VerifyRequest

object

force

Force

boolean

null

null

Responses

200

Successful Response

Media typeapplication/json

VerifyResponse

object

address

required

Any of:

string

string

null

null

cached

required

Cached

True when served from the shared cache (no ATF call, no budget spent).

boolean

city

required

Any of:

string

string

null

null

expiry_date

required

Any of:

string

string format: date

null

null

fetched_at

required

Fetched At

When this answer was fetched from ATF (UTC).

string format: date-time

ffl_number

required

Ffl Number

Licence number as submitted.

string

found

required

Found

boolean

license_type

required

Any of:

string

string

null

null

licensee_dba

required

Any of:

string

string

null

null

licensee_name

required

Any of:

string

string

null

null

state

required

Any of:

string

string

null

null

status

required

Status

‘Verified’ | ‘Expired’ | ‘NotFound’.

string

street

required

Any of:

string

string

null

null

street2

required

Any of:

string

string

null

null

zip

required

Any of:

string

string

null

null

Example^generated

{
  "address": "example",
  "cached": true,
  "city": "example",
  "expiry_date": "2026-04-15",
  "fetched_at": "2026-04-15T12:00:00Z",
  "ffl_number": "example",
  "found": true,
  "license_type": "example",
  "licensee_dba": "example",
  "licensee_name": "example",
  "state": "example",
  "status": "example",
  "street": "example",
  "street2": "example",
  "zip": "example"
}

401

Missing/invalid HMAC auth

403

Missing ffl:verify

422

Validation Error

Media typeapplication/json

HTTPValidationError

object

detail

Detail

Array<object>

ValidationError

object

ctx

Context

object

input

Input

loc

required

Location

Array

msg

required

Message

string

type

required

Error Type

string

Example^generated

{
  "detail": [
    {
      "ctx": {},
      "input": "example",
      "loc": [
        "example"
      ],
      "msg": "example",
      "type": "example"
    }
  ]
}

429

Tenant or service hourly ATF budget exhausted

502

ATF unreachable or response unparsable