Updated
API and AI assistants
The federal records behind this site, as JSON for your code and as tools for Claude, Cursor and other assistants.
One request, the federal record
The employer lookup needs no key. Every answer names its source, the date its data reaches and the page it came from.
curl "https://permtracker.app/v1/lookup/employer?name=Google"
{
"data": {
"query": "Google",
"match": "exact",
"employer": {
"name": "Google LLC",
"slug": "google-llc",
"url": "https://permtracker.app/perm-employers/google-llc",
"page": "perm",
"perm": {
"published": 1617,
"certified": 1608,
"denied": 4,
"certifiedShare": 0.998,
"pending": 15,
"newestFiling": "2026-09-25",
"filingsLast12Months": 15
},
"h1bLcas": 66768,
"wageRequests": null
},
"shareFloor": 30
},
"meta": {
"source": "U.S. Department of Labor, OFLC PERM and LCA disclosure files (decided cases) and FLAG case status (pending)",
"asOf": "2026-06-30",
"url": "https://permtracker.app/perm-employers/google-llc"
}
}1 Make a key
Sign in, then Settings, API keys. Free, no card. It’s shown once.
pt_live_…2 Call the API
Send the key in a header, from your server: browsers on other sites can't call it, which keeps keys out of web pages. Every answer names its source, its date and the page it came from.
curl -H "Authorization: Bearer YOUR_KEY" \ https://permtracker.app/v1/queue3 Or connect an assistant
Add this address as a connector. It works without a key, and a key gives an assistant your own limits.
https://permtracker.app/mcp
Plans
Paid features are free for now: every account gets the Plus plan’s limits, exports, live DOL lookups and webhooks until billing opens. We’ll say so here, and email key holders, before that changes.
| Allowance | Free | Plus |
|---|---|---|
| Calls a minute | 10 | 30 |
| Calls a day | 300 | 3,000 |
| Calls a month | 3,000 | 30,000 |
| Live keys | 1 | 3 |
| Sandbox keys | 2 | 2 |
| Rows in one export | None | 1,000 |
| Export rows a day | None | 20,000 |
| Live DOL lookups a day | None | 200 |
| Webhook endpoints | None | 5 |
| Watched cases and employers | None | 100 |
Calls are counted per account and reset at midnight UTC. Need more? Write to us.
Endpoints
All under https://permtracker.app/v1, and GET unless marked. The OpenAPI description has the same list for tools that read it.
Cases
One DOL case by its number, or cases found from what you know about them. PERM, prevailing wage, H-1B LCA, H-2A, H-2B and CW-1.
| Endpoint | What it answers | Example |
|---|---|---|
| /cases/{caseNumber} | Get one case by its number One case by number: its status, filing date, employer and, once decided, DOL's record. Covers PERM, prevailing wage, H-1B LCA and H-2A, H-2B and CW-1 (applications, job orders and wage requests). A seasonal case adds its workers, work period and worksite, and the job as DOL accepted it. A pending PERM case adds its filing month's place in the queue. Needs a key. Counted. | /cases/G-100-26045-123456 |
| /cases | Find cases without a case number Find a case from what you know about it: any of the employer's name, words of the job title and the law firm, with one filing day, a range of days or no date. One of them is enough. Each case comes with its number, status, job and filing day, and the answer says what DOL's record holds for the days read. With no employer fitting in a month or less, it returns the employers that did file in those days under a close spelling. Needs a key. Counted. | /cases?employer=Acme&from=2026-01-05&to=2026-01-31 |
Timing
DOL's processing times, the pending PERM queue by filing month, and an estimate of when a pending PERM case is likely to be decided.
| Endpoint | What it answers | Example |
|---|---|---|
| /estimate | Estimate a PERM decision date When a pending PERM case is likely to be decided, with the range, the model and its caveats. Send a case number, or a filing date for a case in analyst review. It's an estimate from DOL's measured pace and makes no promise: show the caveats with the date. Needs a key. Counted. | /estimate?filed=2026-02-15 |
| /queue | Get DOL's processing times and the pending queue DOL's processing times (average days, and the month each queue is working on when DOL prints one), the filing month DOL is deciding by PERM Tracker's daily check of case statuses (perm.decidingNow: DOL stopped printing a PERM month on Oct 31 2026), the oldest month still open, and the pending PERM cases by filing month. Needs a key. Counted. | /queue |
Visa bulletin
The State Department's monthly visa bulletin charts, as printed, back to June 2005.
| Endpoint | What it answers | Example |
|---|---|---|
| /visa-bulletin | Get a visa bulletin's charts A visa bulletin's employment and family charts (final action dates and dates for filing), as the State Department printed them. The newest by default. Needs a key. Counted. | /visa-bulletin?month=2026-10 |
Employers, law firms and occupations
Each one's PERM record from DOL's published files, and its cases pending at DOL now. Search by name, then get one by its slug.
| Endpoint | What it answers | Example |
|---|---|---|
| /employers | Search employers by name Employers whose name matches, best first. Each result carries its PERM record and the slug that the get endpoint takes. Needs a key. Counted. | /employers?q=acme |
| /employers/{slug} | Get one employer's PERM record One employer's PERM record: cases, certified and denied, median days to decision, filings in the last 12 months, and how many of its cases are pending at DOL now, by stage. Find the slug with the search first. Needs a key. Counted. | /employers/google-llc |
| /law-firms | Search law firms by name Law firms and agents whose name matches, best first. Each result carries its PERM record and the slug that the get endpoint takes. Needs a key. Counted. | /law-firms?q=fragomen |
| /law-firms/{slug} | Get one law firm's PERM record One law firm's PERM record from DOL's published files, and how many of its cases are pending at DOL now, by stage. Find the slug with the search first. Needs a key. Counted. | /law-firms/fragomen-del-rey-bernsen-loewy-llp |
| /occupations | Search occupations by title Occupations whose title matches, best first. Each result carries its SOC code, its PERM record and the slug that the get endpoint takes. Needs a key. Counted. | /occupations?q=software |
| /occupations/{slug} | Get one occupation's PERM record One occupation's PERM record, with its SOC code and median offered wage, and its cases pending at DOL now. Find the slug with the search first. Needs a key. Counted. | /occupations/software-developers |
Lookups
Two lookups that need no key, under shared limits: a printed employer name to its page, and a job title to its SOC codes.
| Endpoint | What it answers | Example |
|---|---|---|
| /lookup/employer | Match a printed employer name to its page The employer page a printed name belongs to: an exact match, a possible one with the matched name, or none. It comes with the employer's PERM decisions, certified share, pending cases, newest filing and H-1B LCAs. No key: it's what the browser extension calls, under shared limits of 60 calls a minute per address. No key. Not counted. | /lookup/employer?name=Google |
| /lookup/soc | Find the SOC codes for a job title The SOC codes employers filed a job title under in DOL's PERM, prevailing wage and LCA files, with each code's share of the title's filings. For a code: its title, O*NET's description and core tasks, the titles employers filed most under it, and its PERM approval rate and median offered wage (under the site's floors). For a 2010 code: the 2018 codes it became. No key, under the same shared limits as the employer lookup. No key. Not counted. | /lookup/soc?q=data%20scientist |
Exports
A search's whole answer, past one page, as CSV or JSON. Needs the export scope.
| Endpoint | What it answers | Example |
|---|---|---|
| /exports/{kind} | Export a search's whole answer A search's whole answer, past one page, as CSV (format=csv) or JSON: cases (the case search's parameters, such as q, firm, state, occupation, outcome, and from and to for the filing date as a month, YYYY-MM, or one day, YYYY-MM-DD), employers, law-firms or occupations (q). Needs the export scope. Plus exports up to 1,000 rows a call and 20,000 rows a day. Counted as one call. Needs the export scope. Counted. | /exports/employers?q=acme&format=csv |
Webhooks
Signed deliveries when a watched case changes status, DOL moves an employer's cases, a visa bulletin is published or the queue moves. Needs the webhooks scope.
| Endpoint | What it answers | Example |
|---|---|---|
| /webhooks | List webhook endpoints This account's webhook endpoints (url, events, whether paused, the secret's last four characters) and its watches, with every event an endpoint can ask for. Needs the webhooks scope. Needs the webhooks scope. Counted. | /webhooks |
| POST /webhooks | Add a webhook endpoint Add an endpoint: a public https address and the events it wants. The answer carries the signing secret, the only time it's shown; keep it to check each delivery's webhook-signature header. Plus has 5 endpoints. Needs the webhooks scope. Needs the webhooks scope. Counted. | /webhooks |
| DELETE /webhooks/{id} | Delete a webhook endpoint Delete an endpoint and its delivery log. Needs the webhooks scope. Needs the webhooks scope. Counted. | /webhooks/jd7abc123def456ghi789 |
| /watches | List watched cases and employers The case numbers and employers this account's webhooks watch, with its endpoints. Needs the webhooks scope. Needs the webhooks scope. Counted. | /watches |
| POST /watches | Watch a case or an employer Watch a case number (case.status_changed fires when DOL's status for it changes) or an employer's page (employer.moved fires when DOL moves its cases as a group). Plus watches 100. Needs the webhooks scope. Needs the webhooks scope. Counted. | /watches |
| DELETE /watches/{target} | Stop watching a case or an employer Stop watching a case number, or an employer with kind=employer. Needs the webhooks scope. Needs the webhooks scope. Counted. | /watches/G-100-26045-123456 |
Account
Your key's plan and usage, and whether the API is up.
| Endpoint | What it answers | Example |
|---|---|---|
| /me | Get your key's plan and usage Your key, the plan whose limits apply to it, and what you've used today and this month. Not counted, so it answers even when a day's allowance is spent. Needs a key. Not counted. | /me |
| /health | Check the API is up Answers ok when the API is serving, with the description's version and where the docs are. No key, never counted, and it reads no records, so it says the API is up and nothing about any one dataset's freshness (each answer's meta.asOf says that). No key. Not counted. | /health |
The shape of every answer
{
"data": { ... },
"meta": {
"source": "Who published the records",
"asOf": "YYYY-MM-DD, the date the data is true for",
"url": "The page on permtracker.app showing the same thing"
}
}Headers carry the limits: RateLimit-Remaining for the minute, X-Calls-Today and X-Calls-Month as used out of allowed.
Errors
Every refusal is JSON with a stable code and a sentence saying what happened and what to do. The body is an RFC 9457 problem document: type, title, status, detail and code. The error object that version 1.0 sent is still inside it, unchanged, so code written against either keeps working. An address under /v1 that isn’t an endpoint answers 404 with the code unknown_endpoint, and a real endpoint asked with the wrong method answers 405 with no body.
{
"type": "https://permtracker.app/developers#error-rate-limited",
"title": "Too many calls this minute",
"status": 429,
"detail": "The Free plan allows 10 calls a minute. Try again in 42 seconds.",
"code": "rate_limited",
"retryAfter": 42,
"error": { "code": "rate_limited", "message": "...", "retryAfter": 42, "docs": "https://permtracker.app/developers" }
} | Status | Code | What it means |
|---|---|---|
| 400 | bad_request | The request isn't valid A parameter is missing, malformed or out of range. The message says which one and what it takes. Not counted. |
| 400 | refused | The change was refused A webhook or watch couldn't be added or removed as asked. The message says why. Not counted. |
| 401 | missing_key | No API key The endpoint needs a key. Make one free in Settings, under API keys, and send it as Authorization: Bearer <key>. Not counted. |
| 401 | invalid_key | The key isn't recognised The key is malformed or isn't one of ours. Keys start with pt_live_ or pt_test_ and are 46 characters long. Not counted. |
| 401 | revoked_key | The key was revoked The key was revoked or replaced. Make a new one in Settings. Not counted. |
| 401 | expired_key | The key has expired The key passed the expiry date it was made with. Make a new one in Settings. Not counted. |
| 403 | missing_scope | The key lacks a scope The key can read public records, and this call needs more: export, live_lookup or webhooks. Make a key with that scope. Not counted. |
| 403 | plan_feature | Not on this plan The plan doesn't include the feature, or has reached how many of something it may hold. Not counted. |
| 403 | sandbox_key | Not with a sandbox key A pt_test_ key answers sample data and can't change anything. Use a live key. Not counted. |
| 404 | unknown_endpoint | No such endpoint The address isn't one of the API's endpoints. The index at /v1 lists them, and so does the OpenAPI document. Not counted. |
| 404 | not_found | No such record We hold no record for what was asked. The message often names a page that can help. Counted, because the lookup ran. |
| 429 | rate_limited | Too many calls this minute The plan's calls a minute are used, or one address is asking faster than the front door allows. Retry-After says how many seconds to wait. Not counted. |
| 429 | daily_limit | The day's calls are used The plan's calls for today are used. They reset at midnight UTC. Not counted. |
| 429 | monthly_limit | The month's calls are used The plan's calls for this month are used. They reset on the first of the month, UTC. Not counted. |
| 429 | busy | Many callers at once The shared pool for calls without a key is full for this minute. Try again shortly, or use a key for your own limit. Not counted. |
| 429 | live_daily_limit | The day's live lookups are used The account's live DOL lookups for today are used. Without live=1 the API still answers from our records. Not counted. |
| 429 | live_api_limit | The API's live lookups are used Every account together has used the API's live DOL lookups for today, so DOL never sees a spike from us. Not counted. |
| 429 | live_site_limit | The site's live lookups are used The whole site's live DOL lookups for today are used, and we hold no record of the case yet. Not counted. |
| 429 | export_daily_limit | The day's export rows are used The account has exported its rows for today. They reset at midnight UTC. Not counted. |
| 500 | internal_error | Something went wrong on our side Our failure, not the request's. Nothing was counted. Try again shortly. Not counted. |
| 503 | unavailable | Not available right now A part the call needs can't be reached, or the server is full for a moment. Retry-After, when it's sent, says how long to wait. Not counted. |
| 503 | key_check_failed | The key couldn't be checked We couldn't check the key just now, so nothing was answered. Try again in a minute. Not counted. |
| 503 | dol_unavailable | DOL didn't answer A live lookup asked DOL and got no answer in time, and we hold no record of the case yet. Not counted. |
| 503 | live_unavailable | The live lookup couldn't run We couldn't count this live lookup, so DOL wasn't asked. Try again in a minute. Not counted. |
| 503 | record_failed | The case couldn't be recorded DOL answered a live lookup, and we couldn't record the case. Try again in a minute. Not counted. |
| 503 | export_unavailable | The export couldn't be counted We couldn't count today's export rows, so nothing was exported or counted. Try again in a minute. Not counted. |
| 503 | not_loaded | The data isn't loaded yet A table the call reads isn't loaded. Try again later. Not counted. |
Scopes, lifetimes and rotation
Each key says what it may do. Give a script only what it needs. A call outside its scopes answers 403 and isn’t counted. Writing to your cases is reserved for the firm tools and can’t be granted yet.
read
Read public records
export
Export search results
live_lookup
Ask DOL live
webhooks
Manage webhooks
cases_read
Read your own cases
A key can last 30 days, 90, a year or until you revoke it. Rotating one gives you a new key at once and keeps the old one working for 24 hours, so you can switch over. A revoked key stops within a minute, usually at once. GET /v1/me shows the key’s scopes, its end and what’s left today.
Sandbox keys
A key that starts pt_test_ answers every read and export from fixed sample data in the same shape as the real thing, and nothing it does is counted. Use one for tests and CI. Its sample cases are G-100-26000-000101, G-100-26000-000102, P-100-26000-000103, I-200-26000-000104: numbers DOL’s numbering never issues, so none is a real person’s case.
Exports and live DOL lookups
/v1/exports/cases takes the case search’s own parameters and returns the whole answer, up to 1,000 rows on Plus, as JSON or CSV (cells a spreadsheet would run as a formula are written as text). When more matched, X-Export-Truncated says so. An export counts as one call, and its rows count toward 20,000 export rows a day on Plus; X-Export-Rows-Left-Today says what’s left.
curl -H "Authorization: Bearer YOUR_KEY" "https://permtracker.app/v1/exports/cases?q=acme&state=CA&format=csv" Add live=1 to a case lookup and a number our records don’t hold yet is asked of DOL right now, then kept, so the nightly sweep follows it. A case we hold answers from our record and costs nothing. Plus has 200 a day, and every account together 20,000, so DOL never sees a spike from us. A refusal names the limit and when it resets.
How webhooks work
Register an https endpoint in Settings or with POST /v1/webhooks, choose its events, and watch case numbers or employers with POST /v1/watches. Each delivery is a signed POST, the Standard Webhooks way, so any of its libraries can check it.
case.status_changed
A watched case changes status
employer.moved
DOL moves a watched employer's cases as a group
bulletin.published
A new visa bulletin is published
queue.moved
DOL's PERM queue reaches a new month
processing_times.updated
DOL republishes its processing times
A delivery, and how to check its signature
POST https://example.com/hooks/perm
webhook-id: msg_jd7abc123
webhook-timestamp: 1791561600
webhook-signature: v1,K5oZ...base64...=
{
"type": "case.status_changed",
"timestamp": "2026-10-09T16:05:00.000Z",
"data": {
"caseNumber": "G-100-26045-123456",
"program": "perm",
"from": "ANALYST REVIEW",
"to": "CERTIFIED",
"isFinal": true,
"observedOn": "2026-10-09",
"url": "https://permtracker.app/perm-case-status?case=G-100-26045-123456"
}
} The signature is HMAC-SHA256, keyed by your secret without its whsec_ prefix (base64-decoded), over the id, the timestamp and the raw body joined by dots. Refuse a timestamp more than five minutes off, and use the id to skip a delivery you’ve already handled: it’s the same on every retry.
import { createHmac, timingSafeEqual } from "node:crypto";
// secret: the whsec_... value shown when you made the endpoint
export function verify(secret, headers, rawBody) {
const key = Buffer.from(secret.slice("whsec_".length), "base64");
const signed = `${headers["webhook-id"]}.${headers["webhook-timestamp"]}.${rawBody}`;
const want = createHmac("sha256", key).update(signed).digest("base64");
const age = Math.abs(Date.now() / 1000 - Number(headers["webhook-timestamp"]));
return age < 300 && headers["webhook-signature"].split(" ").some((s) => {
const got = s.split(",")[1] ?? "";
return got.length === want.length && timingSafeEqual(Buffer.from(got), Buffer.from(want));
});
}Answer with any 2xx within 10 seconds. Anything else, a redirect included, is retried after 1 minute, 5 minutes, 30 minutes, 2 hours, 5 hours, 10 hours and at the 24-hour mark. After 24 hours the endpoint pauses, we email you once, and events from the last 30 days wait for you to resume it. The delivery log in Settings keeps 30 days, with a button to send any one again.
AI assistants
13 read-only tools over the Model Context Protocol, one for each read endpoint and named after it. Each calls the same code as its endpoint, so an assistant and the API can’t disagree.
get_case
Get a case by its number
One case by number: its status, filing date, employer and, once decided, DOL's record.
find_cases
Find cases without a case number
Find a case from what you know about it: any of the employer's name, words of the job title and the law firm, with one filing day, a range of days or no date.
estimate_decision
Estimate a PERM decision date
When a pending PERM case is likely to be decided, with the range, the model and its caveats.
get_queue
Get processing times and the pending queue
DOL's processing times (average days, and the month each queue is working on when DOL prints one), the filing month DOL is deciding by PERM Tracker's daily check of case statuses (perm.decidingNow: DOL stopped printing a PERM month on Oct 31 2026), the oldest month still open, and the pending PERM cases by filing month.
get_visa_bulletin
Get a visa bulletin
A visa bulletin's employment and family charts (final action dates and dates for filing), as the State Department printed them.
search_employers
Search employers by name
Employers whose name matches, best first.
get_employer
Get an employer's PERM record
One employer's PERM record: cases, certified and denied, median days to decision, filings in the last 12 months, and how many of its cases are pending at DOL now, by stage.
search_law_firms
Search law firms by name
Law firms and agents whose name matches, best first.
get_law_firm
Get a law firm's PERM record
One law firm's PERM record from DOL's published files, and how many of its cases are pending at DOL now, by stage.
search_occupations
Search occupations by title
Occupations whose title matches, best first.
get_occupation
Get an occupation's PERM record
One occupation's PERM record, with its SOC code and median offered wage, and its cases pending at DOL now.
lookup_employer
Match an employer's name to its page
The employer page a printed name belongs to: an exact match, a possible one with the matched name, or none.
lookup_soc
Find a job title's SOC codes
The SOC codes employers filed a job title under in DOL's PERM, prevailing wage and LCA files, with each code's share of the title's filings.
Tool names from version 1.0
The tools were renamed in version 1.1 to match the endpoints. A call under an old name is still answered, so nothing that learned the old names breaks. The list an assistant sees shows the new names only.
lookup_caseis nowget_casefind_caseis nowfind_casesqueue_statusis nowget_queuevisa_bulletinis nowget_visa_bulletinsearch_sponsorsis nowsearch_employers, search_law_firms or search_occupationsemployer_profileis nowget_employer, get_law_firm or get_occupationfind_soc_codeis nowlookup_soc
Claude
Add a custom connector with this address. No key needed.
https://permtracker.app/mcpClaude Code
The header is optional.
claude mcp add --transport http permtracker \
https://permtracker.app/mcp \
--header "Authorization: Bearer YOUR_KEY"Cursor
In mcp.json.
{
"mcpServers": {
"permtracker": {
"url": "https://permtracker.app/mcp",
"headers": {
"Authorization": "Bearer YOUR_KEY"
}
}
}
}What changed
The API is at version 1.1.0. Inside version 1 things are added and never taken away: an endpoint, a field or an error code that shipped keeps its name and its meaning.
Version 1.1.0, November 14, 2026
- The OpenAPI document names every operation (operationId), groups them by tag, types every parameter with an example, and publishes each answer's schema with an example.
- Errors are RFC 9457 problem documents (application/problem+json) with type, title, status, detail and code. The error object version 1.0 sent is still inside, unchanged.
- The assistant server offers one tool per read operation, named after it: get_case, find_cases, estimate_decision, get_queue, get_visa_bulletin, search_employers, get_employer, search_law_firms, get_law_firm, search_occupations, get_occupation, lookup_employer and lookup_soc. Calls under the old names are still answered.
- Tools return typed output (structuredContent) beside the text, and each tool publishes the full shape of its answer.
- An address under /v1 that isn't an endpoint answers 404 as JSON (unknown_endpoint), where it used to get the site's HTML page.
- A caller asking too fast, or arriving while the server is full, gets the same error shape as every other refusal (rate_limited, unavailable). That reply used to carry `error` as a word.
- A new endpoint, /health, says the API is up. No key.
- The X-API-Key header is documented beside Authorization: Bearer.
Version 1.0.0, October 2, 2026
- The first version: cases, estimates, the queue, the visa bulletin, and employers, law firms and occupations, as JSON and as assistant tools.
The rules
Use it under the API terms. Credit “PERM Tracker (permtracker.app)” where you show what it returns, keep your key out of public code, and don’t use it to copy the whole compilation. The records come from DOL and the State Department. Estimates are ours and say so.