API & Services Connection™
Guides
Request Sandbox AccessMarketplaceCommunityQuick Reference

Customer Callback Example API

Suggest Edits

Overview

Due to the long-running nature of the Coverage Discovery process, all concluded task responses will be communicated asynchronously via the Customer's supplied callback url that must be whitelisted by Optum. Therefore,* if enrolled in Coverage Discovery*, the customer must build a Callback API with OAuth2 authentication in order to receive task responses.

Pre-Requisites

  • From Onboarding:
    • Enrollment in Coverage Discovery
    • Whitelisted OAuth2 token endpoint
    • Whitelisted Callback API endpoint
  • From Customer:
    • API Credentials ( client_id, client_secret), generated to authorize with the Whitelisted OAuth2 token endpoint

Postman Collection Example

The below Customer Callback Example collection serves as a reference callback API to which Coverage Discovery will send asynchronous responses. Once your Callback API has been built, this collection may also serve to test your API's functionality and ensure that mock requests have successfully been accepted.

Setup

  1. Download Postman(if applicable) and open the app.
  2. Go to your appropriate Workspace and navigate to the Collections tab. Click Import.

    📘

    Click for Postman's instructions on Importing.

  3. Copy the collection.json below and paste into the Paste raw text box under the Raw Text option. 
{
	"info": {
		"_postman_id": "29f50ece-d255-43a4-bfb6-222206d267c9",
		"name": "Customer Callback Example API",
		"description": "## Introduction\n\nDue to the long-running nature of the Coverage Discovery process, all concluded task responses will be communicated asynchronously via the Customer's supplied callbackUrl that must be whitelisted by Optum. Therefore, if enrolled in Coverage Discovery, the customer must build a Callback API with OAuth2 authentication in order to receive task responses. This collection serves as an example spec for said API to which Coverage Discovery will send asynchronous responses.\n\nOnce the Customer Callback API has been built, this may also serve to test this API's functionality and ensure that *mock requests* have successfully been accepted.\n\n### *Pre-Requisites*\n\n*   Onboarding\n*   Whitelisted OAuth2 token endpoint\n    *   API Credentials ( `client_id`, `client_secret`), generated by you to test\n*   Whitelisted Callback endpoint\n    \n\n### *Steps*\n\n##### Setup\n\n1.  Import the collection ([see instructions here](https://learning.postman.com/docs/getting-started/importing-and-exporting-data/)).\n2.  Import the \"Customer Callback API ENV Example\" environment\n3.  From the \"Environments\" tab, click the imported \"Customer Callback API ENV Example\". Enter the following values for the listed variables:\n    1.  `whitelisted_OAuth2_url`\n    2.  `whitelisted_callback_url`\n    3.  `client_id`\n    4.  `client_secret`\n\n##### Send Requests\n\n1.  Select the `Customer Callback API ENV Example` environment, following instructions from Postman [here](https://learning.postman.com/docs/sending-requests/environments/managing-environments/#switch-between-environments).\n    1.  Once this environment has been selected, the variable values set in Setup #3 will populate.\n2.  Execute the `Customer Callback Example - Task Pending (First Response)`POST request.\n3.  Repeat step #2 with the next POST request `Customer Callback Example - Task Concluded (Final Response)`",
		"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
	},
	"item": [
		{
			"name": "Customer Auth Endpoint Example",
			"event": [
				{
					"listen": "test",
					"script": {
						"exec": [
							"pm.environment.set(\"bearerToken\", pm.response.json().access_token);"
						],
						"type": "text/javascript"
					}
				}
			],
			"request": {
				"method": "POST",
				"header": [
					{
						"key": "x-optum-tenant-id",
						"value": "",
						"description": "The tenant ID given to you during onboarding for data tenancy",
						"type": "text"
					}
				],
				"body": {
					"mode": "raw",
					"raw": "{\r\n    \"client_id\":\"{{client_id}}\",\r\n    \"client_secret\":\"{{client_secret}}\",\r\n    \"grant_type\":\"client_credentials\"\r\n}",
					"options": {
						"raw": {
							"language": "json"
						}
					}
				},
				"url": {
					"raw": "{{whitelisted_OAuth2_tokenurl}}",
					"host": [
						"{{whitelisted_OAuth2_tokenurl}}"
					]
				}
			},
			"response": []
		},
		{
			"name": "Customer Callback Example - Task Pending (First Response)",
			"event": [
				{
					"listen": "prerequest",
					"script": {
						"exec": [
							""
						],
						"type": "text/javascript"
					}
				},
				{
					"listen": "test",
					"script": {
						"exec": [
							""
						],
						"type": "text/javascript"
					}
				}
			],
			"request": {
				"auth": {
					"type": "bearer",
					"bearer": [
						{
							"key": "token",
							"value": "{{bearer_token}}",
							"type": "string"
						}
					]
				},
				"method": "POST",
				"header": [
					{
						"key": "x-optum-correlation-id",
						"value": "{{customer_correlation_id}}",
						"type": "text",
						"description": "(Optional)"
					},
					{
						"key": "x-optum-tenant-id",
						"value": "{{customer_tenant_id}}",
						"type": "text"
					}
				],
				"body": {
					"mode": "raw",
					"raw": "{\n    \"id\": \"6743735-3303-4d9d-9f21-20dd5f6d7ab2\",\n    \"status\": \"pending\",\n    \"name\": \"serial discover task\",\n    \"type\": \"serial\",\n    \"startDateTime\": \"2023-07-21T17:32:28Z\",\n    \"endDatetime\": \"\",\n    \"discoveryPaths\": {\n        \"successful\": [],\n        \"unsuccessful\": [],\n        \"pending\": [\n            {\n                \"name\": \"Commercial - Cigna\"\n            },\n            {\n                \"name\": \"Commercial - Aetna\"\n            },\n            {\n                \"name\": \"Medicare\"\n            }\n        ],\n        \"skipped\": []\n    }\n}",
					"options": {
						"raw": {
							"language": "json"
						}
					}
				},
				"url": {
					"raw": "{{whitelisted_callback_url}}",
					"host": [
						"{{whitelisted_callback_url}}"
					]
				},
				"description": "This \"Customer Callback Example - Task Accepted\" is an example of the POST request sent by Enhanced Eligibility to communicate the creation of the record that's still in a \"pending\" state (see \"status\" field). The future callback requests related to the same id (\"6743735-3303-4d9d-9f21-20dd5f6d7ab2\") will be when the"
			},
			"response": []
		},
		{
			"name": "Customer Callback Example - Task Concluded (Final Response)",
			"event": [
				{
					"listen": "prerequest",
					"script": {
						"exec": [
							""
						],
						"type": "text/javascript"
					}
				},
				{
					"listen": "test",
					"script": {
						"exec": [
							""
						],
						"type": "text/javascript"
					}
				}
			],
			"request": {
				"auth": {
					"type": "bearer",
					"bearer": [
						{
							"key": "token",
							"value": "{{bearer_token}}",
							"type": "string"
						}
					]
				},
				"method": "POST",
				"header": [
					{
						"key": "x-optum-correlation-id",
						"value": "{{customer_correlation_id}}",
						"type": "text"
					},
					{
						"key": "x-optum-tenant-id",
						"value": "{{customer_tenant_id}}",
						"type": "text"
					}
				],
				"body": {
					"mode": "raw",
					"raw": "{\n    \"id\": \"36743735-3303-4d9d-9f21-20dd5f6d7ab2\",\n    \"status\": \"success\",\n    \"name\": \"serial discover task\",\n    \"type\": \"serial\",\n    \"startDateTime\": \"2023-07-21T17:32:28Z\",\n    \"endDatetime\": \"2023-08-21T17:32:28Z\",\n    \"discoveryPaths\": {\n        \"successful\": [\n            {\n                \"id\": \"ee7612c4-d400-4b48-83e3-c05875ee8b1f\",\n                \"name\": \"Commercial\",\n                \"description\": \"This discovery path targets a limited set of non-public payers\",\n                \"timestamp\": \"2023-07-21T17:34:28Z\",\n                \"transaction\": {\n                    \"id\": \"string\",\n                    \"status\": \"eligibile\",\n                    \"chcPayerId\": \"CIGNA\",\n                    \"x12-271\": \"string\"\n                }\n            }\n        ],\n        \"unsuccessful\": [\n            {\n                \"id\": \"ee7612c4-d400-4b48-83e3-c05875ee8b1f\",\n                \"name\": \"Commercial\",\n                \"description\": \"This discovery path targets a limited set of non-public payers\",\n                \"timestamp\": \"2023-07-21T17:34:28Z\",\n                \"transaction\": {\n                    \"id\": \"string\",\n                    \"status\": \"patient_unknown\",\n                    \"chcPayerId\": \"AETNA\",\n                    \"x12-271\": \"string\"\n                }\n            }\n        ],\n        \"pending\": [],\n        \"skipped\": [\n            {\n                \"id\": \"ee7612c4-d400-4b48-83e3-c05875ee8b1f\",\n                \"name\": \"Medicare\",\n                \"description\": \"string\",\n                \"timestamp\": \"2023-07-21T17:34:28Z\",\n                \"reason\": \"patient's MBI not found\"\n            }\n        ]\n    }\n}",
					"options": {
						"raw": {
							"language": "json"
						}
					}
				},
				"url": {
					"raw": "{{whitelisted_callback_url}}",
					"host": [
						"{{whitelisted_callback_url}}"
					]
				}
			},
			"response": []
		}
	],
	"auth": {
		"type": "oauth2",
		"oauth2": [
			{
				"key": "tokenName",
				"value": "Customer Callback API",
				"type": "string"
			},
			{
				"key": "accessTokenUrl",
				"value": "{{whitelisted_OAuth2_url}}",
				"type": "string"
			},
			{
				"key": "clientSecret",
				"value": "{{client_secret}}",
				"type": "string"
			},
			{
				"key": "clientId",
				"value": "{{client_id}}",
				"type": "string"
			},
			{
				"key": "grant_type",
				"value": "client_credentials",
				"type": "string"
			},
			{
				"key": "addTokenTo",
				"value": "header",
				"type": "string"
			}
		]
	},
	"event": [
		{
			"listen": "prerequest",
			"script": {
				"type": "text/javascript",
				"exec": [
					""
				]
			}
		},
		{
			"listen": "test",
			"script": {
				"type": "text/javascript",
				"exec": [
					""
				]
			}
		}
	]
}
  1. Click theContinue button.
