Customer Callback Example API

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

Onboarding with Optum:

Enrollment in Coverage Discovery

Customer Builds Callback API with OAuth2 Token Endpoint

OAuth2 RFC for details for token endpoint.

example request:

POST https://your-auth-server.com/oauth/token
Authorization: Basic Y2xpZW50SWQ6Y2xpZW50U2VjcmV0 (i.e.base64(client_id:client_secret)
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials

example response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "" // up to customer
}

Whitelisted Endpoints:

Your OAuth2 token endpoint must be whitelisted by Optum.
Your Callback API endpoint must also be whitelisted.

API Credentials

( client_id, client_secret), generated by customer 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

Download Postman (if applicable) and open the app.
Go to your appropriate Workspace and navigate to the Collections tab. Click Import.
📘
Click for Postman's instructions on Importing.
Copy the collection.json below and paste into the Paste raw text box under the Raw Text option.

{
	"info": {
		"_postman_id": "48e4769d-2b5a-4960-8499-e51f679517f8",
		"name": "Customer Callback Example API",
		"description": "## 🧾 **Introduction**\n\nThe **Coverage Discovery** process involves long-running tasks whose results are delivered asynchronously. To receive these results, customers must implement a **Callback API** that supports **OAuth2 authentication**. This Postman collection provides a working example of how to simulate and test such an API.\n\nOnce your Callback API is implemented, this collection can be used to:\n\n*   Simulate task conclusion events (success/failure)\n*   Validate that your API correctly receives and handles these events\n    \n\n* * *\n\n### Onboarding with Optum:\n\n*   Enrollment in Coverage Discovery\n    \n\n### Customer Builds Callback API with OAuth2 Token Endpoint\n\n[OAuth2 RFC](https://datatracker.ietf.org/doc/html/rfc6749#section-2.3.1) for details for token endpoint.\n\n*   example request:\n    *   ```\n        POST https://your-auth-server.com/oauth/tokenAuthorization: Basic Y2xpZW50SWQ6Y2xpZW50U2VjcmV0 (i.e.base64(client_id:client_secret)Content-Type: application/x-www-form-urlencodedgrant_type=client_credentials\n        \n        ```\n        \n*   example response:\n    *   ```\n        {  \"access_token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\",  \"token_type\": \"Bearer\",  \"expires_in\": 3600,  \"scope\": \"\" // up to customer}\n        \n        ```\n        \n\n### Whitelisted Endpoints:\n\n*   Your OAuth2 token endpoint must be whitelisted by Optum.\n*   Your Callback API endpoint must also be whitelisted.\n    \n\n### API Credentials\n\n*   ( `client_id`, `client_secret`), generated by customer to authorize with the Whitelisted OAuth2 token endpoint\n    \n\n* * *\n\n## 🛠️ **Steps**\n\n### 1\\. **Setup**\n\n#### a. Import the Collection\n\n*   Follow Postman's instructions to import the provided collection into your workspace.\n    \n\n#### b. Import the Environment\n\n*   Import the **\"Customer Callback API ENV Example\"** environment file.\n    \n\n#### c. Configure Environment Variables\n\n*   Go to the **Environments** tab in Postman.\n*   Select **\"Customer Callback API ENV Example\"**.\n*   Fill in the following variables with your actual values:\n    \n\n| Variable | Description |\n| --- | --- |\n| `whitelisted_OAuth2_url` | Your OAuth2 token endpoint |\n| `whitelisted_callback_url` | Your Callback API endpoint |\n| `client_id` | Your OAuth2 client ID |\n| `client_secret` | Your OAuth2 client secret |\n\n* * *\n\n### (Optional) Populate Collection Variables At Root\n\n#### Collection Variables\n\nOn each request, the following variables may be populated by you to test your Callback API.\n\n1.  `customer_tenant_id` : During onboarding, you will be provided with a unique value as a \"TenantId\" that will be posted back on each request as `x-optum-tenant-id`. You may optionally populate this value when testing your Callback API.\n2.  `customer_correlation_id`: If you sent a unique correlationId header (`x-optum-correlation-id` in your original request, this value will be posted back on the concluded response as `x-optum-correlation-id`\n    \n\n![](https://files.readme.io/15aa9baf706ad46eca79acf19e8f66783007f45444137dd8ae8a69955cb4349d-Headers.png)\n\n## 🔐 Setting Up OAuth2 in Postman (After Importing the Collection)\n\n### ✅ Step-by-Step Instructions\n\n1.  In the Collections tab, Navigate back to the imported \"Customer Callback Example API\"\n2.  Click on the root of the collection to expand it and navigate to the \"Authorization\" tab.\n3.  Click on the \"Get New Access Token\" button, as seen in the image above. If successful, the below \"Authentication Complete\" will show, verifying you have set up the OAuth2 endpoint correctly.\n4.  A new screen will appear to select the button \"Use Token\" as seen below.\n5.  You will notice that the Available Token section is now populated.\n6.  The collection is now ready to run with the generated OAuth2 bearer token, as the requests are configured to inherit auth from parent:\n    \n\n* * *\n\n> 👍 You are now set up to execute Endpoint Test Scenarios !\n\n### 🔁 **Callback Endpoint**\n\n#### ✅ Success: Callback - Successful Task Concluded\n\n*   **Request**: Valid bearer token and success payload\n*   **Expected Response**: `204 No Content`\n*   **Purpose**: Simulates a successful coverage discovery result.\n    \n\n#### ✅ Success: Callback - Failure Task Concluded\n\n*   **Request**: Valid bearer token and failure payload\n*   **Expected Response**: `204 No Content`\n*   **Purpose**: Simulates a failed coverage discovery result.\n    \n\n#### ❌ Failure: Callback - Invalid Token\n\n*   **Request**: No bearer token or an invalid one\n*   **Expected Response**: `401 Unauthorized`\n*   **Purpose**: Validates that your API enforces authentication for callback requests.\n    \n\n* * *\n\n## 🧪 **Validation Tips**\n\n*   Monitor your Callback API logs to confirm receipt of the mock requests.\n*   Ensure your API returns appropriate HTTP status codes:\n    *   `200 OK` for successful token generation\n    *   `204 No Content` for valid callback responses\n    *   `401 Unauthorized` for invalid credentials or missing tokens\n    *   `403 Forbidden` if the token is present but lacks sufficient permissions\n\n### 📥 **Request Payload Validation**\n\nTo ensure your Callback API processes incoming requests correctly, it's important to validate the structure and data types of the request body.\n\nRefer to the Coverage Discovery model [here](https://developer.optum.com/eligibilityandclaims/reference/getdiscoverybyid-1) — specifically the **200 response body** — for a detailed schema of the expected payload. This includes field names, data types, and example values.\n\nUse this model as a reference to implement your own validation logic according to your system’s requirements. This will help ensure your API handles incoming data reliably and consistently.",
		"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
	},
	"item": [
		{
			"name": "Success: Callback - Successful Task Concluded",
			"event": [
				{
					"listen": "prerequest",
					"script": {
						"exec": [
							""
						],
						"type": "text/javascript"
					}
				},
				{
					"listen": "test",
					"script": {
						"exec": [
							"// expected status to return to Enhanced Eligibility is http status code 204.\r",
							"pm.test(\"Status code is 204\", function () {\r",
							" if (pm.response.code === 204) {\r",
							" pm.expect(pm.response.code).to.eql(204);\r",
							" } else {\r",
							" console.log(\"Unexpected status code:\", pm.response.code);\r",
							" pm.test(\"Unexpected status code\", function () {\r",
							" pm.expect(pm.response.code).to.eql(204); // This will fail the test\r",
							" });\r",
							" }\r",
							"});\r",
							""
						],
						"type": "text/javascript"
					}
				}
			],
			"request": {
				"method": "POST",
				"header": [
					{
						"key": "x-optum-correlation-id",
						"value": "{{customer_correlation_id}}",
						"type": "text",
						"description": "(Optional) A unique identifier value that is attached to the response that allow reference to the original request. Differs from x-optum-trace-id as the correlation-id is stored within the datastore for future queryability."
					},
					{
						"key": "x-optum-tenant-id",
						"value": "{{customer_tenant_id}}",
						"type": "text",
						"description": "The unique ID of the customer's tenant. Used to enforce data tenancy. This value is controlled by the Enhanced Eligibility Team."
					}
				],
				"body": {
					"mode": "raw",
					"raw": "{\n    \"id\": \"1e4c472f-a242-47b1-bbcf-89217dcdd473\",\n    \"status\": \"success\",\n    \"name\": \"search options discover task\",\n    \"type\": \"serial\",\n    \"startDateTime\": \"2025-04-21T16:14:38.185249239Z\",\n    \"endDateTime\": \"2025-04-21T16:14:43.250411638Z\",\n    \"discoveryPaths\": {\n        \"successful\": [\n            {\n                \"id\": \"4f683141-743a-4e37-afaa-ddd62570a87e\",\n                \"name\": \"Search - GACAID 66c338b1-fcd5-4fda-ba37-f88b6f7869c6\",\n                \"timestamp\": \"2025-04-21T16:14:38.199277641Z\",\n                \"transaction\": {\n                    \"id\": \"c3c09bfc-32dc-4317-8a4b-e5af1660250b\",\n                    \"status\": \"eligible\",\n                    \"chcPayerId\": \"GACAID\",\n                    \"x12-271\": \"string\"\n                }\n            }\n        ],\n        \"unsuccessful\": [\n            {\n                \"id\": \"cf3a0aba-9579-47ee-bec9-88860968cb24\",\n                \"name\": \"Search - GACAID 6ddad395-c7f4-45e2-b604-0a71b3c497ac\",\n                \"timestamp\": \"2025-04-21T16:14:38.199291842Z\",\n                \"transaction\": {\n                    \"id\": \"d356b7c9-0a7a-4f75-89a6-bb16054b8d3e\",\n                    \"status\": \"patient_unknown\",\n                    \"chcPayerId\": \"GACAID\",\n                    \"x12-271\": \"string\"\n                }\n            }\n        ],\n        \"pending\": [],\n        \"skipped\": [\n            {\n                \"name\": \"HMO\",\n                \"timestamp\": \"2025-04-21T16:14:43.245384355Z\",\n                \"reason\": \"request does not meet path conditions\"\n            }\n        ]\n    },\n    \"callbackUrl\": \"https://whitelistedcallbackurl.com\"\n}",
					"options": {
						"raw": {
							"language": "json"
						}
					}
				},
				"url": {
					"raw": "{{whitelisted_callback_url}}",
					"host": [
						"{{whitelisted_callback_url}}"
					]
				}
			},
			"response": []
		},
		{
			"name": "Success: Callback - Failure Task Concluded",
			"event": [
				{
					"listen": "prerequest",
					"script": {
						"exec": [
							""
						],
						"type": "text/javascript"
					}
				},
				{
					"listen": "test",
					"script": {
						"exec": [
							"// expected status to return to Enhanced Eligibility is http status code 204.\r",
							"pm.test(\"Status code is 204\", function () {\r",
							" if (pm.response.code === 204) {\r",
							" pm.expect(pm.response.code).to.eql(204);\r",
							" } else {\r",
							" console.log(\"Unexpected status code:\", pm.response.code);\r",
							" pm.test(\"Unexpected status code\", function () {\r",
							" pm.expect(pm.response.code).to.eql(204); // This will fail the test\r",
							" });\r",
							" }\r",
							"});\r",
							""
						],
						"type": "text/javascript"
					}
				}
			],
			"request": {
				"method": "POST",
				"header": [
					{
						"key": "x-optum-correlation-id",
						"value": "{{customer_correlation_id}}",
						"type": "text",
						"description": "(Optional) A unique identifier value that is attached to the response that allow reference to the original request. Differs from x-optum-trace-id as the correlation-id is stored within the datastore for future queryability."
					},
					{
						"key": "x-optum-tenant-id",
						"value": "{{customer_tenant_id}}",
						"type": "text",
						"description": "The unique ID of the customer's tenant. Used to enforce data tenancy. This value is controlled by the Enhanced Eligibility Team."
					}
				],
				"body": {
					"mode": "raw",
					"raw": "{\n    \"id\": \"49816c24-81f0-4bf3-9a02-addabde96a2e\",\n    \"status\": \"failure\",\n    \"name\": \"Commercial + HMO\",\n    \"type\": \"serial\",\n    \"startDateTime\": \"2025-05-02T13:33:19Z\",\n    \"endDateTime\": \"2025-05-03T03:47:35Z\",\n    \"discoveryPaths\": {\n        \"successful\": [],\n        \"unsuccessful\": [\n            {\n                \"id\": \"14337574-44b3-4ed9-8c00-2bafbf80cbcb\",\n                \"name\": \"Commercial\",\n                \"timestamp\": \"2025-05-02T13:33:19Z\",\n                \"transaction\": {\n                    \"id\": \"d812aefe-d52c-49f7-9912-d2ab24d6b331\",\n                    \"status\": \"patient_unknown\",\n                    \"chcPayerId\": \"87726\",\n                    \"x12-271\": \"string\"\n                }\n            },\n            {\n                \"id\": \"bbf02eb6-ad30-4651-8618-e74ed0807eeb\",\n                \"name\": \"Commercial\",\n                \"timestamp\": \"2025-05-02T13:33:19Z\",\n                \"transaction\": {\n                    \"id\": \"217f1f42-584f-4ae5-b9c5-4b6238168751\",\n                    \"status\": \"patient_unknown\",\n                    \"chcPayerId\": \"61101\",\n                    \"x12-271\": \"string\"\n                }\n            },\n            {\n                \"id\": \"1ef8bba5-4b15-4c7a-a2d3-19ea553f1ef9\",\n                \"name\": \"Commercial\",\n                \"timestamp\": \"2025-05-02T13:33:19Z\",\n                \"transaction\": {\n                    \"id\": \"af156e4c-7cdb-4d20-97a3-4f26d1ba2275\",\n                    \"status\": \"patient_unknown\",\n                    \"chcPayerId\": \"60054\",\n                    \"x12-271\": \"string\"\n                }\n            },\n            {\n                \"id\": \"53ffe72e-0b62-4ea9-bc2b-2cacd69c9c30\",\n                \"name\": \"Commercial\",\n                \"timestamp\": \"2025-05-02T13:33:19Z\",\n                \"transaction\": {\n                    \"id\": \"4f9bbc02-7707-4f7f-961e-6f220db891b0\",\n                    \"status\": \"patient_unknown\",\n                    \"chcPayerId\": \"CIGNA\",\n                    \"x12-271\": \"string\"\n                }\n            },\n            {\n                \"id\": \"2d765b48-6bc8-4f86-8509-d23b4481e285\",\n                \"name\": \"Commercial\",\n                \"timestamp\": \"2025-05-02T13:33:19Z\",\n                \"transaction\": {\n                    \"id\": \"3801a2c2-7ec4-4fc8-9876-350d9f08b6eb\",\n                    \"status\": \"patient_unknown\",\n                    \"chcPayerId\": \"27514\",\n                    \"x12-271\": \"string\"\n                }\n            }\n        ],\n        \"pending\": [],\n        \"skipped\": []\n    },\n    \"callbackUrl\": \"https://whitelistedcallbackurl.com\"\n}",
					"options": {
						"raw": {
							"language": "json"
						}
					}
				},
				"url": {
					"raw": "{{whitelisted_callback_url}}",
					"host": [
						"{{whitelisted_callback_url}}"
					]
				}
			},
			"response": []
		},
		{
			"name": "Failure: Callback - Invalid Token",
			"event": [
				{
					"listen": "prerequest",
					"script": {
						"exec": [
							""
						],
						"type": "text/javascript"
					}
				},
				{
					"listen": "test",
					"script": {
						"exec": [
							"pm.environment.set(\"bearer_token\", pm.response.json().access_token);\r",
							"\r",
							"pm.test(\"Invalid or Expired Token\", function () {\r",
							" if (pm.response.code === 401) {\r",
							" pm.expect(pm.response.code).to.be.eql(401);\r",
							" } \r",
							"});\r",
							""
						],
						"type": "text/javascript"
					}
				}
			],
			"request": {
				"auth": {
					"type": "bearer",
					"bearer": [
						{
							"key": "token",
							"value": "{{INVALID_BEARERTOKEN}}",
							"type": "string"
						}
					]
				},
				"method": "POST",
				"header": [
					{
						"key": "x-optum-correlation-id",
						"value": "{{customer_correlation_id}}",
						"type": "text",
						"description": "(Optional) A unique identifier value that is attached to the response that allow reference to the original request. Differs from x-optum-trace-id as the correlation-id is stored within the datastore for future queryability."
					},
					{
						"key": "x-optum-tenant-id",
						"value": "{{customer_tenant_id}}",
						"type": "text",
						"description": "The unique ID of the customer's tenant. Used to enforce data tenancy. This value is controlled by the Enhanced Eligibility Team."
					}
				],
				"body": {
					"mode": "raw",
					"raw": "{\n    \"id\": \"49816c24-81f0-4bf3-9a02-addabde96a2e\",\n    \"status\": \"failure\",\n    \"name\": \"Commercial + HMO\",\n    \"type\": \"serial\",\n    \"startDateTime\": \"2025-05-02T13:33:19Z\",\n    \"endDateTime\": \"2025-05-03T03:47:35Z\",\n    \"discoveryPaths\": {\n        \"successful\": [],\n        \"unsuccessful\": [\n            {\n                \"id\": \"14337574-44b3-4ed9-8c00-2bafbf80cbcb\",\n                \"name\": \"Commercial\",\n                \"timestamp\": \"2025-05-02T13:33:19Z\",\n                \"transaction\": {\n                    \"id\": \"d812aefe-d52c-49f7-9912-d2ab24d6b331\",\n                    \"status\": \"patient_unknown\",\n                    \"chcPayerId\": \"87726\",\n                    \"x12-271\": \"string\"\n                }\n            },\n            {\n                \"id\": \"bbf02eb6-ad30-4651-8618-e74ed0807eeb\",\n                \"name\": \"Commercial\",\n                \"timestamp\": \"2025-05-02T13:33:19Z\",\n                \"transaction\": {\n                    \"id\": \"217f1f42-584f-4ae5-b9c5-4b6238168751\",\n                    \"status\": \"patient_unknown\",\n                    \"chcPayerId\": \"61101\",\n                    \"x12-271\": \"string\"\n                }\n            },\n            {\n                \"id\": \"1ef8bba5-4b15-4c7a-a2d3-19ea553f1ef9\",\n                \"name\": \"Commercial\",\n                \"timestamp\": \"2025-05-02T13:33:19Z\",\n                \"transaction\": {\n                    \"id\": \"af156e4c-7cdb-4d20-97a3-4f26d1ba2275\",\n                    \"status\": \"patient_unknown\",\n                    \"chcPayerId\": \"60054\",\n                    \"x12-271\": \"string\"\n                }\n            },\n            {\n                \"id\": \"53ffe72e-0b62-4ea9-bc2b-2cacd69c9c30\",\n                \"name\": \"Commercial\",\n                \"timestamp\": \"2025-05-02T13:33:19Z\",\n                \"transaction\": {\n                    \"id\": \"4f9bbc02-7707-4f7f-961e-6f220db891b0\",\n                    \"status\": \"patient_unknown\",\n                    \"chcPayerId\": \"CIGNA\",\n                    \"x12-271\": \"string\"\n                }\n            },\n            {\n                \"id\": \"2d765b48-6bc8-4f86-8509-d23b4481e285\",\n                \"name\": \"Commercial\",\n                \"timestamp\": \"2025-05-02T13:33:19Z\",\n                \"transaction\": {\n                    \"id\": \"3801a2c2-7ec4-4fc8-9876-350d9f08b6eb\",\n                    \"status\": \"patient_unknown\",\n                    \"chcPayerId\": \"27514\",\n                    \"x12-271\": \"string\"\n                }\n            }\n        ],\n        \"pending\": [],\n        \"skipped\": []\n    },\n    \"callbackUrl\": \"https://whitelistedcallbackurl.com\"\n}",
					"options": {
						"raw": {
							"language": "json"
						}
					}
				},
				"url": {
					"raw": "{{whitelisted_callback_url}}",
					"host": [
						"{{whitelisted_callback_url}}"
					]
				}
			},
			"response": []
		}
	],
	"auth": {
		"type": "oauth2",
		"oauth2": [
			{
				"key": "accessTokenUrl",
				"value": "{{whitelisted_OAuth2_url}}",
				"type": "string"
			},
			{
				"key": "clientSecret",
				"value": "{{client_secret}}",
				"type": "string"
			},
			{
				"key": "clientId",
				"value": "{{client_id}}",
				"type": "string"
			},
			{
				"key": "tokenName",
				"value": "BEARERTOKEN",
				"type": "string"
			},
			{
				"key": "challengeAlgorithm",
				"value": "S256",
				"type": "string"
			},
			{
				"key": "grant_type",
				"value": "client_credentials",
				"type": "string"
			},
			{
				"key": "addTokenTo",
				"value": "header",
				"type": "string"
			},
			{
				"key": "client_authentication",
				"value": "header",
				"type": "string"
			}
		]
	},
	"event": [
		{
			"listen": "prerequest",
			"script": {
				"type": "text/javascript",
				"exec": [
					""
				]
			}
		},
		{
			"listen": "test",
			"script": {
				"type": "text/javascript",
				"exec": [
					""
				]
			}
		}
	],
	"variable": [
		{
			"key": "customer_tenant_id",
			"value": "",
			"type": "string"
		},
		{
			"key": "customer_correlation_id",
			"value": "",
			"type": "string"
		}
	]
}

