Skip to content
Vetting and restrictions

Vetting and restrictions API

A vetting check asks whether a dealer, a destination or a vendor is who the record says it is. The response reports what each source matched and why the check reached its status. A check is evidence, not a legal decision.

Start a check

POST /v1/vetting/checks accepts three types: ffl_dealer, ship_to and vendor. An ffl_dealer check takes a license number and optional business name and premise address. A ship_to check takes a license number and a ship-to address, then compares the address with the licensed premise. A vendor check takes a business name and registration state.

bash
curl -X POST https://api.rollstamp.example/v1/vetting/checks \
  -H "x-api-key: $ROLLSTAMP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "ffl_dealer",
    "license_number": "4-37-201-01-8K-70207",
    "business_name": "Hollow Pawn & Gun",
    "premise_address": {
      "line1": "4409 Highway 41",
      "city": "Nashville",
      "state": "TN",
      "postal_code": "37201"
    },
    "reference": "dealer-8812"
  }'

The result

A new check returns processing. The result arrives a few seconds later: poll the check or subscribe to vetting.check.completed. A result carries the status, the license or business fields the lookup found, the flags and which fields each source matched.

The license listing and business registry in this build are sample data. Live ATF and business-registry lookups are planned. A check result is still evidence, not a legal decision.
json
{
  "id": "chk_7Qp2M4vX",
  "type": "ffl_dealer",
  "status": "verified",
  "reference": "dealer-8812",
  "recheck": false,
  "created_at": "2026-11-17T15:04:06.000Z",
  "confidence": 0.97,
  "license": {
    "number": "4-37-201-01-8K-70207",
    "type": "01",
    "type_name": "Dealer in firearms",
    "expires": "2028-10-31",
    "name_on_license": "HOLLOW PAWN & GUN LLC",
    "premise_county": "Davidson",
    "premise_match": "exact"
  },
  "name_match": "exact",
  "flags": [],
  "evidence": [
    { "source": "license_listing", "matched": ["number", "name", "premise_address"] },
    { "source": "business_registry", "matched": ["name", "state"] }
  ],
  "completed_at": "2026-11-17T15:04:11.000Z"
}

Re-checks

For an FFL or ship-to check, set recheck: true and the license is looked up again daily. A vetting.license.expiring event is sent 60 days before the license expires. A daily recheck updates the license expiry on the same check and adds rechecked_at; it does not create a duplicate check.

Restrictions

POST /v1/restrictions/check tests a destination against your rules for 1 to 100 items. For a US destination, shipping.state is required. Send shipping.county or shipping.ffl_license when the rule depends on one. The response lists matched rules under blocking, warning or manual review, each with its rule id, name, action and customer message. It does not return the rule's scope or a legal conclusion.

Fraud signals

Report a confirmed fraudulent order with POST /v1/fraud/reports. Send the identity fields and optional order items; the endpoint stores keyed hashes of those signals, not the raw values. A note, an order source and an order id are stored in plain text, not as hashes. A shipping address does not count as a signal when the order ships to an FFL. POST /v1/fraud/check returns the number of dealers who reported, signal counts, the signals that matched and the first and last report dates. A match is not an automatic decline.