Our API Environments

Optum provides two API environments: sandbox and production.

Sandbox

To request for a sandbox testing environment, sign up in the sandbox where you can review and get familiarized with our APIs without signing a contract and without any financial obligation before you use them in your production environment.

📘

NOTE

DO NOT perform load testing or production data testing in the sandbox environment. Please use the sandbox ONLY to view [sample API responses] to HTTP requests using our [predefined values] and to familiarize yourself with our APIs.

To perform load testing and production data testing, we recommend using our APIs in production environment.

1. Request for a sandbox test account by providing the information in the page.
   We will provide the API credentials to access the APIs in the sandbox environment.
2. Log in to your sandbox using your API credentials to access the APIs. Contact your Optum representative if you do not have this information.

API credentials

1. Your API credentials include the following information in an API request.

📘

NOTE

You should have two sets of credentials:

• One for the sandbox — to help you test our APIs before signing a contract
• One for production — provided after signing a contract or after processing a subscription

These credentials are specific and unique to an API environment and to your company.

📘

NOTE

Optum strongly recommends that you carefully guard your API access credentials. Avoid sharing them with others.

After receiving your client_id and client_secret for the sandbox environment, you can try or test our APIs by using one of these options:

• (Preferred method) A third-party application, such as a Postman tool/platform or any tool of your choice
• Our Try It interactive view
• Your own development console

3. Generate bearer token by using your sandbox credentials.

📘

NOTE

For more information, see Security and Authorization.
Use our REST APIs with these HTTP URLs.

• Use our [API URLs and Endpoints] to access our APIs

We have a list of canned test service ID values to use in the sandbox environment [sandbox predefined fields and values] for testing a variety of responses by using a set of secure credentials provided.
At any time, for more information, contact an Optum representative.

• For sandbox API testing, you can edit the request body and send it to the API engine to see what kinds of responses you will get.
• The sandbox provides a set of predefined values that you can apply to see how the API works. It uses simulated values. For successful use of sandbox APIs, you must use ["canned patient" and “canned provider” values for your testing].

👍

IMPORTANT

The sandbox returns canned responses based on the received data. There is no validation check or confirmation of specifically required information. These checks would only occur in the production environment. You would need to manually review the companion guides offered by the specific payers to confirm what is required for each.

📘

NOTE

Do not use real-world values in our sandbox API endpoints! Doing so will generate errors.

We provide a list of test values to use in sandbox so you can get a variety of different responses. See Sandbox Predefined Fields and Responses.

📘

NOTE

The JSON attributes in our APIs use snake-case, with the first letter of the attribute in lower case as in umClearingHouseId, tradingPartnerServiceId (the Payer ID; this will vary based on the payer you want to connect to) Our APIs are case-sensitive and your JSON request body must observe this convention.

👍

NOTE

For sandbox usage, all fields must have the correct predefined values to obtain a successful response. Inventing new PMI values or using real-world PMI values will result in errors. Please provide all of the values, such as umClearingHouseId, payerId, and so on marked as required (R) in your API requests.

Production

📘

NOTE

If you contract with Optum for API usage, use a separate credential pair issued by Optum for your production API work.

Subscribe to production environment

1. To request for a production environment account, reach out to sales @ [email protected] and for the following:

• To either start a new contract
• To have your contract-related questions answered
• If you have an existing account and want to add additional products to it
• Add/remove a product
• API endpoint usage example

In the preceding example:

• sandbox-apigw.optum.com: Base URL
• /apip/auth/v2/token: Endpoint

Use your API credentials provided by Optum to access the sandbox environment or production environment.

Prerequisites to use our APIs

Our APIs are private and require credentials to gain access Sign in and request for API credentials.

API components

Reference

• OpenAPI spec:
  You can use this JSON document to view all the allowable fields and objects for the API through an OpenAPI swagger preview. All of our API collections provide this specification as an easy download.