API Reference - GET /api/HistoricJoa

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