API Reference - GET /api/Archive

The Export Archived Jobs endpoint is designed to support historical content consumption by posting agencies and departments. It is anticipated that this API will be leveraged by agencies and departments who desire to obtain historical records on previously offered employment opportunities. This API is not intended to be used by Commercial Job Boards, Mobile Applications or Social Media sites.

Resource

GET /api/Archive

Authorization

API Key Authentication

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

ControlNumber

Issues a search to pull the results with matching control number(s) specified.

NOTE: Multiple values are semicolon delimited.

PostingStartDate

Required parameter if a control number is not supplied.

Issues search to find hits on employment opportunities posted on or after date specified.

PostingEndDate

Required parameter if a control number is not supplied.

Issues search to find hits on employment opportunities posted on or before date specified.

Organization

Issues a search to find jobs for the specified agency using the Agency Subelement Code.
See Code List for a listing of the Organization codes.

The following will get a listing of job announcements from the Department Of The Treasury: https://data.usajobs.gov/api/Archive?Organization=TR

Note: Multiple values are semicolon delimited.

PositionTitle

Issues search to find hits in the title of the job.

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:
https://data.usajobs.gov/api/Archive?PositionTitle=Psychologist

The following query will return all job announcements with "Electrical Engineer" in the title:
https://data.usajobs.gov/api/Archive?PositionTitle=Electrical%20Engineer

NOTE: Multiple values are semicolon delimited.

JobCategoryCode

Issues a search to find hits with the job category series specified.

See Code List for a listing of the Job Category codes.

https://data.usajobs.gov/api/Archive?JobCategoryCode=0830

Note: Multiple values are semicolon delimited.

RemunerationMinimumAmount

Issues search to find hits with the minimum salary specified.

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.

https://data.usajobs.gov/api/Archive?RemunerationMinimumAmount=15000

RemunerationMaximumAmount

Issues search to find hits with the maximum salary specified.

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 following query: https://data.usajobs.gov/api/Archive?RemunerationMinimumAmount=26000&RemunerationMaximumAmount=85000 - will return all job announcements where the starting and/or ending salary are between $25,000 and $99,999.

CityName

Issues a search to find hits with the city specified.

Note: Multiple values are semicolon delimited.

CountrySubDivision

Issues a search to find hits with the state, province or territory name from the country subdivision code specified.

See Code List for a listing of the Country Subdivision codes.

Note: Multiple values are semicolon delimited.

Country

Issues a search to find hits with the country code specified.

See Code List for a listing of the Country codes.

Note: Multiple values are semicolon delimited.

PayGradeHigh

Issues search to find hits with the maximum pay grade specified. Must be 01 through 15. This is the ending 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: https://www.usajobs.gov/Help/faq/pay/series-and-grade/ .

