# USAJobs Federal Reference Codelist Lookup

> USAJobs Federal Reference Codelist Lookup is a paid API for AI agents from 2s.io, paid per call via x402, $0.0012/call, status unknown (last checked 2026-09-14).

Fetches one of 33 official USAJobs reference codelists (agencies, pay plans, hiring paths, occupational series, security clearances, etc.) used as filter inputs for federal job searches.

## Facts

- Endpoint: GET https://2s.io/api/job/federal-codes
- Price: $0.0012/call
- Payment: x402
- Status: unknown
- Last checked: 2026-09-14
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/2s-io-7b8ec433
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_u57Hcbs2OowxCX5cF5TkI

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability 2s-io-7b8ec433
```

Example prompt: Can you pull the full list of federal hiring path codes from USAJobs — I need the valid values like 'veterans', 'military spouse', and 'native American' so I can use them to filter a federal job search?

## When to prefer this

Use this endpoint when you need to discover or validate the exact code values accepted by the federal job search endpoint (/api/job/federal-search). This is the authoritative source for all USAJobs reference data — agencies, pay plans, occupational series, hiring paths, clearances, etc. Prefer this over hardcoding values, as the lists are maintained by OPM and may change.

## Known failure modes

- Invalid or missing 'name' parameter returns an error — must be one of the 33 exact enum values
- Network timeout if USAJobs upstream is unavailable
- Empty list returned if the codelist has no current entries
- Payment failure (x402) if USDC balance is insufficient

## How this service works

Fetch a USAJobs reference codelist (lookup tables behind every federal job posting). Pass name to pick which list: agencysubelements (every agency + sub-element), occupationalseries (2210 IT, 0301 Misc Admin, 0801 Engineer, etc.), paygrades, payplans (GS, SES, ES, WG, etc.), hiringpaths (veteran, military spouse, native American, etc.), securityclearances, locationcodes, countries, countrysubdivisions, ethnicities, racecodes, militarystatuscodes, languagecodes, positionscheduletypecodes (full-time/part-time/seasonal), travelpercentages, missioncriticalcodes, cyberworkroles, etc. (33 lists total). Use the returned codes as filter inputs to /api/job/federal-search.

## Output

Returns a reference codelist array containing code-value pairs (e.g. code ID + human-readable label) for the requested list type — such as all agency subelements, all GS/SES/WG pay plans, all occupational series with titles, all hiring path identifiers, etc. These codes are used as structured filter parameters for the USAJobs federal job search endpoint.

## Example request

```json
{
 "input": {
  "type": "http",
  "method": "GET",
  "queryParams": {
   "name": "securityclearances"
  }
 }
}
```

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "required": [
  "input"
 ],
 "properties": {
  "input": {
   "type": "object",
   "required": [
    "type",
    "method",
    "queryParams"
   ],
   "properties": {
    "type": {
     "const": "http"
    },
    "method": {
     "const": "GET"
    },
    "queryParams": {
     "required": [
      "name"
     ],
     "properties": {
      "name": {
       "enum": [
        "academichonors",
        "agencysubelements",
        "announcementclosingtypes",
        "applicantsuppliers",
        "cyberworkroles",
        "countries",
        "countrysubdivisions",
        "degreetypecodes",
        "documentations",
        "ethnicities",
        "federalemploymentstatuses",
        "geoloccodes",
        "hiringpaths",
        "languagecodes",
        "languageproficiencies",
        "locationcodes",
        "militarystatuscodes",
        "missioncriticalcodes",
        "occupationalseries",
        "paygrades",
        "payplans",
        "positionofferingtypecodes",
        "positionopeningstatuses",
        "positionscheduletypecodes",
        "racecodes",
        "refereetypecodes",
        "remunerationrateintervalcodes",
        "requiredstandarddocuments",
        "securityclearances",
        "servicetypes",
        "specialhirings",
        "travelpercentages",
        "whomayapply"
       ],
       "type": "string"
      }
     }
    }
   }
  }
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/2s-io-7b8ec433/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from 2s.io](https://www.zero.xyz/host/2s.io/llms.txt)