The USAJOBS developers' site provides guides for the search API, code lists, schemas and other needs.

The Historic JOAs API is designed to deliver smaller fields for all current and past job postings to USAJOBS filtered by a set of standard parameters. This endpoint is intended to deliver a bulk data set to be parsed by the consumer.

Resource

GET /api/historicjoa

Authorization

The Historic JOAs endpoint does not require authorization or authentication. The data returned by this endpoint is publicly consumable.

The endpoint will also return a payload providing pagination details including links to previous and next paged data as well as metadata on record count, page size, current page and total pages.

Query Parameters

The query parameters are appended to the URL to drive the specific results desired. Each consumer can leverage any combination of these parameters. The query parameters are:

Parameter Name	Description
HiringAgencyCodes	The code of the agency in which the position is located.
HiringDepartmentCodes	The code of the department in which the position is located.
PositionSeries	The occupational code identifying the position as indicated on the position description associated with a vacancy.
AnnouncementNumbers	The unique identifying number associated with an announcement.
USAJOBSControlNumbers	The USAJOBS provided announcement control number.
StartPositionOpenDate	The beginning of the calendar date range when an announcement opened.
EndPositionOpenDate	The end of the calendar date range when an announcement opened.
StartPositionCloseDate	The beginning of the calendar date range when an announcement closed.
EndPositionCloseDate	The end of the calendar date range when an announcement closed.

Response