Click theContinue button.

Then click the Import button.

Next, navigate to the Environments tab in Postman. Click Import.
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"
}

Click theContinue button.

Then, click the Import button.

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

(Optional) Populate Collection Variables At Root

Collection Variables

On each request, the following variables may be populated by you to test your Callback API.

customer_tenant_id : During onboarding, you will be provided with a unique value as a "TenantId" that will be posted back on each request as x-optum-tenant-id. You may optionally populate this value when testing your Callback API.
customer_correlation_id: If you sent a unique correlationId header (x-optum-correlation-id in your original request, this value will be posted back on the concluded response as x-optum-correlation-id

🔐 Setting Up OAuth2 in Postman (After Importing the Collection)

✅ Step-by-Step Instructions

In the Collections tab, Navigate back to the imported "Customer Callback Example API"
Click on the root of the collection to expand it and navigate to the "Authorization" tab.
Click on the "Get New Access Token" button, as seen in the image above. If successful, the below "Authentication Complete" will show, verifying you have set up the OAuth2 endpoint correctly.
A new screen will appear to select the button "Use Token" as seen below
You will notice that the Available Token section is now populated.
The collection is now ready to run with the generated OAuth2 bearer token, as the requests are configured to inherit auth from parent:

👍
You are now authenticated to execute Endpoint Test Scenarios !

🔁 Callback Endpoint

✅ Success: Callback - Successful Task Concluded

Request: Valid bearer token and success payload
Expected Response: 204 No Content
Purpose: Simulates a successful coverage discovery result.

✅ Success: Callback - Failure Task Concluded

Request: Valid bearer token and failure payload
Expected Response: 204 No Content
Purpose: Simulates a failed coverage discovery result.

❌ Failure: Callback - Invalid Token

Request: No bearer token or an invalid one
Expected Response: 401 Unauthorized
Purpose: Validates that your API enforces authentication for callback requests

🧪 Validation Tips

Monitor your Callback API logs to confirm receipt of the mock requests.
Ensure your API returns appropriate HTTP status codes:
- 200 OK for successful token generation
- 204 No Content for valid callback responses
- 401 Unauthorized for invalid credentials or missing tokens
- 403 Forbidden if the token is present but lacks sufficient permissions

📥 Request Payload Validation

To ensure your Callback API processes incoming requests correctly, it's important to validate the structure and data types of the request body.

Refer to the Coverage Discovery model here — specifically the 200 response body — for a detailed schema of the expected payload. This includes field names, data types, and example values.

Use this model as a reference to implement your own validation logic according to your system’s requirements. This will help ensure your API handles incoming data reliably and consistently.

📞
Need help? See Troubleshooting and Support

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

Updated 18 days ago

Customer Callback Example API

Overview

✅ Pre-Requisites

Onboarding with Optum:

Customer Builds Callback API with OAuth2 Token Endpoint

Whitelisted Endpoints:

API Credentials

Postman Collection Example

Setup

📘
Click for Postman's instructions on Importing.

(Optional) Populate Collection Variables At Root

Collection Variables

🔐 Setting Up OAuth2 in Postman (After Importing the Collection)

✅ Step-by-Step Instructions

👍
You are now authenticated to execute Endpoint Test Scenarios !

🔁 Callback Endpoint

✅ Success: Callback - Successful Task Concluded

✅ Success: Callback - Failure Task Concluded

❌ Failure: Callback - Invalid Token

🧪 Validation Tips

📥 Request Payload Validation

📞
Need help? See Troubleshooting and Support

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

Overview

✅ Pre-Requisites

Onboarding with Optum:

Customer Builds Callback API with OAuth2 Token Endpoint

Whitelisted Endpoints:

API Credentials

Postman Collection Example

Setup

📘Click for Postman's instructions on Importing.

(Optional) Populate Collection Variables At Root

Collection Variables

🔐 Setting Up OAuth2 in Postman (After Importing the Collection)

✅ Step-by-Step Instructions

👍You are now authenticated to execute Endpoint Test Scenarios !

🔁 Callback Endpoint

✅ Success: Callback - Successful Task Concluded

✅ Success: Callback - Failure Task Concluded

❌ Failure: Callback - Invalid Token

🧪 Validation Tips

📥 Request Payload Validation

📞Need help? See Troubleshooting and Support

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

📘
Click for Postman's instructions on Importing.

👍
You are now authenticated to execute Endpoint Test Scenarios !

📞
Need help? See Troubleshooting and Support

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