However, grade is also used to define salary. USAJOBS search uses grades for the General Schedule (GS) pay plan (http://www.opm.gov/policy-data-oversight/pay-leave/salaries-wages).

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 //www.opm.gov/policy-data-oversight/pay-leave/salaries-wages/salary-tables/14Tables/html/RUS.aspx).

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.

https://data.usajobs.gov/api/Archive?PayGradeHigh=07

PayGradeLow

Issues search to find hits with the minimum pay grade specified. Must be 01 through 15. This is the beginning grade for the job. See PayGradeHigh for more information.

https://data.usajobs.gov/api/Archive?PayGradeLow=04
https://data.usajobs.gov/api/Archive?PayGradeLow=07&PayGradeHigh=09

Student

Issues a search that will find hits for jobs matching the Student category. Acceptable values are: True or False – Default is False. When the Student query parameter is used and the value is set to True, only job announcements targeted for students will be included.

The value of "False" (or not providing a query parameter of Student) does not exclude student jobs from the search. "False" tells search to not return student jobs exclusively.

To find all Student positions, use:
https://data.usajobs.gov/api/Archive?Student=True

PositionOfferingTypeCode

Issues a search to find jobs within the specified type. This field is also known as Work Type.

Note: Multiple values are semicolon delimited.

PositionScheduleTypeCode

Issues a search to find hits for jobs matching the specified job schedule. This field is also known as work schedule.
Acceptable values for Position Schedule Type Code are:

Value Definition
1 Full-Time
2 Part-Time
3 Shift Work
4 Intermittent
5 Job Sharing
6 Multiple Schedules

https://data.usajobs.gov/api/Archive?PositionSchedule=4

Note: Multiple values are semicolon delimited.

Page

Issues a search to pull the paged results specified.

ResultsPerPage

Issues a search and returns the page size specified. In this example, 25 jobs will be return for the first page.
Acceptable values for this field are numbers, up to 500.

https://data.usajobs.gov/api/Archive?ResultsPerPage=50

Response

JSON:            
{                            
    "LanguageCode": "EN",
    "SearchParameters": {},
    "SearchResult": {
        "SearchResultCount": 1,
        "SearchResultItems": [
            {
                "MatchedObjectId": "337875900",
                "MatchedObjectDescriptor": {
                    "PositionID": "SROC-NWSHRO-13-843376",
                    "PositionTitle": "Park Guide, GS-0090-03/04/05",
                    "PositionURI": "https://www.usajobs.gov:443/GetJob/ViewDetails/337875900",
                    "PositionLocation": [
                        {
                            "LocationName": "Wisdom, Montana",
                            "CountryCode": "United States",
                            "CountrySubDivisionCode": "Montana",
                            "CityName": "Wisdom",
                            "Longitude": 45.6690979,
                            "Latitude": 45.6690979
                        }
                    ],
                    "OrganizationName": "Dept of The Interior",
                    "DepartmentName": "National Park Service",
                    "JobCategory": [
                        {
                            "Name": "Guide",
                            "Code": "0090"
                        }
                    ],
                    "JobGrade": [
                        {
                            "Code": "GS"
                        }
                    ],
                    "PositionSchedule": [
                        {
                            "Name": "Full-Time",
                            "Code": "1"
                        }
                    ],
                    "PositionOfferingType": [
                        {
                            "Name": "Temporary",
                            "Code": "15318"
                        }
                    ],
                    "PositionEmuneration": [
                        {
                            "MinimumRange": "24856.0000",
                            "MaximumRange": "33300.8000",
                            "RateIntervalCode": "Per Hour"
                        }
                    ],
                    "PositionStartDate": "2016-01-01",
                    "PositionEndDate": "2016-05-01",
                    "PublicationStartDate": "2016-01-01",
                    "ApplicationCloseDate": "2016-05-01",
                    "UserArea": {
                        "Details": {
                            "WhoMayApply": {
                                "Name": "US Citizens",
                                "Code": "15514"
                            },
                            "LowGrade": "03",
                            "HighGrade": "05"
                        },
                        "IsRadialSearch": false
                    }
                }
            }
        ]
    }
}      
Name Description Type
LanguageCode Response Langauge String
SearchParameters Query parameters used in search request. Object
SearchResult Object
 SearchResultCount Number of records returned in response object. Integer
 SearchResultItems Array of job opportunity announcement objects that matched search criteria. Array
  MatchedObjectId Control Number Number
  MatchedObjectDescriptor Object
   PositionID Job Announcement Number String
   PositionTitle Title of the job offering. String
   PositionURI URI to view the job offering. String
   PositionLocation Contains values for location name, country, country subdivision, city, latitude and longitude. Object
   OrganizationName Name of the organization or agency offering the position. String
   DepartmentName Name of the department within the organization or agency offering the position. String
   JobCategory List of job category objects that contain values for name and code. See Code List for a list of Job Category codes. Array
   JobGrade List of job grade objects that contains an code value. This field is also known as Pay Plan. See Code List for a list of Pay Plan codes. Array
   PositionSchedule List of position schedule objects that contains values for name and code. See PositionSchedule in paramters above for list of code values. Array
   PositionOfferingType List of position offering type objects that contains values for name and code. See PositionOfferingType in paramters above for list of code values. Array
   PositionRemuneration List of position remuneration objects that contains MinimumRange, MaximumRange and RateIntervalCode. Gives the pay range and frequency. Array
   PositionStartDate The date the job opportunity will be open to applications. Datetime
   PositionEndDate Last date the job opportunity will be posted Datetime
   PublicationStartDate Date the job opportunity is posted Datetime
   ApplicationCloseDate Last date applications will be accepted for the job opportunity Datetime
   UserArea Object
    Details Object
     WhoMayApply Object that contains values for name and code of who may apply to the job opportunity. Object
     LowGrade Lowest potential grade level for the job opportunity. String
     HighGrade Highest potential grade level for the job opportunity. String
    IsRadialSearch Was a radial search preformed. Boolean