Job Opportunity Announcements (JOA)


The REST based API is designed to support lightweight JOA content consumption by consumers. It is anticipated that this API will be leveraged by Commercial Job Boards, Mobile Applications and Social Media sites who desire to provide employment opportunities on their site. Typically in these commercial venues, the breadth of data presented to a user (job seeker) is much smaller than the detailed content provided on USAJOBS, as required by law.

Technical Overview

  1. The REST API does not require authentication and is open to all consumers.
  2. The data presented back through the API is for Public Job Opportunities. These jobs are open to the public.
  3. The API will provide a maximum of 5,000 job results per query. The API will leverage paging to return the results in groups of 250 JOAs per page.

Technical Implementation Detail

To instantiate the REST API, an HTTPS GET will be used. All interactions with USAJOBS are via HTTPS.

  1. It will require that you provide the base URL:
    With the base URL, you will append the query parameters to drive the results outcome desired. In the below example, the query parameter for occupational series is included to select all jobs for Information Technology Management.

  2. Request Header
    • Host:
    • User-Agent: your@email.address
    • Within the Request Header, you also need to identify which format you desire. JSON is the default value if not specified:
      1. Accept: application/json
      2. Accept: application/xml
  1. As noted in the previous Tab (Instantiating the API), the query parameters are appended to the URL to drive the specific results desired. Each consumer can leverage any combination of these parameters. All parameters support multiple search values which must be separated by a colon. The query parameters are:

    Data Element Description
    OrganizationID Example AF for all Air Force or HE39 for CDC
    Title This is the job title - e.g. IT Specialist, Psychologist, etc. The title search will be treated as contains and will select all job announcements where the job title contains the value provided.

    The following query will return all job announcements with "psychologist" or a synonym of psychologist in the title -
    Series This is a 4 digit number which the Federal government uses to categorize and define jobs. For a complete list of series, please visit List by Occupational Series. You may also obtain the list of series used by USAJOBS at For more information on what a series is, please visit
    MinSalary Jobs are placed in salary buckets: $0-$24,999, $25,000-$49,999, $50,000-$74,999, $75,000-$99,999, $100,000-$124,999, $125,000-$149,999, $150,000-$174,999, $175,000-$199,999 and $200,000 or greater. So a search with a minimum salary of $15,500 will return jobs with a minimum salary in the $0-$24,999 range.
    MaxSalary Jobs are placed in salary buckets: $0-$24,999, $25,000-$49,999, $50,000-$74,999, $75,000-$99,999, $100,000-$124,999, $125,000-$149,999, $150,000-$174,999, $175,000-$199,999 and $200,000 or greater. So a search with a maximum salary of $72,000 will return jobs with a maximum salary in the $50,000-$74,999 range.

    For example, combining MinSalary and MaxSalary, the folling query - - will return all job announcements where the starting and/or ending salary are between $25,000 and $99,999.
    LocationID The location id is either a valid USPS Zip Code or a 9-digit Duty Location Code. NOTE: Use of Location ID will only return job announcements posted to that specific location id. Separate multiple location ids with a semicolon.

    You may download a zip file of the currently supported location ids from the USAJOBS schemas site:
    LocationName This is the city or military installation name. LocationName simplifies location based search as the user does not need to know or account for each and every code. As example, Washington DC has over 200 zip codes and 7 different Duty Station codes. If the consumer wishes to find all job announcements posted to Washington DC, they should use LocationName instead of LocationID. LocationName will search for all location codes and ZIP codes that have that specific description.

    For example, to find all job announcements in Washington, DC, use,%20District%20of%20Columbia.
    To find all job announcements in Atlanta, GA use,%20Georgia.
    Country Country name - e.g. United States. The list of countries used by USAJOBS is at Use the contents of the Value element for the country name.

    For example, to find all job announcements in Germany, use
    CountrySubDivision When searching in the United States, this is the state name. Currently, country subdivisions for foreign countries are not supported in a job search. The list of country subdivisions is at

    For example, to find all job announcements in Washington state, use
    SES Yes/No – Default is No. SES stands for Senior Executive Service which is comprised of the men and women charged with leading the continuing transformation of government. When specifying "Yes" for SES, only those jobs which are considered an SES position will be returned. For more information on what SES, go to

    To find all SES positions, use
    GradeLow Must be 01 through 15. This is the starting grade for the job. (Caution: Fed speak ahead but it cannot be helped.) The grade along with series is used by the Federal government to categorize and define jobs. For more information on what series and grade are, please visit

    However, grade is also used to define salary. USAJOBS search uses grades for the General Schedule (GS) pay plan ( For jobs that use a different pay plan than the GS schedule, USAJOBS will derive the corresponding grade by using the minimum and maximum salary and the wages for the GS schedule for the Rest of the United States (for 2014, see http />/

    For federal employees, especially those who have a GS pay plan, searching by grade is extremely useful since they would already know which grades they are or qualify for. However, for non-GS employees, searching by salary is much simpler.
    GradeHigh Must be 01 through 15. This is the ending grade for the job. See grade low for more information.

    To search for jobs that have a grade of 07 or 09, use
    Keyword Optional. Keyword will search for all of the words specified (or synonyms of the word) through the job announcement.
    Student Yes/No – Default is No. When the Student query parameter is used and the value is set to Yes, only job announcements targeted for students will be included. The value of "no" (or not providing a query parameter of Student) does not exclude student jobs from the search. "No" tells search to not return student jobs exclusively.
    Page The Page query parameter is used to specify which page results are desired. The API can provide up to 5,000 results for a given query. Within those results, the Page parameter is leveraged to return the specific results for that page. The Page parameter ensures that results are returned quickly and do not impede performance with the consumer's presentation layer.
    NumberOfJobs The NumberOfJobs query parameter is used to specify the number of jobs to return per query. The maximum value is 250. The default value is 25. This will directly affect the total number of jobs return value and the page parameter. So it should be specified on every call if not using the default value.
  2. Here is an example of a query with multiple paramters put together:

    In this example, the API Query would return job announcements that belong to DoD and is located in Washington, DC for the 2nd page of the results.
PostChannelID (PCI) is used within USAJOBS to identify the source from which a job seeker originates.

  • The default PostChannelID of RESTAPI will be generated in the ApplyOnlineURL node within the data returned for each JOA.
  • If you have previously requested and been provided a PCI, you would simply replace RESTAPI with your PCI. Why is this important? As USAJOBS runs sourcing analysis reports, it identifies that the job seeker originated at a specific JOA consumers site. Over time, this provides not only USAJOBS, but also the agencies clear transparency to venues that attract the Federal Job Seekers.
  • If you would like to have a PostChannelID established for Sourcing Analysis, please submit your request to We will need your Company Name, Site Name, and technical contact information.
As noted previously, the REST API can render results to you in both JSON and XML format. The following examples are provided:

  1. JSON Sample Output:

    {"TotalJobs":"1","JobData":[{"DocumentID":"12951900","JobTitle":"Information Technology Specialist (Systems Analysis), GS-2210-12/13", "OrganizationName":"Department Of Health And Human Services", "AgencySubElement":"Office of the Secretary of Health and Human Services", "SalaryMin":"$74,872.00","SalaryMax":"$115,742.00","SalaryBasis":"Per Year", "StartDate":"2/16/2013","EndDate":"12/31/2013", "WhoMayApplyText":"United States Citizens","PayPlan":"GS","Series":"2210", "Grade":"12/13","WorkType":"Career/Career Conditional", "WorkSchedule":"Full Time","Locations":"Washington DC Metro Area, District of Columbia","AnnouncementNumber":"HHS-OS-DE-11-440116", "JobSummary":"This position is located in the Department of Health and Human Services (HHS), Office of the Secretary (OS), Assistant Secretary for Administration (ASA), Office of Human Resources, Enterprise Systems Division in Washington, D.C. This vacancy is also being announced concurrently with vacancy announc", "ApplyOnlineURL":""},],"Pages":"1"}

  2. XML Sample Output:

As defined in both of the examples provided, the ApplyOnlineURL node will redirect a job seeker from the consumer’s site to USAJOBS. The job seeker can review the JOA in more detail or apply for the job opportunity. If you have a PostChannelID established, please replace “RESTAPI” with your specific PostChannelID.
For questions or assistance in leveraging the API, please contact USAJOBS at When you submit a question or request to this email address, a ticket will automatically be opened and routed to the resources that can best assist.