Skip to page navigation
U.S. flag

An official website of the United States government

Official websites use .gov
A .gov website belongs to an official government organization in the United States.

Secure .gov websites use HTTPS
A lock ( ) or https:// means you’ve safely connected to the .gov website. Share sensitive information only on official, secure websites.

OPM.gov / Agency Services / Technology Systems / USA Performance / API Documentation /
Skip to main content

USA Performance: API Documentation

Getting Started with the API

At USA Performance, we prioritize integration, security, and the protection of information. To support organizational integration, we incorporate the following measures:

  • Secure Connection: All integration communication is conducted over HTTPS using TLS. The USA Performance Program Office and the OPM OCIO team will collaborate with each integration partner to ensure the appropriate version is utilized.
  • IP Address Validation: We validate IP addresses to ensure secure access.
  • API Key: Each agency or organization will have a unique API key for secure access, which is value for 180 days.

 API Endpoints and Methods:

The USA Performance API provides the following endpoints and methods:

  • /health (GET method)
  • /organizations (GET, POST, PUT methods)
  • /report/activities/{activityDate} (GET method)
  • /users (GET, POST, PUT methods)
  • /users/rating-assignments (GET, POST methods)
  • /users/agency-identifier-assignments (PUT method)
  • /users/ssn-assignments (PUT method)
  • /users/rating-cycle-groups-assignments (PUT method)
  • /users/slst-summary-ratings (GET method) 

Technical Specifications

For detailed information about each API endpoint, including the parameters you can use and the types of responses you can expect, please visit:

https://dataconnect2-usapdemo.opm.gov/swagger/index.html

API Access

To make calls to the API, use the appropriate URL for the environment in which your application is hosted.

Demo: https://dataconnect2-usapdemo.opm.gov

Production: https://dataconnect2-usaperformance.opm.gov

Obtaining your API Key

To begin using the API, you must first obtain an API key, which serves as your authentication credential. Your account manager will work closely with the USA Performance development team to generate an API key specifically for your organization. Additionally, you will need to acquire an Agency Code from your agency’s’ Administrator.

Once you have both the API Key and Agency Code, connecting to the USA Performance API is straightforward. For each API request, simply include your API Key in the HTTP header named API-key and the Agency Code in the head names AgencyCode. Refer to the examples provided for further details.

Fetching Organization Data

To get started with the API, follow these simple steps:

  1. Select an API Method: Click on an API method to view its reference documentation. For example, you can click on GET /organizations.
  2. Try It Out: Click the “Try it out” button to display a form where you can enter values and test the request. (Note: This option is only available for GET methods.)
  3. Enter Credentials: In the HTTP request header, input your API Key and Agency Code.
    1. Use the header name API-key and provide the value given by your account manager.
    2. User the header name AgencyCode and provide the value given by your agency administrator.
  4. Execute the Request: Click the “Execute” button to run the API request.
  5. When you execute an API request, the display will show the following information:
    1. Request URL: This shows the URL that was executed.
    2. Request Headers: This contains messages about the success or failure of the request.
    3. Request Body: This contains a JSON array of results. For example, an array of Organization objects. Other API requests use the User object.
    4. Curl Command Line: This contains a form of the request you copy and paste to execute at the command line or in script. For example:

      curl -X 'GET' \ 'https://dataconnect2-usapuat.opm.gov/organizations' \ -H 'accept: application/json' \ -H 'API-key: <API Key>' \ -H 'AgencyCode: <Agency Code>'

  6. Each organization object in the returned array is identified by an OrganizationApiId

Creating Organizations

To create your organization structure in a single API call, follow these steps:

  1. Make a POST request to the /organizations endpoint with a JSON formatted request body.
    1. Note: The ProcessingOrder parameter is used to ensure that parent organizations are created before their subordinate organizations.

  2. Enter your API Key and Agency Code in the HTTP request header.
    1. Use the header name API-key and supply the value provided by your account manager.
    2. User the header name AgencyCode and supply the value provided by your agency administrator.
  3. The display shows results as follows:
    1. Request URL: Shows what executed.
    2. Request Headers: Contains messages about the success or failure of the request.
    3. Request Body: Contains a JSON array of results, in this case an array of Organization objects. Other API requests use the User object.
    4. Curl Command Line: Contains a form of the request that you can copy and paste to execute at the command line or in script. Example

      curl -X 'POST' \ 'https://dataconnect2-usapuat.opm.gov/organizations' \ -H 'accept: application/json' \ -H 'API-key: <API Key>' \ -H 'AgencyCode: <Agency Code>'

  4. Each organization object that was not successfully created is identified in the returned array with an error message.

Rate Limit and Throttling

To ensure the system remains stable and resources are distributed fairly, the API enforces rate limits and quotas on all requests.

For each environment (Stage & Production), the API allows a maximum of 30 concurrent requests. If this limit is exceeded, the next 5 requests will be queued for processing. After that, any additional requests will receive an error code 429.

Additionally, each API Key has its own rate limit. If more than 2 requests are processed within a 10-second window, subsequent requests will be delayed.

Each API response includes headers that inform users of their current status regarding the rate limit and quota.

Quota Headers 

Sample Value 

Definition 

X-RateLimit-Limit 

2 

The request limit per specified unit of time. (minute) 

X-RateLimit-Remaining 

1

The remaining number of requests that API consumers can send in the current time window. 

X-RateLimit-Reset 

10

The number of seconds until the next quota reset. Sent only when quota remains. 

 

Status Codes and Error Handling

The API uses HTTP status codes to indicate the result of a client request. Here are the main categories of these status codes, although not all are currently in use on the platform. 

  • 1xx: Informational-Communicates transfer protocol-level information.
  • 2xx: Success-The client’s request was accepted successfully. For example:
    • A successful PUT (update) request for a data class on the platform will return a 200 code.
    • A successful POST (create) request will return the 201 status code.
  • 3xx: Redirection-The client must take additional action to complete the request.
  • 4xx: Client Error-This type of error status code indicates a client error. For example, an unsuccessful request on the platform may return the 400 status code: "Bad Request due to an invalid format or because the requested name is already in use".
  • 5xx: Server Error-This type of error status code indicates a server error.

If an API call fails, the server will return a standard error code instead of a 200 (OK) or 201 (CREATED) response.

Control Panel