API Access
Updated monthly | Data as of May 2026
Open, programmatic access to Employment, Accessions, and Separations data. No authentication required.
Getting started
BASE URL
https://data.opm.gov/api/v1/files
Parameters
| Name | Type | Format | Definition |
|---|---|---|---|
version |
int |
- |
Filters results to datasets matching the specified version number. |
current |
bool |
true/false |
Filters results by whether a dataset is the current version. |
month |
string |
MM |
Filters results to datasets from the specified month. Accepts full name (January), 3-letter abbreviation (Jan), or numeric 1–12. Case-insensitive. |
year |
int |
YYYY |
Filters results to datasets from the specified year. Must be a 4-digit value between 1900 and 9999. |
dataCapturedThrough |
date |
MM/DD/YYYY |
Filters results to datasets whose reference period matches the month, day, and year of the provided date. |
publishedBefore |
date |
MM/DD/YYYY |
Returns only datasets published on or before the specified date. Inclusive. |
publishedAfter |
date |
MM/DD/YYYY |
Returns only datasets published on or after the specified date. Inclusive. |
Response codes
| Status | Description |
|---|---|
200 |
Success. File found and data returned. |
204 |
No Content. No data is returned. |
400 |
Bad Request. Request is malformed, incorrectly sent, or has exceeded size byte limit of 25 MB. |
404 |
File not found. |
429 |
Quota and/or Throttle Rate limit reached. Request denied. |
500 |
Internal Server Error. Error has occurred on the server. |
Endpoints
Use the list endpoint to discover files, then loop to download.
Download the FWD Data Dictionary for detailed definitions of all fields used in the Employment, Accessions, and Separations datasets.
Download FWD Data Dictionary
GET List available files
Returns metadata for all available files.
| Endpoint | Dataset | Type | File size / month |
|---|---|---|---|
GET /api/v1/files/employment |
Employment |
JSON |
75 KiB |
GET /api/v1/files/accessions |
Accessions |
JSON |
75 KiB |
GET /api/v1/files/separations |
Separations |
JSON |
75 KiB |
Example
The code examples below return the metadata for the most recent Separations files loaded on the site.
library(httr2)
# Get urls
base_url <- "https://data.opm.gov/api/v1/files"
list_url<- paste0(base_url, "/separations")
# Get current files
list_payload<- request(list_url) |>
req_url_query(current = TRUE) |>
req_timeout(30) |>
req_perform() |>
resp_body_json()
print(list_payload)
GET Download a file
Streams the files available on the site (as parquet files).
| Endpoint | Dataset | Type | File size / month |
|---|---|---|---|
GET /v1/files/employment/{year}/{month}/{version}/download |
Employment |
Parquet |
26–75 MiB |
GET /v1/files/accessions/{year}/{month}/{version}/download |
Accessions |
Parquet |
60 KiB–1 MiB |
GET /v1/files/separations/{year}/{month}/{version}/download |
Separations |
Parquet |
100 KiB–4 MiB |
Example
The code examples below return the current version of files from the Employment dataset for the month of September from 2020 to 2026.
library(httr2)
# Specify starting year, month and dataset
year <- "2020"
month <- "09"
dataset <- "employment"
# Get urls
base_url <- "https://data.opm.gov/api/v1/files"
list_url <- paste0(base_url, "/", dataset)
# Create output directory
output_dir <- "fwd_downloads"
if (!dir.exists(output_dir)) {
dir.create(output_dir, recursive = TRUE)
}
# Get current files
list_payload <- request(list_url) |>
req_url_query(current = TRUE, month = month) |>
req_timeout(30) |>
req_perform() |>
resp_body_json()
# Get files after specified year and month
filtered_list <- Filter(
function(x) as.numeric(x$year) >= as.numeric(year),
list_payload
)
# Download the files
for (file in filtered_list) {
file_name <- paste0(file$filename, ".parquet")
output_path <- file.path(output_dir, file_name)
download_url <- paste0(
base_url, "/", dataset, "/",
file$year, "/",
file$month, "/",
file$version, "/download"
)
download_response <- request(download_url) |>
req_timeout(120) |>
req_perform(path = output_path)
cat(sprintf("Downloaded file to %s\n", output_path))
}
) or https:// means you’ve safely connected to the .gov