Overview

The API Setup page covers the following information:

• Security and authorization
• Create sandbox account
• Generate a Bearer token
• Perform API health check
• Integrate APIs into your production environment

Security and authorization

Optum uses OAuth2 specification to establish a secure connection with our API users and our APIs are private and secure, which requires unique credentials to generate a Bearer token and gain access to.

❗️

REQUIRED

• Credentials - your unique identity in the Optum ecosystem
• Bearer token - to securely access our APIs
• Sandbox testing - ensure your integration works before you go live

API components

URLs

These are the base Sandbox and Production URLs for Optum APIs.

• Sandbox URL: https://sandbox-apigw.optum.com/
• Production URL: https://apigw.optum.com/

Create sandbox account

The sandbox environment allows you to familiarize yourself with our APIs and test and integrate for real-time usage in your production environment before you subscribe and enroll in our API product(s).

Go to Request Sandbox Access and select the API product of your choice and submit the form.

Optum provides you a set of unique credentials (client_id and client_secret) specific to your sandbox API environment, API product, and to your organization. Use the unique credentials to generate a Bearer token to securely access our APIs.

📘

NOTE

DO NOT perform load testing or production data testing in the sandbox environment. Select the GREYED out field values (pre-populated) to view example API responses.

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

❗️

IMPORTANT

Do not submit PHI or PII data on the Developer Portal's Try It! interface.

❗️

CAUTION

Guard your API access credentials. Avoid sharing it with others.

Generate a Bearer token

Try It! Interface

1. Select Generate Bearer token.
2. Enter your secure credentials:
   • grant_type : select client_credentials
   • client_id : your client ID
   • client_secret : your client secret
3. Select Try It! under the cURL Request box.

A Bearer token with a lifespan of 7200 seconds is generated (highlighted in yellow in the following figure) in the RESPONSE box below the Try It! interface.

Copy the Bearer token without the double quotes into a notepad to reuse it within the Bearer token lifespan of 7200 seconds.

📘

NOTE: You will have two sets of credentials.

• Sandbox - For testing APIs before or after signing a contract
• Production - Provided after contract signing or subscription processing.

Credentials are unique to your organization and API environment.
If you don’t have credentials, contact your account manager or API consultant.

In your development platform

1. Download and import the required product OpenAPI Spec (for example, Recast Claim Formatter OpenAPI Spec) provided in the Overview section into your platform.
2. Under the Product API Collection folder, select Get Token ([https://sandbox-apigw.optum.com/apip/auth/sntl/v1/token endpoint.
3. Select the Body tab and enter your secure credentials.

curl --request POST \
     --url https://sandbox-apigw.optum.com/apip/auth/sntl/v1/token \
     --header 'accept: application/json' \
     --header 'content-type: application/x-www-form-urlencoded' \
     --data grant_type=client_credentials \
     --data client_id="your client_id" \
     --data client_secret="your client_secret"

4. Send the request to generate a Bearer token.

The Bearer token is valid until the Bearer token expires to try the APIs.

📘

BEARER TOKEN LIFESPAN

The lifespan of a Bearer token is 7200 seconds for both sandbox and production environments.

We recommend automating transactions to use the tokens generated over the token lifespan. Obtaining tokens for each transaction is less efficient and does not improve the security criteria for any transactions.

Perform API health check

All our API collections include a /healthcheck endpoint to verify that the connection to the API server is established and the API is operational. See example.

Subscribe to live and mock data testing in sandbox environment

1. To test live and mock data testing, you must have purchased an API that shows a “subscribed” status in your AI Marketplace account.
2. Use your unique sandbox credentials (client_id and client_secret) (mentioned in the section above) to send live data to the sandbox environment for the API you purchased.
   At this point, responses will be based on the live data submitted to the sandbox environment as opposed to mock data preloaded to the sandbox environment.
3. You will retain the ability to query mock responses from a sandbox environment by using an optional request header called “environment”. By placing the value “sandbox" in the optional header, the request returns mock responses.

📘

NOTE

Do not submit PHI or PII data in the Sandbox environment.

Integrate our APIs in production environment

After successful sandbox testing, you can integrate our APIs for real-time usage in your production environment by subscribing and enrolling to an API product of your choice and select the contract term in Optum's AI Marketplace. Our business and technical teams support you through each step of the implementation process and through post-production.

Optum provides you a set of unique credentials (client_id and client_secret) specific to your production API environment, API product, and to your organization to generate a Bearer token to securely access our APIs.