# USAJOBS — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Search federal job openings and view detailed job announcements from USAJobs.gov, plus access historical job data and reference codes to help you find the right government position. Filter and explore thousands of federal career opportunities with comprehensive job details all in one place.

**Category:** Jobs | **Website:** [usajobs.gov/](https://usajobs.gov/) | **Docs:** [parse.bot/marketplace/e9e6899f-8d98-41b2-ae65-1b669e5123ba/usajobs-gov-api](https://parse.bot/marketplace/e9e6899f-8d98-41b2-ae65-1b669e5123ba/usajobs-gov-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-usajobs-gov-api-e9e6899f/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_codelist

Retrieve reference code lists used by USAJobs for various classification fields. Each code list contains validated entries with their codes, display values, and status. Use these codes as filter values in search and historic JOA queries.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `list_name` | string | Yes | The name of the code list to retrieve. Accepted values: 'occupationalseries', 'agencysubelements', 'payplans', 'hiringpaths', 'whomayapply', 'positionscheduletypes' |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-usajobs-gov-api-e9e6899f/get_codelist \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"list_name":"<string>"}'
```

### get_historic_joas

Retrieve historic Job Opportunity Announcements (JOAs) metadata. Supports bulk retrieval by agency code, control numbers, or date ranges. At least one filter parameter is required. Returns up to 500 records per page with a continuation token for further pages.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `agency_code` | string | No | Filter by hiring agency code (e.g., 'TD03' for FAA, 'NV27' for US Marine Corps, 'HE37' for Indian Health Service) |
| `control_numbers` | string | No | Comma-separated list of USAJobs Control Numbers |
| `end_close_date` | string | No | Filter by end of position close date (YYYY-MM-DD) |
| `end_open_date` | string | No | Filter by end of position open date (YYYY-MM-DD) |
| `start_close_date` | string | No | Filter by start of position close date (YYYY-MM-DD) |
| `start_open_date` | string | No | Filter by start of position open date (YYYY-MM-DD) |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-usajobs-gov-api-e9e6899f/get_historic_joas \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agency_code":"<string>","control_numbers":"<string>","end_close_date":"<string>","end_open_date":"<string>","start_close_date":"<string>","start_open_date":"<string>"}'
```

### get_job_detail

Retrieve full details for a specific job announcement by its control number. Returns a flat object with structured metadata (salary, locations, agency, hiring paths, work schedule, security clearance) and key announcement text fields (summary, duties, qualifications, how to apply). The control_number is the DocumentID from search_jobs results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `control_number` | string | Yes | The USAJobs Control Number (DocumentID from search_jobs results) |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-usajobs-gov-api-e9e6899f/get_job_detail \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"control_number":"<string>"}'
```

### search_jobs

Search for current federal job openings on USAJobs.gov. Supports keyword and location filters with paginated results. Each result includes job title, agency, salary, location, work schedule, and hiring paths. Returns up to 100 results per page.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `keyword` | string | No | Search keyword to match against job titles and descriptions (e.g., 'engineer', 'analyst', 'nurse') |
| `location` | string | No | Location name to filter results (e.g., 'Washington DC', 'New York', 'Texas') |
| `page` | integer | No | Page number of results (1-based) |
| `results_per_page` | integer | No | Number of results per page (1 to 100) |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-usajobs-gov-api-e9e6899f/search_jobs \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keyword":"<string>","location":"<string>","page":"<integer>","results_per_page":"<integer>"}'
```