Getting started overview

Integrating with the USAJOBS Data API enables developers to access and display federal job listings directly within their own applications. The entire service, from account creation to API usage, is free of charge. This guide outlines the process of setting up an account, obtaining the necessary authentication credentials, and executing an initial API call to confirm your setup.

The USAJOBS API generally returns data in either JSON or XML format, supporting a range of applications from web dashboards to mobile apps. Understanding the basic API structure and authentication methods is foundational for any integration.

Quick Reference Steps

The table below summarizes the key steps to get started with the USAJOBS API:

Step What to Do Where
1. Create Account Register for a USAJOBS account. USAJOBS Account Creation page
2. Obtain API Keys Request a Client Share ID and Host from the USAJOBS Data Portal. USAJOBS Data API reference
3. Make First Request Construct an API call using your credentials. Your preferred development environment
4. Parse Response Process the JSON or XML data returned by the API. Your application code

Create an account and get keys

Accessing the USAJOBS API requires specific credentials that identify your application. While general browsing of USAJOBS doesn't require an account, developer access to the API does. The process involves creating a user account and then applying for API access through the Data Portal.

1. Create a USAJOBS Account

Before you can obtain API keys, you must have an active USAJOBS user account. This account will serve as your identifier for requesting API access.

  1. Navigate to the USAJOBS website's account creation page.
  2. Follow the on-screen instructions to register for a new account. This typically involves providing an email address, creating a password, and agreeing to terms of service.
  3. Verify your email address if prompted, to activate your account.

2. Obtain API Keys (Client Share ID and Host)

After creating your USAJOBS account, the next step is to request the API credentials. The USAJOBS API uses a combination of a Client Share ID and a Host header for authentication, rather than a single API key typically seen in other services like the Cloudflare API getting started guide.

  1. Visit the USAJOBS Data Portal.
  2. Look for instructions on how to request API access. This may involve filling out a form or contacting the USAJOBS data team. The portal will specify the exact steps to receive your unique Client Share ID and the Host value you must include in your API requests.
  3. Record your Client Share ID and Host value securely. These are critical for all subsequent API calls.

Your first request

Once you have your Client Share ID and Host credentials, you can make your first API call. This example demonstrates a basic request to retrieve job listings.

API Endpoint Structure

The base URL for the USAJOBS API is typically https://data.usajobs.gov/api/Search, with various parameters available to filter search results. Consult the USAJOBS API reference documentation for a complete list of available endpoints and parameters.

Example Request (cURL)

This cURL example demonstrates how to search for jobs tagged with "developer". Replace YOUR_CLIENT_SHARE_ID with your actual Client Share ID and ensure the Host header matches the value provided to you.

curl -X GET \
  'https://data.usajobs.gov/api/Search?Keyword=developer' \
  -H 'Host: data.usajobs.gov' \
  -H 'User-Agent: YOUR_EMAIL_ADDRESS' \
  -H 'ClientShareKey: YOUR_CLIENT_SHARE_ID' \
  -H 'Accept: application/json'

In this request:

  • -X GET specifies the HTTP GET method.
  • 'https://data.usajobs.gov/api/Search?Keyword=developer' is the target URL with a search parameter.
  • -H 'Host: data.usajobs.gov' is a required header.
  • -H 'User-Agent: YOUR_EMAIL_ADDRESS' is a custom header where you should provide your email address for identification. This is a common practice for public APIs to understand usage patterns and contact developers if issues arise, similar to how Twilio's API documentation notes the importance of user identification for support.
  • -H 'ClientShareKey: YOUR_CLIENT_SHARE_ID' is your unique API key.
  • -H 'Accept: application/json' requests the response in JSON format.

Interpreting the Response

A successful request will return a JSON object containing an array of job listings. The structure of this JSON can be complex, including details such as job title, agency, location, and application dates. Review the API reference documentation for a full schema definition.

Example of a simplified successful JSON response snippet:

{
  "SearchResult": {
    "SearchResultItems": [
      {
        "MatchedObjectDescriptor": {
          "PositionID": "1234567",
          "PositionTitle": "Software Developer",
          "DepartmentName": "Department of Defense",
          "OrganizationName": "Defense Information Systems Agency",
          "Locations": [
            "Fort Meade, Maryland"
          ],
          "ApplyEndDate": "2026-06-30",
          "Url": "https://www.usajobs.gov/job/1234567"
        }
      }
      // ... more job listings
    ]
  }
}

Errors will typically return an HTTP status code greater than or equal to 400 and an error message within the JSON response, detailing the issue.

Common next steps

After successfully making your first API call, you can explore more advanced features and integrate the data into your applications:

  • Advanced Search Parameters: Utilize additional query parameters such as Location, JobCategory, SalaryMinimum, and TravelPercentage to refine your job searches. The full list of parameters is available in the USAJOBS API documentation.
  • Pagination: Implement pagination to handle large result sets efficiently. The API allows you to specify the number of results per page and control the offset for fetching subsequent pages, preventing excessive data transfer in a single request.
  • Error Handling: Develop robust error handling in your application to manage network issues, invalid parameters, or authentication failures. This ensures a stable user experience.
  • Data Storage and Caching: For frequently accessed data, consider implementing caching strategies to reduce the number of API calls and improve performance. Be mindful of the API's usage policies regarding data freshness.
  • Integration with Front-end: Display the retrieved job data in a user-friendly format on your website or application. This might involve using a front-end framework like React, Angular, or Vue.js to render the job listings dynamically.
  • Security Best Practices: Always store your Client Share ID and Host values securely, ideally in environment variables or a secrets management service, and avoid hardcoding them directly into your application's source code, especially in client-side applications.

Troubleshooting the first call

If your initial API call does not return the expected results, consider these common troubleshooting steps:

  • Check Credentials: Double-check that your Client Share ID and Host header values are correct and accurately copied from the USAJOBS Data Portal. Even minor typos can cause authentication failures.
  • Verify Headers: Ensure all required headers (Host, User-Agent, ClientShareKey, Accept) are present and correctly formatted in your request. Missing or malformed headers are frequent causes of issues.
  • Review URL and Parameters: Confirm that the API endpoint URL is correct and any query parameters are properly encoded and adhere to the syntax specified in the USAJOBS API reference. Incorrect parameter names or values can lead to empty or erroneous responses.
  • Inspect HTTP Status Codes: The HTTP status code returned in the response can provide immediate clues. Common error codes include:
    • 400 Bad Request: Often indicates an issue with your request parameters or format.
    • 401 Unauthorized: Typically means your ClientShareKey is incorrect or missing.
    • 403 Forbidden: Your credentials might be valid, but you lack permission for the requested resource, or there's an IP restriction.
    • 404 Not Found: The requested endpoint or resource does not exist.
    • 5xx Server Error: Indicates an issue on the USAJOBS server side. If this persists, consult the USAJOBS help documentation for service status updates.
  • Examine Response Body: Even with an error status code, the response body often contains a detailed error message that can pinpoint the exact problem. Always parse the response body, even when expecting an error, to extract this diagnostic information.
  • Consult Documentation: Refer back to the official USAJOBS API documentation for the most up-to-date information on endpoints, parameters, and authentication requirements. Changes to the API can occur, and the documentation is the primary source of truth.
  • Firewall/Network Issues: If you are working within a corporate network, ensure that no firewalls or network policies are blocking outgoing requests to data.usajobs.gov.