API Setup

📢

Coming Soon!!

📘

NOTE

Please use the table of contents on the right side of this page to quickly navigate to a desired topic.

Overview

Please note that 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 going live

API components

URLs

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

Create sandbox

The sandbox environment allows you to familiarize yourself with our APIs and test our APIs before subscribing and enrolling to our API products, and integrating for real-time usage in your production environment.

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

We will provide 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

Please 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

Please do not submit PHI or PII data on the developer portal's Try It interface.

Generate a Bearer token

❗️

CAUTION

Carefully guard your API access credentials. Avoid sharing them with others.

In Try It interface

1. Click Generate Bearer token.
2. Enter the company-specific secure credentials provided:
   • grant_type: select client_credentials
   • client_id: your client_id
   • client_secret: your client_secret
3. Click Try It! under the cURL Request box.

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

Copy the Bearer token without the double quotes into a notepad for reusing within the Bearer token lifespan of 7200 seconds.

In your development platform

1. Download and import the required product OpenAPI Spec (for example Pre-Care Estimate OpenAPI Spec provided in the Overview section into your platform.
2. Under the product API collection folder, click the Get Token (https://sandbox-apigw.optum.com/apip/auth/sntl/v1/token) endpoint.
3. Click the Body tab and enter the unique secure credentials.
   • grant_type: client_credentials
   • client_id: your client_id
   • client_secret: your client_secret
   Bearer Token Request Example

   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.

Copy the Bearer token without the double quotes into a notepad to reuse it to try other APIs within the Bearer token lifespan.

📘

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 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. Please work with your API consultant to associate the provider TIN(s) before sending live data to the sandbox environment.
2. Use your sandbox unique credentials (client_id and client_secret) (mentioned in the section above) to send live data to the sandbox environment for the API 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

Please do not submit PHI or PII data on 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 at Optum AI Marketplace. Our business and technical teams support you through each step of the implementation process and through post-production.

We will provide 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.

If you need help with this process reach out to @Contact us. Please refer to our FAQs to find common queries answered.

Pre-Care Estimate Technical Reference Guide