# H-1B Salary Data API: Full Reference

> Complete API documentation for LLM consumption.

## Overview

REST API serving 8M+ H-1B visa salary records from U.S. DOL/OFLC LCA filings.
All salaries normalized to annual. Free tier available. Paid plans from $9/mo.

Base URL: https://h1bapi.com

## Authentication

API key required via `X-API-Key` header.

## Pricing

| Tier | Price | Requests/day | Features |
|------|-------|-------------|----------|
| Free | $0 | 20 | Last 2 fiscal years, 6 fields, 25 results/page |
| Dev | $9/mo | 5,000 | All years, all fields, 50 results/page |
| Pro | $29/mo | 25,000 | All years, all fields, 100 results/page |
| Business | $79/mo | 100,000 | Everything, priority support |

## GET /api/v1/salaries

Search and filter H-1B salary filings.

### Query Parameters

| Parameter       | Type    | Required | Description                                      | Example            |
|----------------|---------|----------|--------------------------------------------------|--------------------|
| employer       | string  | no       | Employer name (case-insensitive, partial match)   | google             |
| job_title      | string  | no       | Job title (case-insensitive, partial match)       | software engineer  |
| soc_code       | string  | no       | SOC occupation code (exact or prefix)             | 15-1252            |
| state          | string  | no       | Worksite state (2-letter code)                    | CA                 |
| city           | string  | no       | Worksite city (case-insensitive, partial match)   | Mountain View      |
| fiscal_year    | integer | no       | Fiscal year                                       | 2024               |
| min_salary     | number  | no       | Minimum annual salary filter                      | 100000             |
| max_salary     | number  | no       | Maximum annual salary filter                      | 300000             |
| case_status    | string  | no       | Certified, Denied, Withdrawn, Certified - Withdrawn | Certified          |
| wage_level     | string  | no       | Prevailing wage level: I, II, III, IV             | III                |
| sort           | string  | no       | salary_asc, salary_desc (default), date           | salary_desc        |
| page           | integer | no       | Page number (default: 1)                          | 1                  |
| per_page       | integer | no       | Results per page (default: 25, max: varies by tier) | 25                 |
| include_suspect| string  | no       | Include suspect salary rows (default: false)      | false              |

### Example Request

```
GET /api/v1/salaries?employer=google&job_title=software+engineer&state=CA&sort=salary_desc
```

### Example Response

```json
{
  "results": [
    {
      "case_number": "I-200-12345-678901",
      "case_status": "Certified",
      "employer": "Google LLC",
      "job_title": "Software Engineer",
      "soc_code": "15-1252",
      "soc_title": "Software Developers",
      "salary_min": 185000,
      "salary_max": 210000,
      "wage_unit_original": "Year",
      "prevailing_wage_annual": 165000,
      "wage_level": "III",
      "worksite_city": "Mountain View",
      "worksite_state": "CA",
      "fiscal_year": 2024,
      "full_time": true,
      "visa_class": "H-1B",
      "salary_suspect": false,
      "received_date": "2024-01-15",
      "decision_date": "2024-02-01"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "has_more": true
  }
}
```

### Response Fields

| Field                  | Type    | Description                                  |
|-----------------------|---------|----------------------------------------------|
| case_number           | string  | DOL case number                              |
| case_status           | string  | Application status                           |
| employer              | string  | Employer name                                |
| job_title             | string  | Job title as filed                           |
| soc_code              | string  | Standard Occupational Classification code    |
| soc_title             | string  | SOC occupation title                         |
| salary_min            | number  | Minimum annual salary (normalized)           |
| salary_max            | number  | Maximum annual salary (normalized)           |
| wage_unit_original    | string  | Original wage unit before normalization      |
| prevailing_wage_annual| number  | Prevailing wage (annual)                     |
| wage_level            | string  | Prevailing wage level (I-IV)                 |
| worksite_city         | string  | Work location city                           |
| worksite_state        | string  | Work location state                          |
| fiscal_year           | number  | DOL fiscal year                              |
| full_time             | boolean | Full-time position                           |
| visa_class            | string  | Visa classification                          |
| salary_suspect        | boolean | Flagged if salary seems anomalous            |
| received_date         | string  | Date application received                    |
| decision_date         | string  | Date decision made                           |

## MCP Server (AI Tool Integration)

Connect this API to Claude, Cursor, Windsurf, or any MCP client:

```
npx h1b-salary-mcp
```

Environment variable: H1B_API_KEY (required, get free key at /docs)

### MCP Tools

| Tool | Description | Key Parameters |
|------|-------------|----------------|
| search_salaries | Search H-1B filings | employer, job_title, state, city, fiscal_year, min_salary, wage_level, sort, page |
| get_top_employers | Rank companies by volume or salary | job_title, state, fiscal_year, rank_by (volume/salary), limit |
| compare_salaries | Compare two employers or cities | job_title, compare_type (employer/city), value_a, value_b, state, fiscal_year |

### Configuration

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):
```json
{
  "mcpServers": {
    "h1b-salaries": {
      "command": "npx",
      "args": ["h1b-salary-mcp"],
      "env": { "H1B_API_KEY": "your_key" }
    }
  }
}
```

## Data Source

U.S. Department of Labor, Office of Foreign Labor Certification (OFLC).
Public LCA disclosure files, updated quarterly.
Over 8 million records spanning multiple fiscal years.