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

terminal
claude mcp add --transport http filings \
  https://filings-api.fly.dev/mcp \
  --header "Authorization: Bearer YOUR_KEY"

Cursor

.cursor/mcp.json
{
  "mcpServers": {
    "filings": {
      "url": "https://filings-api.fly.dev/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_KEY"
      }
    }
  }
}

Claude (web and desktop)

Settings → Connectors
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.

mcp.json
{
  "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.

identify_employer · response (trimmed)
{
  "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 → search → wage → case
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
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

ToolMain parametersWhat it does
identify_employerquery, stateResolve a raw name to an employer_id. Ambiguous names return assigned: false and candidates.
employer_profileemployer_idLCA and PERM certified totals and sample cases for one employer.
search_casesemployer_id or employer_query, job_title, soc_code, worksite_city, worksite_state, visa_class, pw_wage_level, fiscal_year, program, limitCertified cases. Needs at least one of employer, title, SOC code, state or city.
get_casecase_numberOne LCA (I-200-…) or PERM (G-100-/G-200-/G-300-…) case.
wage_summarysame filters as search_casesCertified wage percentiles; withheld when there are fewer than 5 cases.
title_searchsame filters, limitThe most-filed job titles.
rank_employersgroup_by, order_by, filters, limitRankings 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.
citewhatOfficial OFLC source, publication date and caveat for the current window.
sponsorship_checkcompany, role, location, fiscal_year, visa_classDoes 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_offerrole, location, salary, companyThe salary’s percentile among certified wages for the role and place, and the prevailing wage per level I to IV. Base pay only.
sponsor_trendsmode, fiscal_year, base_fiscal_year, filtersChange over fiscal years: per-year counts, growth, decline, new and stopped sponsors.

Filters

FilterWhat it does
fiscal_yearPeriod: 2024, FY2024, 2022-2024 or all. Default: the last four quarters. A period outside the data returns outside_coverage.
role / seniorityA role family across title variants (for example software engineer, nurse), and entry, mid, senior, lead or executive read from the title.
metrobay area, nyc metro, seattle area, dfw or greater boston.
programlca (default) or perm. LCA case numbers start with I-200-, PERM with G-100-, G-200- or G-300-.
visa_classVisa class as filed on the LCA: H-1B, E-3 or H-1B1.
worksite_city / worksite_stateCity is a contains match; state is the two-letter code.
pw_wage_levelPrevailing wage level I to IV.
petition_typenew, continued, change_employer or amended.
h1b_dependent / willful_violatorEmployer flags as filed on the LCA.
naics_codeIndustry code of the employer.

Prefer employer_id over raw names. search_cases returns 5 cases by default and at most 25.

Errors and limits

StatusMeaningWhat your agent should do
401Missing or invalid keyCheck the header or the connector URL
429Too many rankings at once, or too many failed key attemptsWait for the Retry-After time in the response
outside_coverageRequested period is outside the loaded dataCall list_releases and pick a covered period

Troubleshooting

What you seeWhat it means and what to do
No tools listedThe MCP config path is wrong, or the client was not restarted. Check the URL and key, then restart the client.
Empty searchNo 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 candidatesAssigning automatically would risk the wrong company. Pick from the candidates, or pass the state.
Percentiles missingFewer than 5 certified wages. That is a quality rule, not an error.
Old as_of dateThe data is the published FY2026 Q3 release. Pending cases are out of scope; the next quarter is loaded after DOL publishes it.
401 or 429See 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.