{ "openapi": "3.0.1", "info": { "title": "USCIS H-1B Employer Data: Approvals and Denials by Company", "description": "Official USCIS H-1B employer files as rows: fiscal year, employer, initial and continuing approvals and denials, totals and denial rate, NAICS sector with its name, tax-ID last four, city, state and ZIP. Filter by employer, state, city, industry, ZIP or petition volume. FY2009-FY2023, UTC dates.", "version": "0.1", "x-build-id": "16cVrAVAuxAxZ7CfX" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/yadroo~uscis-h1b-employers/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-yadroo-uscis-h1b-employers", "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/yadroo~uscis-h1b-employers/runs": { "post": { "operationId": "runs-sync-yadroo-uscis-h1b-employers", "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/yadroo~uscis-h1b-employers/run-sync": { "post": { "operationId": "run-sync-yadroo-uscis-h1b-employers", "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": { "mode": { "title": "What one row should be", "enum": [ "byYear", "employerTotals" ], "type": "string", "description": "What one dataset row is. `byYear` keeps the published granularity: one row per employer per fiscal year you asked for - for a year-over-year chart or a research table. `employerTotals` sums the four decision counts of an employer over the selected fiscal years into one row and adds `yearCount`, `firstFiscalYear`, `lastFiscalYear` and `fiscalYearsCovered` - for a sponsor profile. The filters below work the same in both modes and are applied to the published rows before anything is summed.", "default": "byYear" }, "fiscalYears": { "title": "Fiscal years", "maxItems": 15, "type": "array", "description": "Which fiscal-year files to read; each one is a separate download, so each extra year costs time, not extra rows per employer. FY2023 is the newest year published as a file. The platform refuses any other value before the run starts - a later fiscal year exists only inside the interactive data hub, whose own pages and export buttons the site closes to automated clients, so this actor does not read them. Leave empty and the newest year (FY2023) is used.", "items": { "type": "string", "enum": [ "2023", "2022", "2021", "2020", "2019", "2018", "2017", "2016", "2015", "2014", "2013", "2012", "2011", "2010", "2009" ], "enumTitles": [ "FY 2023 (Oct 2022 - Sep 2023) - newest file", "FY 2022", "FY 2021", "FY 2020", "FY 2019", "FY 2018", "FY 2017", "FY 2016", "FY 2015", "FY 2014", "FY 2013", "FY 2012", "FY 2011", "FY 2010", "FY 2009 - oldest file" ] } }, "employers": { "title": "Employer name contains", "maxItems": 20, "type": "array", "description": "Free text matched inside the employer name as filed: `microsoft`, `mayo clinic`. Case, punctuation and spaces are ignored, so `walmart` finds `WAL MART ASSOCIATES INC`; several values are combined with OR. Matching is on a part of the name on purpose: these names are filed by hand and often shortened (`SAGINAW VLY ST UNIV`). The value that found a row is written to `matchedEmployer`, and a value that matched nothing is named in the run's status message, so you can shorten it and run again.", "items": { "type": "string" } }, "states": { "title": "Employer state", "maxItems": 56, "type": "array", "description": "Two-letter codes of the employer's mailing address, combined with OR. The platform refuses any value outside the list before the run starts, so pick the codes from the dropdown. This is the address on the petition, not where the worker sits, so a national employer filing from one headquarters shows up in one state only - say so in any report you build on it. The full state name is written to every row as `stateName`. The oldest files leave the state empty on some rows.", "items": { "type": "string", "enum": [ "AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "DC", "FL", "GA", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "WA", "WV", "WI", "WY", "PR", "GU", "VI", "AS", "MP" ], "enumTitles": [ "Alabama", "Alaska", "Arizona", "Arkansas", "California", "Colorado", "Connecticut", "Delaware", "District of Columbia", "Florida", "Georgia", "Hawaii", "Idaho", "Illinois", "Indiana", "Iowa", "Kansas", "Kentucky", "Louisiana", "Maine", "Maryland", "Massachusetts", "Michigan", "Minnesota", "Mississippi", "Missouri", "Montana", "Nebraska", "Nevada", "New Hampshire", "New Jersey", "New Mexico", "New York", "North Carolina", "North Dakota", "Ohio", "Oklahoma", "Oregon", "Pennsylvania", "Rhode Island", "South Carolina", "South Dakota", "Tennessee", "Texas", "Utah", "Vermont", "Virginia", "Washington", "West Virginia", "Wisconsin", "Wyoming", "Puerto Rico", "Guam", "U.S. Virgin Islands", "American Samoa", "Northern Mariana Islands" ] } }, "cities": { "title": "Employer city", "maxItems": 20, "type": "array", "description": "City names as a whole value: `Seattle`, `NEW YORK`, `san jose`. Case and extra spaces are ignored and several values are combined with OR, but unlike the employer filter this one matches the whole city name, so `york` does not pull in `NEW YORK`. The files write the city as filed and in capitals; a value that matched nothing is named in the run's status message.", "items": { "type": "string" } }, "zipPrefixes": { "title": "ZIP code or ZIP prefix", "maxItems": 20, "type": "array", "description": "A full five-digit ZIP (`98101`) or the first two to five digits of one (`100` keeps every 100xx ZIP in New York). Several values are combined with OR, with the state and city filters combined as AND, so `states: ['NY']` plus `zipPrefixes: ['100']` is Manhattan only. The ZIP is the employer's mailing address and is empty on some rows of the oldest files.", "items": { "type": "string" } }, "naics": { "title": "Industry (2-digit NAICS sector)", "maxItems": 25, "type": "array", "description": "The sector the employer is classified in, as the two-digit code the files carry; values are combined with OR. Code 99 means the file itself does not know the industry, and it covers a large share of the smaller employers. Every row also gets `naicsLabel`, the plain name of the sector, so a dataset can be read without a code table. The platform refuses any value outside this list before the run starts.", "items": { "type": "string", "enum": [ "11", "21", "22", "23", "31", "32", "33", "42", "44", "45", "48", "49", "51", "52", "53", "54", "55", "56", "61", "62", "71", "72", "81", "92", "99" ], "enumTitles": [ "11 - Agriculture, forestry, fishing and hunting", "21 - Mining, quarrying, oil and gas extraction", "22 - Utilities", "23 - Construction", "31 - Manufacturing: food, textiles, apparel", "32 - Manufacturing: wood, paper, chemicals, plastics", "33 - Manufacturing: metals, machinery, electronics, vehicles", "42 - Wholesale trade", "44 - Retail trade: vehicles, building, food, health stores", "45 - Retail trade: clothing, sports, general and online stores", "48 - Transportation", "49 - Postal service, couriers and warehousing", "51 - Information: software publishing, telecoms, media", "52 - Finance and insurance", "53 - Real estate, rental and leasing", "54 - Professional, scientific and technical services (IT consulting, engineering, research)", "55 - Management of companies and enterprises", "56 - Administrative and support services (staffing agencies)", "61 - Educational services (universities, schools)", "62 - Health care and social assistance (hospitals, clinics)", "71 - Arts, entertainment and recreation", "72 - Accommodation and food services", "81 - Other services except public administration", "92 - Public administration", "99 - Industry unknown, as the file records it" ] } }, "minTotalApprovals": { "title": "Minimum approvals in the row", "minimum": 0, "type": "integer", "description": "Keep only rows whose initial and continuing approvals add up to at least this many workers - `totalApprovals` in the row. Most employers in these files have one or two approvals, so a value like 50 or 100 turns a whole state into a short list of the employers that really sponsor at scale. In employerTotals mode the threshold is applied to the summed row, so it means 'this many over all the selected years'." }, "minTotalDenials": { "title": "Minimum denials in the row", "minimum": 0, "type": "integer", "description": "Keep only rows with at least this many denied workers (`totalDenials`). Set it to 1 to study where decisions went against the employer; combine it with an industry or a state to compare denial patterns. Note that a denial here is a first decision, so a case later won on appeal still counts as a denial in the file." }, "maxDenialRate": { "title": "Maximum denial rate", "minimum": 0, "maximum": 1, "type": "number", "description": "Keep only rows whose `denialRate` (denials divided by all decisions in the row) is at most this much: `0.1` for employers that were refused in at most a tenth of their decisions. Rows with no decisions at all have no rate and are dropped by this filter. The rate is computed by this actor - the files publish the counts only." }, "sort": { "title": "Order of the rows", "enum": [ "approvalsDesc", "denialsDesc", "denialRateDesc", "employer", "fiscalYear" ], "type": "string", "description": "Which rows you get first when `maxItems` cuts the answer - the published files are in alphabetical order, so without a sort the biggest sponsors would be hidden behind thousands of one-petition employers. In `byYear` mode the order is applied inside each fiscal year, and the years are written newest first, so a two-year run with `maxItems: 25` gives the top 25 of the newest year. In `employerTotals` mode every selected year is read first and the order is applied to the whole result.", "default": "approvalsDesc" }, "maxItems": { "title": "Maximum rows", "minimum": 1, "maximum": 5000, "type": "integer", "description": "Hard cap on the rows this run writes, and therefore on what it costs. A single fiscal-year file holds tens of thousands of employers, so a run with no filters and a high cap is a lot of rows for little insight - filter first, sort second, and keep the cap small. Reading a file always costs the same few seconds whatever the cap is.", "default": 50 }, "onlyNew": { "title": "Skip rows written by earlier runs", "type": "boolean", "description": "Write only rows no earlier run wrote. Every row written is remembered (fiscal year, employer name and tax-ID last four) in the actor's key-value store, per actor or task, so two tasks watching two states do not interfere. It is a way not to pay twice for the same employer: a rerun returns the next rows of the list, so you can take a long result 50 rows at a time or widen the filters later. The published files do not change, so this is not a 'last N hours' window.", "default": false }, "fields": { "title": "Only these columns", "type": "array", "description": "Keep only the named columns, in the order given - for example `employer, state, totalApprovals, denialRate`. Empty = every column. `fiscalYear`, `employer`, `totalApprovals`, `totalDenials`, `url` and `fetchedAt` are always present; name one of them here and it moves to the position you gave it. Unknown names are reported in the run's status message instead of being dropped in silence.", "items": { "type": "string" } } } }, "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 } } } } } } } } } }