COMPLIANCE API

Integrate firearm compliance verification into your dealer software. Cover all 50 US states + DC, federal NFA classification, named-banned lists, feature tests, and statute citations — through a single REST endpoint.

Quick start

1. Get an API key

API keys are issued manually during the early-access period. Email api@fflwatch.com with your company name, expected volume, and intended use case. We'll provision a key within one business day.

Keys look like gcc_live_a3f2b7c8… for production and gcc_test_… for testing.

2. Make your first call

curl -X POST https://fflwatch.com/api/compliance \
  -H "Authorization: Bearer gcc_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "upc",
    "value": "787450868106",
    "stateCode": "NJ"
  }'

3. Read the response

{
  "found": true,
  "make": "Sig Sauer",
  "model": "P320 Compact",
  "caliber": "9mm",
  "action": "semi-automatic",
  "magazine_capacity": 15,
  "verdict": "COMPLIANT WITH MODIFICATIONS",
  "federal_classification": "Pistol",
  "summary": "...",
  "issues": ["Magazine capacity exceeds NJ 10-round limit"],
  "modifications": ["Replace 15-round magazine with 10-round-or-less magazine before transfer"],
  "permits_required": [
    "Firearms Purchaser Identification Card (FPIC)",
    "Permit to Purchase a Handgun (PPH)"
  ],
  "statutes": "N.J.S.A. 2C:39-1y, 2C:58-3",
  "_meta": {
    "plan": "starter",
    "calls_used_this_period": 1,
    "calls_remaining_this_period": 4999,
    "monthly_limit": 5000
  }
}

Authentication

Every request must include the API key in one of two headers:

Authorization: Bearer gcc_live_YOUR_KEY_HERE

or

X-API-Key: gcc_live_YOUR_KEY_HERE

Endpoints

POST /api/compliance

The single endpoint covers three modes via the mode field.

Mode: "upc" — Look up by UPC barcode + run compliance

{
  "mode": "upc",
  "value": "787450868106",      // UPC-A or EAN-13, digits only
  "stateCode": "NJ"             // optional — if present, runs full compliance after lookup
}

Mode: "mpn" — Look up by manufacturer part number / model name

{
  "mode": "mpn",
  "value": "Smith & Wesson M&P 9 Shield",
  "stateCode": "CA"
}

Mode: "compliance" — Compliance check from explicit firearm specs

{
  "mode": "compliance",
  "stateCode": "NJ",
  "state": "New Jersey",
  "firearmDescription": "Ruger AR-556 5.56mm semi-auto rifle, 16-inch barrel, telescoping stock, pistol grip, 30-round magazine, no flash suppressor"
}

Response fields

• verdict — "COMPLIANT", "NON-COMPLIANT", or "COMPLIANT WITH MODIFICATIONS"
• federal_classification — "Rifle", "Pistol", "Shotgun", or "Other"
• firearm_identified — Make, model, caliber as identified
• summary — 2-3 sentence plain-English verdict
• issues — Array of compliance violations, if any
• modifications — Array of physical changes that would make the firearm compliant
• permits_required — Array of permits the buyer must hold (always spelled out fully)
• statutes — Specific state and federal statute citations
• notes — Dealer-facing notes (waiting periods, age requirements, etc.)
• _meta — Your account's API usage info on this call

Pricing

Pricing for Starter, Pro, and Enterprise tiers is set per-customer based on volume and use case. Email api@fflwatch.com for a quote.

Errors

Best practices

• Cache aggressively. The same UPC + state combination will return the same verdict for hours or days. Cache results in your own system to reduce calls and improve latency.
• Display the citations. Your users (the FFL) need to see the statute references — that's how dealers verify the verdict is real and how they defend their decision in an audit.
• Show the reasoning chain. When the verdict is NON-COMPLIANT or COMPLIANT WITH MODIFICATIONS, surface the issues and modifications arrays — dealers need to know why and what to do about it.
• Never auto-block transfers based solely on this API. The verdict is informational. Your software should surface it to the dealer; the dealer makes the final call.
• Handle 429 gracefully. Show the dealer "compliance check temporarily unavailable" rather than silently failing.
• Use server-side calls. Browser/mobile-app calls expose the API key.

Disclaimer

FFL WATCH · COMPLIANCE API · v1.0