---
title: "Fetch a USAJobs reference codelist (lookup tables behind..."
method: GET
path: "/api/job/federal-codes"
tags: ["job"]
---

# Fetch a USAJobs reference codelist (lookup tables behind...

`GET /api/job/federal-codes`

## Request

- Base URL: `https://2s.io`
- URL: `https://2s.io/api/job/federal-codes`
- Auth: API key in header `PAYMENT-SIGNATURE`

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.

## Query parameters

- `name` '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', required
- `trial` 1

## Other responses

- `200` (unresolved $ref)
- `400`: Invalid request — not charged. error.code: BAD_REQUEST or INVALID_PARAM (parameter validation; error.details.issues lists each problem), MALFORMED_JSON, or a request-specific code. Other client errors: 405 METHOD_NOT_ALLOWED (wrong verb; see the Allow header), 413 PAYLOAD_TOO_LARGE.
- `402`: Payment required. Body is the x402 PaymentRequirements envelope with a multi-network accepts array; the per-call price is in accepts[].amount (and on the operation as x-2s-price). Sign for whichever rail you hold USDC on (EIP-3009 for Base, partial SPL transfer for Solana) and retry with the PAYMENT-SIGNATURE header (X-PAYMENT also accepted for v1 clients). Also PAYMENT_SETTLE_FAILED (error envelope) when a verified payment failed to settle: error.details.chargeStatus is "not_charged" (retry with a fresh payment) or "unknown" (the authorization may still settle before its deadline — check it before retrying).
- `404`: Not found — NOT_FOUND (or NO_SOURCES / NO_OPINIONS): the requested entity does not exist. Not charged.
- `429`: Too many requests — RATE_LIMITED: our per-IP / per-payer limiter. Not charged; retry after Retry-After.
- `5XX`: Server-side failure. 500 INTERNAL: unexpected error; quote error.errorId (also the X-2s-Error-Id header). 502 UPSTREAM_UNAVAILABLE (or another UPSTREAM_* code): the data provider failed — composite endpoints refuse unbilled when every source fails. 503 SERVICE_PAUSED: endpoint paused by the operator kill switch, retry after Retry-After; 503 SPEND_CAP: daily upstream budget exhausted. 504 UPSTREAM_TIMEOUT. Not charged.

---

[API](https://skmtc.dev/2s-io/apis/2s-the-most-everything-api.md) · [All operations](https://skmtc.dev/2s-io/apis/2s-the-most-everything-api/llms.txt) · [OpenAPI document](https://skmtc.dev/2s-io/apis/2s-the-most-everything-api/revisions/da4c5caf686e?raw)