Step 4

Step 4

  1. Then click the Import button.
Step 5

Step 5


  1. Next, navigate to the Environments tab in Postman. Click Import.
  2. Copy the environment.json below and paste into the Paste raw text box under the Raw Text option.
{
  "id": "3771ced9-e507-4419-8584-2ac4832ada87",
  "name": "Customer Callback API ENV Example",
  "values": [
    {
      "key": "whitelisted_OAuth2_url",
      "value": "CHANGE TO CUSTOMER WHITELISTED TOKEN URL",
      "type": "default",
      "enabled": true
    },
    {
      "key": "whitelisted_callback_url",
      "value": "CHANGE TO CUSTOMER WHITELISTED CALLBACK URL",
      "type": "default",
      "enabled": true
    },
    {
      "key": "client_id",
      "value": "CHANGE TO CLIENT_ID TO AUTHETNICATE WITH OAuth2 URL",
      "type": "default",
      "enabled": true
    },
    {
      "key": "client_secret",
      "value": "CHANGE TO CLIENT_SECRET VALUE TO AUTHENTICATE WITH OAuth2 URL",
      "type": "default",
      "enabled": true
    }
  ],
  "_postman_variable_scope": "environment",
  "_postman_exported_at": "2024-07-26T19:07:22.762Z",
  "_postman_exported_using": "Postman/9.14.14"
}
  1. Click theContinue button.
Step 8

Step 8

  1. Then, click the Import button.
Step 9

Step 9

  1. Navigate to the newly imported "Customer Callback API ENV Example". Enter your own values for the following variables in CURRENT_VALUE and save the changes:
    1. whitelisted_OAuth2_url
    2. whitelisted_callback_url
    3. client_id
    4. client_secret

👍

You are now set up to authenticate and execute requests!

Execute Requests

  1. Navigate back to the Customer Callback Example API collection.
  2. Select the Customer Callback API ENV Example environment, following instructions from Postman here. Once this environment has been selected, the variable values (set in step #10) will populate.
  3. First, authenticate with your OAuth2 endpoint by executing the Customer Auth Endpoint ExamplePOST request. The bearer token will automatically be added to the subsequent calls to your Callback API.
  4. Next, execute the Customer Callback Example - Task Pending (First Response) POST request. The request body includes mock data, mimicking an example synchronous response.
  5. Finally, execute the Customer Callback Example - Task Concluded (Final Response) POST request that will update the originally created record from #5 and conclude the pending task.

📞

Need help? See Troubleshooting and Support

↪️

Looking for the homepage? Return to Enhanced Eligibility Overview here.

Updated 2 months ago