{
"openapi": "3.0.1",
"info": {
"title": "US Firearms License (FFL) & Gun Dealer Leads Scraper",
"description": "Download the official ATF Federal Firearms Licensee (FFL) list: 77,000+ licensed gun dealers, manufacturers, importers and pawnbrokers with address, county, phone, license type and expiry. Track new licenses, verify FFL numbers in bulk. Independent tool, not affiliated with any government agency.",
"version": "0.1",
"x-build-id": "CVY4FNq91IcRLWezc"
},
"servers": [
{
"url": "https://api.apify.com/v2"
}
],
"paths": {
"/acts/scrapesage~us-firearms-license-scraper/run-sync-get-dataset-items": {
"post": {
"operationId": "run-sync-get-dataset-items-scrapesage-us-firearms-license-scraper",
"x-openai-isConsequential": false,
"summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
"tags": [
"Run Actor"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inputSchema"
}
}
}
},
"parameters": [
{
"name": "token",
"in": "query",
"required": true,
"schema": {
"type": "string"
},
"description": "Enter your Apify token here"
}
],
"responses": {
"200": {
"description": "OK"
}
}
}
},
"/acts/scrapesage~us-firearms-license-scraper/runs": {
"post": {
"operationId": "runs-sync-scrapesage-us-firearms-license-scraper",
"x-openai-isConsequential": false,
"summary": "Executes an Actor and returns information about the initiated run in response.",
"tags": [
"Run Actor"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inputSchema"
}
}
}
},
"parameters": [
{
"name": "token",
"in": "query",
"required": true,
"schema": {
"type": "string"
},
"description": "Enter your Apify token here"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/runsResponseSchema"
}
}
}
}
}
}
},
"/acts/scrapesage~us-firearms-license-scraper/run-sync": {
"post": {
"operationId": "run-sync-scrapesage-us-firearms-license-scraper",
"x-openai-isConsequential": false,
"summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
"tags": [
"Run Actor"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inputSchema"
}
}
}
},
"parameters": [
{
"name": "token",
"in": "query",
"required": true,
"schema": {
"type": "string"
},
"description": "Enter your Apify token here"
}
],
"responses": {
"200": {
"description": "OK"
}
}
}
}
},
"components": {
"schemas": {
"inputSchema": {
"type": "object",
"properties": {
"states": {
"title": "States",
"type": "array",
"description": "Premise (business) state of the licensee. Pick one or more; leave empty for the whole country. Puerto Rico, Guam, the US Virgin Islands and the Northern Mariana Islands are included.",
"items": {
"type": "string",
"enum": [
"AL",
"AK",
"AS",
"AZ",
"AR",
"CA",
"CO",
"CT",
"DE",
"DC",
"FL",
"GA",
"GU",
"HI",
"ID",
"IL",
"IN",
"IA",
"KS",
"KY",
"LA",
"ME",
"MD",
"MA",
"MI",
"MN",
"MS",
"MO",
"MT",
"NE",
"NV",
"NH",
"NJ",
"NM",
"NY",
"NC",
"ND",
"MP",
"OH",
"OK",
"OR",
"PA",
"PR",
"RI",
"SC",
"SD",
"TN",
"TX",
"VI",
"UT",
"VT",
"VA",
"WA",
"WV",
"WI",
"WY"
],
"enumTitles": [
"Alabama (AL)",
"Alaska (AK)",
"American Samoa (AS)",
"Arizona (AZ)",
"Arkansas (AR)",
"California (CA)",
"Colorado (CO)",
"Connecticut (CT)",
"Delaware (DE)",
"District of Columbia (DC)",
"Florida (FL)",
"Georgia (GA)",
"Guam (GU)",
"Hawaii (HI)",
"Idaho (ID)",
"Illinois (IL)",
"Indiana (IN)",
"Iowa (IA)",
"Kansas (KS)",
"Kentucky (KY)",
"Louisiana (LA)",
"Maine (ME)",
"Maryland (MD)",
"Massachusetts (MA)",
"Michigan (MI)",
"Minnesota (MN)",
"Mississippi (MS)",
"Missouri (MO)",
"Montana (MT)",
"Nebraska (NE)",
"Nevada (NV)",
"New Hampshire (NH)",
"New Jersey (NJ)",
"New Mexico (NM)",
"New York (NY)",
"North Carolina (NC)",
"North Dakota (ND)",
"Northern Mariana Islands (MP)",
"Ohio (OH)",
"Oklahoma (OK)",
"Oregon (OR)",
"Pennsylvania (PA)",
"Puerto Rico (PR)",
"Rhode Island (RI)",
"South Carolina (SC)",
"South Dakota (SD)",
"Tennessee (TN)",
"Texas (TX)",
"U.S. Virgin Islands (VI)",
"Utah (UT)",
"Vermont (VT)",
"Virginia (VA)",
"Washington (WA)",
"West Virginia (WV)",
"Wisconsin (WI)",
"Wyoming (WY)"
]
}
},
"cities": {
"title": "Cities",
"type": "array",
"description": "Premise city, matched as a whole name (case and punctuation ignored, St./Saint and Ft./Fort treated alike), e.g. Houston or Springfield, MO to pin the state.",
"items": {
"type": "string"
}
},
"counties": {
"title": "Counties",
"type": "array",
"description": "Premise county, e.g. Harris, Harris County, TX, Miami-Dade or a 5-digit FIPS code such as 48201. Every licensee carries its county name and FIPS code, taken from the county code ATF puts in the FFL number.",
"items": {
"type": "string"
}
},
"zipCodes": {
"title": "ZIP codes (prefix)",
"type": "array",
"description": "Premise ZIP: a full ZIP (77002) or a prefix (770 matches every 770xx ZIP).",
"items": {
"type": "string"
}
},
"licenseTypes": {
"title": "License types",
"type": "array",
"description": "ATF license types to return. Leave empty for all. Type 01 (dealers and gunsmiths) is by far the most common. ATF does not publish Type 03 (Curio & Relic collector) licenses in its lists, so that type is not offered.",
"items": {
"type": "string",
"enum": [
"01",
"02",
"06",
"07",
"08",
"09",
"10",
"11"
],
"enumTitles": [
"01 - Dealer / Gunsmith",
"02 - Pawnbroker",
"06 - Manufacturer of Ammunition",
"07 - Manufacturer of Firearms",
"08 - Importer of Firearms",
"09 - Dealer in Destructive Devices",
"10 - Manufacturer of Destructive Devices",
"11 - Importer of Destructive Devices"
]
}
},
"licenseCategories": {
"title": "License categories",
"type": "array",
"description": "Groups of license types: Dealer = 01 and 09, Pawnbroker = 02, Manufacturer = 06, 07 and 10, Importer = 08 and 11. Use with or instead of license types.",
"items": {
"type": "string",
"enum": [
"Dealer",
"Pawnbroker",
"Manufacturer",
"Importer"
],
"enumTitles": [
"Dealer (01, 09)",
"Pawnbroker (02)",
"Manufacturer (06, 07, 10)",
"Importer (08, 11)"
]
}
},
"businessOnly": {
"title": "Business name present only",
"type": "boolean",
"description": "Only licensees with a business / trade name (DBA) on file, a strong sign of an established storefront rather than a home-based individual license.",
"default": false
},
"withPhoneOnly": {
"title": "With phone number only",
"type": "boolean",
"description": "Only licensees with a valid 10-digit voice phone number on file.",
"default": false
},
"businessNameContains": {
"title": "Business name contains",
"type": "string",
"description": "Only licensees whose business / trade name contains this text (case-insensitive), e.g. pawn, tactical, armory, sporting."
},
"licenseeNameContains": {
"title": "Licensee name contains",
"type": "string",
"description": "Only licensees whose legal license name contains this text (case-insensitive). Individuals are listed by ATF as LAST, FIRST, e.g. smith, john."
},
"nameContains": {
"title": "Any name contains",
"type": "string",
"description": "Matches either the legal license name or the business / trade name (case-insensitive). Use it for a broad keyword sweep."
},
"expiringWithinMonths": {
"title": "License expiring within (months)",
"minimum": 0,
"maximum": 48,
"type": "integer",
"description": "Only licenses whose expiry date falls within this many months after the list's month, e.g. 3 for licensees due to renew soon. Licenses already past their expiry date but still on ATF's list (renewal pending) are included."
},
"regionCodes": {
"title": "ATF region codes (advanced)",
"type": "array",
"description": "Advanced: the first digit of the FFL number (ATF licensing region). Most users should filter by state instead.",
"items": {
"type": "string"
}
},
"countyCodes": {
"title": "ATF county codes (advanced)",
"type": "array",
"description": "Advanced: the 3-digit county segment of the FFL number (the county's FIPS code within its state). Most users should use Counties instead.",
"items": {
"type": "string"
}
},
"fflNumbers": {
"title": "FFL numbers to verify",
"type": "array",
"description": "Check specific licenses against the current ATF list: a full number such as 5-74-491-07-9C-04321 (dashes optional) or the first 3 + last 5 digits that ATF's FFL eZ Check uses, such as 5-74-04321. You get one row per number in the same order: listed rows carry the full current record (and say if the license was renewed under a newer number) and are billed; not listed and invalid number rows are free. Other filters are not applied while verifying.",
"items": {
"type": "string"
}
},
"compareWithPreviousMonth": {
"title": "Compare with the previous month",
"type": "boolean",
"description": "Also read ATF's previous monthly list and mark every licensee new, renewed, updated (address, phone or name changed, listed in changedFields) or unchanged. Adds a few seconds per run.",
"default": true
},
"changeTypes": {
"title": "Only these changes",
"type": "array",
"description": "Keep only licensees with these changes since the previous month. New = licenses that were not on last month's list (fresh leads), Renewed = expiry date moved, Updated = address, phone or name changed, Removed = on last month's list but gone from this one (expired, surrendered or revoked; their details are last month's). Leave empty for the whole list.",
"items": {
"type": "string",
"enum": [
"new",
"renewed",
"updated",
"unchanged",
"removed"
],
"enumTitles": [
"New licenses",
"Renewed",
"Updated (address, phone or name)",
"Unchanged",
"Removed from the list"
]
}
},
"listingMonth": {
"title": "List month (optional)",
"pattern": "^(\\d{4}-\\d{2})?$",
"type": "string",
"description": "Read an older monthly list instead of the newest, as YYYY-MM (ATF's online archive starts January 2021 and skips a few months). Leave empty for the newest list."
},
"maxResults": {
"title": "Max results",
"minimum": 1,
"type": "integer",
"description": "Maximum number of licensees to return (and pay for) in this run. ATF's list holds about 77,000 licensees in total; raise this for a whole state or the full list.",
"default": 100
},
"sortBy": {
"title": "Sort order",
"enum": [
"leadScore",
"businessName",
"state",
"source"
],
"type": "string",
"description": "Lead score = highest-value B2B licensees first (manufacturers and importers with a phone and a registered business). Business name and State = alphabetical. Source order = ATF's own file order.",
"default": "leadScore"
},
"monitorMode": {
"title": "Monitoring mode: only new licensees",
"type": "boolean",
"description": "For scheduled runs. The first run returns the current list (up to Max results) and remembers every licensee that matches your filters; each later run returns only licensees that joined ATF's list since, tagged monitorEvent: \"new\". Renewals and licensees you simply had not seen before are never reported as new. ATF publishes about once a month, so a monthly or weekly Schedule is enough.",
"default": false
},
"monitorKey": {
"title": "Monitor key",
"type": "string",
"description": "Names the memory used by monitoring mode. Use a different key for each separate watch (for example one per state).",
"default": "default"
},
"proxyConfiguration": {
"title": "Proxy configuration",
"type": "object",
"description": "Not needed: the actor downloads ATF's file directly and only falls back to Apify proxy on its own when atf.gov refuses a request. Set a proxy here only if you must route the download through one.",
"default": {
"useApifyProxy": false
}
}
}
},
"runsResponseSchema": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"actId": {
"type": "string"
},
"userId": {
"type": "string"
},
"startedAt": {
"type": "string",
"format": "date-time",
"example": "2025-01-08T00:00:00.000Z"
},
"finishedAt": {
"type": "string",
"format": "date-time",
"example": "2025-01-08T00:00:00.000Z"
},
"status": {
"type": "string",
"example": "READY"
},
"meta": {
"type": "object",
"properties": {
"origin": {
"type": "string",
"example": "API"
},
"userAgent": {
"type": "string"
}
}
},
"stats": {
"type": "object",
"properties": {
"inputBodyLen": {
"type": "integer",
"example": 2000
},
"rebootCount": {
"type": "integer",
"example": 0
},
"restartCount": {
"type": "integer",
"example": 0
},
"resurrectCount": {
"type": "integer",
"example": 0
},
"computeUnits": {
"type": "integer",
"example": 0
}
}
},
"options": {
"type": "object",
"properties": {
"build": {
"type": "string",
"example": "latest"
},
"timeoutSecs": {
"type": "integer",
"example": 300
},
"memoryMbytes": {
"type": "integer",
"example": 1024
},
"diskMbytes": {
"type": "integer",
"example": 2048
}
}
},
"buildId": {
"type": "string"
},
"defaultKeyValueStoreId": {
"type": "string"
},
"defaultDatasetId": {
"type": "string"
},
"defaultRequestQueueId": {
"type": "string"
},
"buildNumber": {
"type": "string",
"example": "1.0.0"
},
"containerUrl": {
"type": "string"
},
"usage": {
"type": "object",
"properties": {
"ACTOR_COMPUTE_UNITS": {
"type": "integer",
"example": 0
},
"DATASET_READS": {
"type": "integer",
"example": 0
},
"DATASET_WRITES": {
"type": "integer",
"example": 0
},
"KEY_VALUE_STORE_READS": {
"type": "integer",
"example": 0
},
"KEY_VALUE_STORE_WRITES": {
"type": "integer",
"example": 1
},
"KEY_VALUE_STORE_LISTS": {
"type": "integer",
"example": 0
},
"REQUEST_QUEUE_READS": {
"type": "integer",
"example": 0
},
"REQUEST_QUEUE_WRITES": {
"type": "integer",
"example": 0
},
"DATA_TRANSFER_INTERNAL_GBYTES": {
"type": "integer",
"example": 0
},
"DATA_TRANSFER_EXTERNAL_GBYTES": {
"type": "integer",
"example": 0
},
"PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
"type": "integer",
"example": 0
},
"PROXY_SERPS": {
"type": "integer",
"example": 0
},
"PROXY_UNBLOCKER_UNITS": {
"type": "integer",
"example": 0
}
}
},
"usageTotalUsd": {
"type": "number",
"example": 0.00005
},
"usageUsd": {
"type": "object",
"properties": {
"ACTOR_COMPUTE_UNITS": {
"type": "integer",
"example": 0
},
"DATASET_READS": {
"type": "integer",
"example": 0
},
"DATASET_WRITES": {
"type": "integer",
"example": 0
},
"KEY_VALUE_STORE_READS": {
"type": "integer",
"example": 0
},
"KEY_VALUE_STORE_WRITES": {
"type": "number",
"example": 0.00005
},
"KEY_VALUE_STORE_LISTS": {
"type": "integer",
"example": 0
},
"REQUEST_QUEUE_READS": {
"type": "integer",
"example": 0
},
"REQUEST_QUEUE_WRITES": {
"type": "integer",
"example": 0
},
"DATA_TRANSFER_INTERNAL_GBYTES": {
"type": "integer",
"example": 0
},
"DATA_TRANSFER_EXTERNAL_GBYTES": {
"type": "integer",
"example": 0
},
"PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
"type": "integer",
"example": 0
},
"PROXY_SERPS": {
"type": "integer",
"example": 0
},
"PROXY_UNBLOCKER_UNITS": {
"type": "integer",
"example": 0
}
}
}
}
}
}
}
}
}
}