JSON: 
{
  "paging": {
    "metadata": {
      "totalCount": 20597,
      "pageSize": 1000,
      "continuationToken": "WMwzNNcOmf1Uau6HUM03Nw%3D%3D"
    },
    "next": "/api/historicjoa?continuationtoken=WMwzNNcOmf1Uau6HUM03Nw%3D%3D&hiringagencycodes=VALA"
  },
  "data": [
    {
      "usajobsControlNumber": 314527500,
      "hiringAgencyCode": "VALA",
      "hiringAgencyName": "Veterans Benefits Administration",
      "hiringDepartmentCode": "VA",
      "hiringDepartmentName": "Department of Veterans Affairs",
      "agencyLevel": 2,
      "agencyLevelSort": "Department of Veterans Affairs\\Veterans Benefits Administration",
      "appointmentType": "Agency Employees Only",
      "workSchedule": "Full-time",
      "payScale": "GS",
      "salaryType": "Per Year",
      "vendor": "USASTAFFING",
      "travelRequirement": "Not required",
      "teleworkEligible": "N",
      "serviceType": null,
      "securityClearanceRequired": "N",
      "securityClearance": "Not Required",
      "whoMayApply": "United States Citizens",
      "announcementClosingTypeCode": null,
      "announcementClosingTypeDescription": null,
      "positionOpenDate": "2018-02-15",
      "positionCloseDate": "2018-02-15",
      "positionExpireDate": null,
      "announcementNumber": "317-12-286-RU646796",
      "hiringSubelementName": null,
      "positionTitle": "Rating Veterans Service Representative",
      "minimumGrade": "10",
      "maximumGrade": "10",
      "promotionPotential": "12",
      "minimumSalary": 0.0,
      "maximumSalary": 0.0,
      "supervisoryStatus": "N",
      "drugTestRequired": "N",
      "relocationExpensesReimbursed": "N",
      "totalOpenings": null,
      "disableAppyOnline": "N",
      "positionOpeningStatus": "Applications under review",
      "hiringPaths": [
        {
          "hiringPath": "The public"
        }
      ],
      "jobCategories": [
        {
          "series": "0996"
        }
      ],
      "positionLocations": [
        {
          "positionLocationCity": "Jackson",
          "positionLocationState": "Mississippi",
          "positionLocationCountry": "United States"
        }
      ]
    }

Name	Description	Type
USAJOBSControlNumber	The USAJOBS provided announcement control number.	integer
HiringAgencyCode	The code of the agency in which the position is located.	string
HiringAgencyName	The name of the agency in which the position is located.	string
HiringDepartmentCode	The parent code of the department in which the position is located.	string
HiringDepartmentName	The name of the department in which the position is located.	string
AgencyLevel	The Agency Level defines the hierarchy of the Agency.	integer
AgencyLevelSort	The Agency Level sort shows the drill path of the Agency.	string
AppointmentType	Identifies the type of appointment (e.g., permanent, temporary, term).	string
WorkSchedule	Identifies the type of work schedule (e.g., full time, part time, intermittent, shift work, job sharing) for the position announced.	string
PayScale	The table or array of pay rates as indicated on the position description associated with a vacancy.	string
SalaryType	The frequency of salary payment. Bi-weekly, Fee Basis, Per Year, etc.	string
Vendor	The Talent Acquisition System (TAS) used to post the position on USAJOBS.gov.	string
TravelRequirement	Description of the travel requirement for the position: Occasional Travel, No Travel, etc.	string
TeleworkEligible	Flag indicating if the position in the vacancy is eligible for telework.	boolean
ServiceType	The Federal government has 3 services that determine how you are hired:Competitive, Excepted and Senior Executive.	string
SecurityClearanceRequired	Flag indicating if a security clearance is required for the position.	boolean
SecurityClearance	Description of the type security clearance required for the request: Not Required, Confidential, Secret, etc.	string
WhoMayApply	Description of the types of candidates that may apply for a job posting: Agency Employees Only, Public, United States Citizens, etc.	string
AnnouncementClosingTypeCode	Code Indicating how the announcement the circumstances that will cause it to close and stop receiving applications.	string
AnnouncementClosingTypeDescription	Field Indicating how the announcement the circumstances that will cause it to close and stop receiving applications: Closing Date, Open Continuous, Applicant Cut-Off, or Closing Time.	string
PositionOpenDate	The calendar date that an announcement opened.	date
PositionCloseDate	The calendar date that an announcement closed.	date
PositionExpireDate	Close date of position, if it is closed early. If this field is populated, this is the actual close date of the position.	date
AnnouncementNumber	The unique identifying number associated with an announcement.	string
HiringSubelementName	The name of the administrative subdivision where the position is located. (manually entered by HR representative).	string
PositionTitle	Official classification title description of the position of the employee associated with a request.	string
MinimumGrade	The pay rate level as indicated on the position description associated with a vacancy.	string
MaximumGrade	The pay rate level as indicated on the position description associated with a vacancy.	string
PromotionPotential	Highest Grade Level for a position.	string
MinimumSalary	The minimum salary associated with the position being posted to USAJOBS.	decimal
MaximumSalary	The maximum salary associated with the position being posted to USAJOBS.	decimal
SupervisoryStatus	Flag indicating if the position in the request is a supervisory position.	boolean
DrugTestRequired	Indicator showing if the position requires a drug test for employment.	boolean
RelocationExpensesReimbursed	Flag indicating if the candidates moving expenses are reimbursable.	boolean
TotalOpenings	The number of position openings associated with the announcement.	string
DisableApplyOnline	Indicates if an individual can start an application for a job announcement within USAJOBS, or must go to another site to start said application.	boolean
PositionOpeningStatus	The hiring status of the position. Indicates if it is currently accepting applications, reviewing applications, has selected an individual to hire, or has been canceled.	string
HiringPaths		Object
HiringPath	The group(s) of job seekers who are eligible to apply for a position (e.g., The Public, Federal Employees - Competitive Service, Veterans).	string
JobCategories		Object
Series	The occupational code identifying the position as indicated on the position description associated with a vacancy.	string
PositionLocations		Object
PositionLocationCity	The city of the location for which a position is announced.	string
PositionLocationState	The state of the location for which a position is announced.	string
PositionLocationCountry	The country of the location for which a position is announced.	string

Pagination

A metadata continuation token is a unique identifier returned by the API that allows users to retrieve the next set of results in a paginated response. Instead of retrieving all data at once, APIs use these tokens to provide a seamless and efficient way to navigate large datasets. The API returns a subset of results along with a continuation token. Users can use the continuation token in the next request to fetch the next page of results. This process continues until no continuation token is returned, indicating the end of the dataset.

Sample Response:


{
  "paging": {
    "metadata": {
      "totalCount": 20597,
      "pageSize": 1000,
      "continuationToken": "WMwzNNcOmf1Uau6HUM03Nw%3D%3D"
    },
    "next": "/api/historicjoa?continuationtoken=WMwzNNcOmf1Uau6HUM03Nw%3D%3D&hiringagencycodes=VALA"
  }
}

Fetch Next Page Using Continuation Token:

GET /api/historicjoa?continuationtoken=o0JDwdUrm%2FcbWX0b%2FSEYlA%3D%3D


{
  "paging": {
    "metadata": {
      "totalCount": 19597,
      "pageSize": 1000,
      "continuationToken": "o0JDwdUrm%2FcbWX0b%2FSEYlA%3D%3D"
    },
    "next": "/api/historicjoa?continuationtoken=o0JDwdUrm%2FcbWX0b%2FSEYlA%3D%3D&hiringagencycodes=VALA"
  } 
}

Repeat Until No Continuation Token

If the API returns a response without a continuationtoken, it means all available data has been retrieved

API Reference - GET /api/HistoricJoa

Page content