Docs
Quickstart
From key to first answer in a few minutes. For every parameter, see the API reference.
1. Get a key
Keys are issued by hand during the pilot: ask for one.
2. Connect your client
Filings is a hosted MCP server at https://filings-api.fly.dev/mcp (Streamable HTTP). Send your key as Authorization: Bearer YOUR_KEY or X-Api-Key: YOUR_KEY.
Claude Code
claude mcp add --transport http filings \ https://filings-api.fly.dev/mcp \ --header "Authorization: Bearer YOUR_KEY"
Cursor
{
"mcpServers": {
"filings": {
"url": "https://filings-api.fly.dev/mcp",
"headers": {
"Authorization": "Bearer YOUR_KEY"
}
}
}
}Claude (web and desktop)
Claude → Settings → Connectors → Add custom connector Name: Filings URL: https://filings-api.fly.dev/mcp Claude then asks you to sign in: paste your Filings key.
Other MCP clients
Most clients take a JSON entry like this. Some need "type": "http", others ignore it.
{
"mcpServers": {
"filings": {
"type": "http",
"url": "https://filings-api.fly.dev/mcp",
"headers": {
"X-Api-Key": "YOUR_KEY"
}
}
}
}Then ask your agent something like “Does Google file LCAs for software engineers, and what pay do they certify?” It will call identify_employer first and then wage_summary.
3. Your first call
Every answer carries as_of, its data window and a caveat. When a name is ambiguous, assigned is false and you get candidates instead of a guess.
{
"employer_id": "emp_us_google_llc",
"display_name": "Google LLC",
"confidence": 0.96,
"assigned": true,
"reason": "alias+state",
"as_of": "2026-06-30",
"group": {
"group_id": "grp_alphabet",
"display_name": "Alphabet (Google)",
"n_entities": 5
}
}A typical run
Agents compose the tools themselves; there is no workflow to configure. Resolve the employer first, fetch only what the question needs, then stop. Percentiles only come from wage_summary, and only when there are at least 5 certified wages.
identify_employer(query="google", state="CA") # → emp_us_google_llc · 0.96 · alias+state search_cases(employer_id="emp_us_google_llc", job_title="Software Engineer") # → certified cases: title, wage, worksite wage_summary(employer_id="emp_us_google_llc", worksite_state="CA") # → p25 / p50 / p75, only if n ≥ 5 get_case(case_number="I-200-25267-331421") # → one case, as_of, resolved employer
REST API
The same tools are available over HTTPS under https://filings-api.fly.dev/v1/, with the same key. The machine-readable spec is at /openapi.json; the interactive version is the API reference.
curl -X POST https://filings-api.fly.dev/v1/employers/identify \
-H "X-Api-Key: YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "google", "state": "CA"}'Tools
| Tool | Main parameters | What it does |
|---|---|---|
| identify_employer | query, state | Resolve a raw name to an employer_id. Ambiguous names return assigned: false and candidates. |
| employer_profile | employer_id | LCA and PERM certified totals and sample cases for one employer. |
| search_cases | employer_id or employer_query, job_title, soc_code, worksite_city, worksite_state, visa_class, pw_wage_level, fiscal_year, program, limit | Certified cases. Needs at least one of employer, title, SOC code, state or city. |
| get_case | case_number | One LCA (I-200-…) or PERM (G-100-/G-200-/G-300-…) case. |
| wage_summary | same filters as search_cases | Certified wage percentiles; withheld when there are fewer than 5 cases. |
| title_search | same filters, limit | The most-filed job titles. |
| rank_employers | group_by, order_by, filters, limit | Rankings over all matching cases; legal entities roll up into their group. |
| list_releases | — | Every loaded DOL release with fiscal year, quarter, as_of and row counts. |
| cite | what | Official OFLC source, publication date and caveat for the current window. |
| sponsorship_check | company, role, location, fiscal_year, visa_class | Does a company sponsor, optionally for a role and in a place? A finished answer with certified counts, the latest decision and how the name was matched. |
| compare_offer | role, location, salary, company | The salary’s percentile among certified wages for the role and place, and the prevailing wage per level I to IV. Base pay only. |
| sponsor_trends | mode, fiscal_year, base_fiscal_year, filters | Change over fiscal years: per-year counts, growth, decline, new and stopped sponsors. |
Filters
| Filter | What it does |
|---|---|
| fiscal_year | Period: 2024, FY2024, 2022-2024 or all. Default: the last four quarters. A period outside the data returns outside_coverage. |
| role / seniority | A role family across title variants (for example software engineer, nurse), and entry, mid, senior, lead or executive read from the title. |
| metro | bay area, nyc metro, seattle area, dfw or greater boston. |
| program | lca (default) or perm. LCA case numbers start with I-200-, PERM with G-100-, G-200- or G-300-. |
| visa_class | Visa class as filed on the LCA: H-1B, E-3 or H-1B1. |
| worksite_city / worksite_state | City is a contains match; state is the two-letter code. |
| pw_wage_level | Prevailing wage level I to IV. |
| petition_type | new, continued, change_employer or amended. |
| h1b_dependent / willful_violator | Employer flags as filed on the LCA. |
| naics_code | Industry code of the employer. |
Prefer employer_id over raw names. search_cases returns 5 cases by default and at most 25.
Errors and limits
| Status | Meaning | What your agent should do |
|---|---|---|
| 401 | Missing or invalid key | Check the header or the connector URL |
| 429 | Too many rankings at once, or too many failed key attempts | Wait for the Retry-After time in the response |
| outside_coverage | Requested period is outside the loaded data | Call list_releases and pick a covered period |
Troubleshooting
| What you see | What it means and what to do |
|---|---|
| No tools listed | The MCP config path is wrong, or the client was not restarted. Check the URL and key, then restart the client. |
| Empty search | No certified cases for that employer_id in the selected period, or the name was never assigned. Try fiscal_year=all or check the identify_employer result. |
| Low confidence or candidates | Assigning automatically would risk the wrong company. Pick from the candidates, or pass the state. |
| Percentiles missing | Fewer than 5 certified wages. That is a quality rule, not an error. |
| Old as_of date | The data is the published FY2026 Q3 release. Pending cases are out of scope; the next quarter is loaded after DOL publishes it. |
| 401 or 429 | See errors and limits. |
Still stuck? Write to support with the tool name, the arguments and the time of the call.
About the data
Filings serves the public LCA and PERM disclosure files of the Office of Foreign Labor Certification, from October 2019 through 2026-06-30 (FY2026 Q3). Determined cases only: a certified LCA is not a USCIS H-1B approval, and pending cases are not in the files. Case numbers, FEINs, job titles and worksites come back as DOL published them; computed identity always shows its reason. Attorney and point-of-contact names are not exposed.
Filings is independent of the U.S. Department of Labor and does not give legal or immigration advice. For language models, a short summary of all this is at llms.txt.