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

The Announcement Text API is designed to deliver long text 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/announcementtext

Authorization

The Announcement Text 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: 
 {  
        "usajobsControlNumber": 27295400,
        "positionOpenDate": "2024-03-22",
        "positionCloseDate": "2024-04-01",
        "hiringAgencyCode": "ARAT",
        "hiringDepartmentCode": "AR",
        "positionSeries": "0830",
        "announcementNumber": "CHAG237111257022",
        "summary": "...",
        "duties": "...",
        "hiringPathExplanation": "See Who May Apply in the Qualifications section for more information on who is eligible to apply for this position.",
        "majorDutiesList": null,
        "requirementsConditionsOfEmployment": "...",
        "requirementsQualifications": "...",
        "requirementsEducation": "...",
        "requiredStandardDocuments": null,
        "requiredDocuments": "...",
        "howToApply": "...",
        "howToApplyNextSteps": "...",
        "requirements": null,
        "evaluations": "...",
        "benefitsURL": "https://www.usajobs.gov/Help/working-in-government/benefits/",
        "benefits": null,
        "otherInformation": "...",
        "appointmentTypeOverride": null,
        "positionScheduleOverride": null,
        "exclusiveClarificationText": null,
        "videoURL": "https://www.youtube.com/embed?v=J7dNEgo7Nxk"
}

Name	Description	Type
UsajobsControlNumber	The USAJOBS provided announcement control number.	integer
PositionOpenDate	The calendar date that an announcement opened.	date
PositionCloseDate	The calendar date that an announcement closed.	date
HiringAgencyCode	The code of the agency in which the position is located.	string
HiringDepartmentCode	The parent code of the department in which the position is located.	integer
PositionSeries	The occupational code identifying the position as indicated on the position description associated with a vacancy.	string
AnnouncementNumber	Identification number assigned to the job announcement by the TAS (also known as Requisition Number for some vendors).	string
Summary	Overall description of the job being posted to USAJOBS.	string
Duties	The name of the department in which the position is located.	string
HiringPathExplanation	Additional explanation of the hiring paths on the position.	string
MajorDutiesList	Expected activities associated wtith the position being published to USAJOBS.	string
RequirementsConditionsOfEmployment	Describes Job Requirements that are expected.	string
RequirementsQualifications	Description of the items used to qualify and evaluate applicants applying to the position being published to USAJOBS.	string
RequirementsEducation	Education requirements associated with the position being posted to USAJOBS.	string
RequiredStandardDocuments	Provides for Standard codes and description of Required Documents used by all Agencies.	string
RequiredDocuments	Explanation of the documents the agency requires of applicants when applying to this position.	string
HowToApply	Text explaining steps prospective applicants can take apply for the position being reviewed.	string
HowToApplyNextSteps	Description of what will occur after application is sent.	string
Requirements	Describes Job Requirements that are expected.	string
Evaluations	Describes the Candidate Evaluation Criteria for the JOA.	string
BenefitsURL	URL for Agency Benefits Page.	string
Benefits	Description of employee benefits provided with the position.	string
OtherInformation	Any additional information the agency wishes to include specific to the postion.	string
AppointmentTypeOverride	Additional description of appointment type.	string
PositionScheduleOverride	Additional description of position schedule.	string
ExclusiveClarificationText	Text explaining exclusive job posting.	string
VideoURL	Text allowing agency to provide a link to videos.	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/announcementtext?continuationtoken=WMwzNNcOmf1Uau6HUM03Nw%3D%3D&hiringagencycodes=VALA"
  }
}

Fetch Next Page Using Continuation Token:

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


{
  "paging": {
    "metadata": {
      "totalCount": 19597,
      "pageSize": 1000,
      "continuationToken": "o0JDwdUrm%2FcbWX0b%2FSEYlA%3D%3D"
    },
    "next": "/api/historicjoa/announcementtext?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/AnnouncementText

Page content