PERM Tracker
Live DOL data · Automatic deadlines
Skip to main content

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.

Terminal
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"
  }
}
Asked October 22, 2026.
  1. 1 Make a key

    Sign in, then Settings, API keys. Free, no card. It’s shown once.

    pt_live_…
  2. 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/queue
  3. 3 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_case is now get_case
  • find_case is now find_cases
  • queue_status is now get_queue
  • visa_bulletin is now get_visa_bulletin
  • search_sponsors is now search_employers, search_law_firms or search_occupations
  • employer_profile is now get_employer, get_law_firm or get_occupation
  • find_soc_code is now lookup_soc

Claude

Add a custom connector with this address. No key needed.

https://permtracker.app/mcp

Claude 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.

  1. 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.
  2. 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.