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.
GET /api/historicjoa/announcementtext
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.
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:
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.
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" }
{ "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" }
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.
{ "paging": { "metadata": { "totalCount": 20597, "pageSize": 1000, "continuationToken": "WMwzNNcOmf1Uau6HUM03Nw%3D%3D" }, "next": "/api/historicjoa/announcementtext?continuationtoken=WMwzNNcOmf1Uau6HUM03Nw%3D%3D&hiringagencycodes=VALA" } }
{ "paging": { "metadata": { "totalCount": 19597, "pageSize": 1000, "continuationToken": "o0JDwdUrm%2FcbWX0b%2FSEYlA%3D%3D" }, "next": "/api/historicjoa/announcementtext?continuationtoken=o0JDwdUrm%2FcbWX0b%2FSEYlA%3D%3D&hiringagencycodes=VALA" } }
If the API returns a response without a continuationtoken, it means all available data has been retrieved
As a USAJOBS API Consumer, you agree to the following terms and conditions, and any policies, guidelines or amendments thereto that may be presented to you from time to time (collectively, the "Terms of Service") governing use of the USAJOBS API service. The Office of Personnel Management USAJOBS Program Office (OPM USAJOBS) may update the Terms of Service, and will notify you by email to accept the most current version of the Terms of Service. Inquiries should be sent via email: access@usajobs.gov
The API is described on the USAJOBS Developer site available here: https://developer.usajobs.gov. in consideration of your use of the api, you may be required to provide current, accurate identification, contact, and other information as part of the registration process and />or continued use of the services offered by OPM USAJOBS and its representatives. You are responsible for maintaining the confidentiality of your USAJOBS API key, and are responsible for all activities that occur under your account. You agree to immediately notify USAJOBS of any unauthorized use of your API key or any other breach of security. USAJOBS cannot and will not be liable for any loss or damage arising from your failure to comply with this.
USAJOBS reserves the right to refuse service to anyone at any time found to be in violation of this and subsequent sections. USAJOBS reserves the right at any time and from time to time to modify or discontinue, temporarily or permanently, the API (or any part thereof) with or without notice. You agree that USAJOBS shall not be liable to you or to any third party for any modification, suspension or discontinuance of USAJOBS services.
Data provided to you through the API is for the explicit use of the requesting company identified on the USAJOBS Program Office API Registration Form. No other use of the data provided is permitted without prior approval, in writing, from OPM USAJOBS. You may not rent, lease, loan, sell, trade or create derivative works of USAJOBS API services and data, in whole or in part.
The data provided through the API is restricted to publicly available information found in a USAJOBS JOA, contains no Personally-Identifiable Information (PII) of USAJOBS system users other than publicly disclosed contact information within the JOA, and may not exceed the Controlled Unclassified Information (CUI) designation.
You agree that you are responsible for your own conduct and the proper handling of any information made available while using the API and for any consequences thereof. You agree to use the API only for purposes that are legal, proper and in accordance with these Terms of Service and any applicable policies or guidelines. By way of example, and not as a limitation, you agree that when using the USAJOBS API, you will not:
You understand and agree that USAJOBS shall have the right (but not the obligation) in its sole discretion to deny access to those users that are found to be in violation of these Terms of Service.
By using the USAJOBS API service, you acknowledge and agree that OPM USAJOBS may access, preserve, and disclose your API account information or information about account activity if required to do so by law or in a good faith belief that such access preservation or disclosure is reasonably necessary to: (a) satisfy any applicable law, regulation, legal process or governmental request, (b) enforce this Terms of Service, including investigation of potential violations hereof, (c) detect, prevent, or otherwise address fraud, security or technical issues, (d) respond to JOA Consumer support requests, or (e) protect the rights, property or safety of USAJOBS, its users and the public. USAJOBS will not be responsible or liable for the exercise or non- exercise of its rights under the Terms of Service.
You understand that the technical processing and transmission of USAJOBS services, including API information, may involve (a) transmissions over various networks; and (b) changes to conform and adapt to technical requirements of connecting networks or devices.
You agree that OPM USAJOBS has no responsibility or liability for the deletion or failure to store any API service data. You acknowledge that OPM USAJOBS retains the right, at its sole discretion, to create limits at any time with or without notice on the number of API transactions the API Consumer may initiate, the size of API data files received, or the amount of storage space used.
You may cancel your use of the API with or without cause at any time by providing notice to USAJOBS at access@usajobs.gov; provided, however, that a terminated account may continue to exist until processed for removal and deletion under standard account management procedures. USAJOBS may at any time and for any reason, including a period of account inactivity, terminate your access. In the event of termination, your API key will be disabled and you may not be granted access to your API information.
API data may include links to World Wide Web sites or resources external to the USAJOBS information system. You acknowledge and agree that OPM is not responsible for the availability of such external sites or resources, and does not endorse and is not responsible or liable for any content available from such sites or resources, or your use or reliance on or through these resources.
You agree to hold harmless and indemnify USAJOBS, and its subsidiaries, affiliates, officers, agents, and employees, from and against any third party claim arising from or in any way related to your use of the API or violation of these Terms of Service including any liability or expense arising from all claims, losses, damages (actual and consequential), suits, judgments, litigation costs and attorneys' fees, of every kind and nature. In such a case, USAJOBS will provide you with written notice of such claim, suit or action.
You expressly understand and agree that USAJOBS shall not be liable to you for any direct, indirect, incidental, special, consequential or exemplary damages resulting from: (i) the use or the inability to use the API; (ii) the cost of procurement of substitute goods and services resulting from any goods, data, information or services purchased or obtained or messages received or transactions entered into through or from the API; (iii) unauthorized access to or alteration of your transmissions or data; (iv) statements or conduct of any third party utilizing the API; or (v) any other matter relating to OPM USAJOBS.
Any material downloaded or otherwise obtained through the use of the API is done at your own discretion and risk and that you will be solely responsible for any damage to your computer system or loss of data that results from the download of any such material.
No advice or information, whether oral or written, obtained by you from OPM shall create any warranty.
You agree that there shall be no third party beneficiaries to the Terms of Service.
The Terms of Service constitute the entire agreement between you and OPM governing your use of the USAJOBS API service as an API Consumer. You also may be subject to additional terms and conditions that may apply when you use other USAJOBS services.
The failure of USAJOBS to exercise or enforce any right or provision of the Terms of Service shall not constitute a waiver of such right or provision.
An official website of the United States Government
An official website of the United States Government