Customer Callback Example API

Introduction

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.

Callbacks API Overview

The Callbacks API allows customers to receive asynchronous notifications when a task is complete, eliminating the need for polling. This feature is currently supported for customers enrolled in Coverage Discovery.

OAuth2 Token Endpoint Specification

Customers must expose a token endpoint that adheres to [RFC 6749](https://datatracker.ials flow). This endpoint must be whitelisted by our system and will be used to obtain a bearer token before sending callback requests.

Token Request

Endpoint:
POST https://your-auth-server.com/token

Headers:

Authorization: Basic <base64(client_id:client_secret)>
Content-Type: application/x-www-form-urlencoded

Body:

grant_type=client_credentials

Token Response

The endpoint must respond with status 200 OK and a response JSON object with the following fields:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600, // value in seconds and used for token refresh
  "scope": "" // optional 

The expires_in field is critical — we use it to determine when to reissue the token.


Callback Delivery

Once a valid token is obtained, we will send the callback request to the whitelisted callback URL with the following header:

Authorization: Bearer <access_token>

Callback Endpoint Requirements

  • A successful response must return HTTP status code 204 (No Content).
  • If the access token is invalid or expired, your API must return HTTP status code 401 (Unauthorized).
  • The callback request will include the following headers:
    • Authorization: Bearer <access_token> — token obtained from your token endpoint
    • x-optum-tenant-id: <your-tenant-id> — your tenant identifier assigned during onboarding
    • x-optum-correlation-id: <correlation-id> — optional, if provided in the original request

Callback Request Payload

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


📘

Note: We recommend downloading the OpenAPI specification and viewing it in an OpenAPI editor for the best experience. Download the spec here .

Once you have downloaded and imported into an OpenAPI editor, you may also view the available example responses in the GET /rcm/eligibility/v1/coverage-discovery/{id} endpoint.


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.

In addition to the above, you can also view the expected request on the "Callbacks" tab next to "Parameters" in the Coverage Discovery POST endpoint /rcm/eligibility/v1/coverage-discovery.

Retries

Automated Retries

If either the token request or the callback delivery fails, we will retry the request up to 5 times. The wait interval between each retry is ~5 minutes.

This approach ensures that transient issues—such as brief outages or network delays—do not result in lost messages. We recommend that your callback API is designed to handle retries safely and idempotently.

Manual Retries

We also support the ability to manually retry callbacks:

  • By individual record ID
  • By a specified time range

Customer Callback Postman Example API

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.

✅ Pre-Requisites

Onboarding with Optum:

  • Enrollment in Coverage Discovery

Customer Built Callback API with OAuth2 Token Endpoint

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 for to authorize with their Whitelisted OAuth2 token endpoint

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": "b6f118d9-41a9-473b-a4f4-8e207fd66af7",
		"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## **Documentation**\nView Documentation and Setup Steps [here](https://developer.optum.com/eligibilityandclaims/docs/customer-callback-example-api):",
		"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
	},
	"item": [
		{
			"name": "Callback: Coverage Discovery Task (No Hydrated Realtime Response)",
			"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",
									"    pm.expect(pm.response.code).to.eql(204);\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    \"tenantName\": \"\",\n    \"traceId\": \"4c22f47b-1cca-7f48-373c-af7d887443b0\",\n    \"correlationId\": \"91d76432-ac2b-4ae2-b031-f8a6615a2df4\",\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    \"realTime\": {},\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}",
							"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",
									"    pm.expect(pm.response.code).to.eql(204);\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    \"tenantName\": \"\",\n    \"traceId\": \"4c22f47b-1cca-7f48-373c-af7d887443b0\",\n    \"correlationId\": \"91d76432-ac2b-4ae2-b031-f8a6615a2df4\",    \n    \"name\": \"Commercial + HMO\",\n    \"type\": \"serial\",\n    \"startDateTime\": \"2025-05-02T13:33:19Z\",\n    \"endDateTime\": \"2025-05-03T03:47:35Z\",\n    \"realTime\": {},\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}",
							"options": {
								"raw": {
									"language": "json"
								}
							}
						},
						"url": {
							"raw": "{{whitelisted_callback_url}}",
							"host": [
								"{{whitelisted_callback_url}}"
							]
						}
					},
					"response": []
				}
			]
		},
		{
			"name": "Consolidated Callback: Real Time Response",
			"item": [
				{
					"name": "Success: Callback - Successful Task Concluded, RealTime Patient Unknown",
					"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",
									"    pm.expect(pm.response.code).to.eql(204);\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\": \"6d94985a-b4a8-498d-a567-cc20a04a608f\",\n    \"tenantName\": \"customerName\",\n    \"traceId\": \"0d7e4ab6-8439-40ad-8470-98e7d464aa03\",\n    \"correlationId\": \"6063af1d-dc2f-4d57-a842-266014c2b423\",\n    \"status\": \"success\",\n    \"name\": \"search options discover task\",\n    \"type\": \"serial\",\n    \"startDateTime\": \"2025-04-12T21:14:01Z\",\n    \"endDateTime\": \"2025-04-12T21:14:21Z\",\n    \"realTime\": {\n        \"id\": \"4de1794e-8f62-49ad-9766-8154c3260382\",\n        \"name\": \"Real Time\",\n        \"timestamp\": \"2025-04-12T12:53:19Z\",\n        \"transaction\": {\n            \"id\": \"8fc5940f-7f85-4519-9166-c8fedfb3eb8e\",\n            \"status\": \"patient_unknown\",\n            \"chcPayerId\": \"87726\",\n            \"x12-271\": \"ISA*00*          *01*SomePwd   *ZZ*EMDEON         *ZZ*TPG00000       *230101*1253*^*00501*000000001*0*T*:~GS*HB*EMDEON*TPG00000*20230101*1253*1*X*005010X279A1~ST*271*0001*005010X279A1~BHT*0022*13*10001234*20230101*1253*TH~HL*1**20*1~NM1*PR*2*SOURCE NAME*****PI*SOURCEID~HL*2*1*21*1~NM1*1P*2*RECEIVER NAME*****PI*RECEIVERID~HL*3*2*22*0~NM1*IL*1*SUBSCRIBER NAME****MI*SUBSCRIBERID~DTP*291*RD8*20230101-20230101~EB*I**30~SE*10*0001~GE*1*1~IEA*1*000000001~\"\n        }\n    },\n    \"discoveryPaths\": {\n        \"successful\": [\n            {\n                \"id\": \"1fba95f2-e2fd-432f-a319-66b53bd5fd51\",\n                \"name\": \"Search - SB700 Subscriber First Name, Subscriber Last Name, Subscriber Date of Birth\",\n                \"timestamp\": \"2025-04-12T21:14:01Z\",\n                \"transaction\": {\n                    \"id\": \"746e74af-9abe-4e5a-a001-6f6a0718a7ea\",\n                    \"status\": \"eligible\",\n                    \"chcPayerId\": \"SB700\",\n                    \"x12-271\": \"ISA*00*          *01*SomePwd   *ZZ*EMDEON         *ZZ*TPG00000    *240722*1617*^*00501*000000001*0*T*:~GS*HB*EMDEON*TPG00000*20240722*1617*1*X*005010X279A1~ST*271*0001*005010X279A1~BHT*0022*11*1234567890*20240722*1617~HL*1**20*1~NM1*PR*2*SB700*****PI*SB700~HL*2*1*21*1~NM1*1P*2*TEST PROVIDER*****XX*1234567890~HL*3*2*22*0~TRN*2*1234567890*9876543210~NM1*IL*1*DOE*JOHN****MI*123456789~N3*123 MAIN ST~N4*HARTFORD*CT*06103~DMG*D8*19800101*M~INS*Y*18*030*25~DTP*291*D8*20240722~EB*1**30*GOLD PLAN~MSG*Eligibility confirmed for SB700 Gold Plan.~SE*25*0001~GE*1*1~IEA*1*000000001~\"\n                }\n            }\n        ],\n        \"unsuccessful\": [\n            {\n                \"id\": \"223c0f2d-8127-4b3d-a833-7682f9fe608f\",\n                \"name\": \"Search - SB700 Subscriber Member ID\",\n                \"timestamp\": \"2025-04-12T21:14:01Z\",\n                \"transaction\": {\n                    \"id\": \"26e1c315-fcab-4190-bf57-23eee4422df7\",\n                    \"status\": \"patient_unknown\",\n                    \"chcPayerId\": \"SB700\",\n                    \"x12-271\": \"ISA*00*          *01*SomePwd   *ZZ*EMDEON         *ZZ*TPG00000       *230101*1253*^*00501*000000001*0*T*:~GS*HB*EMDEON*TPG00000*20230101*1253*1*X*005010X279A1~ST*271*0001*005010X279A1~BHT*0022*13*10001234*20230101*1253*TH~HL*1**20*1~NM1*PR*2*SOURCE NAME*****PI*SOURCEID~HL*2*1*21*1~NM1*1P*2*RECEIVER NAME*****PI*RECEIVERID~HL*3*2*22*0~NM1*IL*1*SUBSCRIBER NAME****MI*SUBSCRIBERID~DTP*291*RD8*20230101-20230101~EB*I**30~SE*10*0001~GE*1*1~IEA*1*000000001~\"\n                }\n            },\n            {\n                \"id\": \"c9d39b8f-98d6-4508-a475-c978b096ec64\",\n                \"name\": \"Search - SB700 Subscriber Member ID, Subscriber First Name, Subscriber Last Name\",\n                \"timestamp\": \"2025-04-12T21:14:01Z\",\n                \"transaction\": {\n                    \"id\": \"ae86ffb5-71c9-42ed-9109-848e781cf617\",\n                    \"status\": \"patient_unknown\",\n                    \"chcPayerId\": \"SB700\",\n                    \"x12-271\": \"ISA*00*          *01*SomePwd   *ZZ*EMDEON         *ZZ*TPG00000       *230101*1253*^*00501*000000001*0*T*:~GS*HB*EMDEON*TPG00000*20230101*1253*1*X*005010X279A1~ST*271*0001*005010X279A1~BHT*0022*13*10001234*20230101*1253*TH~HL*1**20*1~NM1*PR*2*SOURCE NAME*****PI*SOURCEID~HL*2*1*21*1~NM1*1P*2*RECEIVER NAME*****PI*RECEIVERID~HL*3*2*22*0~NM1*IL*1*SUBSCRIBER NAME****MI*SUBSCRIBERID~DTP*291*RD8*20230101-20230101~EB*I**30~SE*10*0001~GE*1*1~IEA*1*000000001~\"\n                }\n            }\n        ],\n        \"pending\": [],\n        \"skipped\": []\n    }\n}",
							"options": {
								"raw": {
									"language": "json"
								}
							}
						},
						"url": {
							"raw": "{{whitelisted_callback_url}}",
							"host": [
								"{{whitelisted_callback_url}}"
							]
						}
					},
					"response": []
				},
				{
					"name": "Success: Callback - Failure Task Concluded, RealTime Success",
					"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",
									"    pm.expect(pm.response.code).to.eql(204);\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\": \"d4107065-0029-4071-b308-df7159e24131\",\n    \"tenantName\": \"customerName\",\n    \"traceId\": \"0d7e4ab6-8439-40ad-8470-98e7d464aa03\",\n    \"correlationId\": \"6063af1d-dc2f-4d57-a842-266014c2b423\",\n    \"status\": \"failure\",\n    \"name\": \"search options discover task\",\n    \"type\": \"serial\",\n    \"startDateTime\": \"2025-04-12T12:53:15Z\",\n    \"endDateTime\": \"2025-04-12T12:53:19Z\",\n    \"realTime\": {\n        \"id\": \"7a303676-9909-48e0-b655-887ceb707aec\",\n        \"name\": \"Real Time\",\n        \"timestamp\": \"2025-04-12T12:53:15Z\",\n        \"transaction\": {\n            \"id\": \"5cd73326-a66d-4ce9-b5bc-78fc50088dc7\",\n            \"status\": \"eligible\",\n            \"chcPayerId\": \"87726\",\n            \"x12-271\": \"ISA*00*          *01*SomePwd   *ZZ*EMDEON         *ZZ*TPG00000       *230101*1253*^*00501*000000001*0*T*:~GS*HB*EMDEON*TPG00000*20230101*1253*1*X*005010X279A1~ST*271*0001*005010X279A1~BHT*0022*13*10001234*20230101*1253*TH~HL*1**20*1~NM1*PR*2*SOURCE NAME*****PI*SOURCEID~HL*2*1*21*1~NM1*1P*2*RECEIVER NAME*****PI*RECEIVERID~HL*3*2*22*0~NM1*IL*1*SUBSCRIBER NAME****MI*SUBSCRIBERID~DTP*291*RD8*20230101-20230101~EB*I**30~SE*10*0001~GE*1*1~IEA*1*000000001~\"\n        }\n    },\n    \"discoveryPaths\": {\n        \"successful\": [],\n        \"unsuccessful\": [],\n        \"pending\": [],\n        \"skipped\": [\n            {\n                \"id\": \"\",\n                \"name\": \"SearchOptions\",\n                \"reason\": \"request does not meet path conditions\",\n                \"timestamp\": \"2025-04-12T12:53:15Z\"\n            }\n        ]\n    }\n}",
							"options": {
								"raw": {
									"language": "json"
								}
							}
						},
						"url": {
							"raw": "{{whitelisted_callback_url}}",
							"host": [
								"{{whitelisted_callback_url}}"
							]
						}
					},
					"response": []
				},
				{
					"name": "Success: Callback - Failure Task Concluded, RealTime Patient Unknown",
					"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",
									"    pm.expect(pm.response.code).to.eql(204);\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\": \"6d94985a-b4a8-498d-a567-cc20a04a608f\",\n    \"tenantName\": \"\",\n    \"traceId\": \"0d7e4ab6-8439-40ad-8470-98e7d464aa03\",\n    \"correlationId\": \"6063af1d-dc2f-4d57-a842-266014c2b423\",\n    \"status\": \"success\",\n    \"name\": \"search options discover task\",\n    \"type\": \"serial\",\n    \"startDateTime\": \"2025-04-12T21:14:01Z\",\n    \"endDateTime\": \"2025-04-12T21:14:21Z\",\n    \"realTime\": {\n        \"id\": \"4de1794e-8f62-49ad-9766-8154c3260382\",\n        \"name\": \"Real Time\",\n        \"timestamp\": \"2025-04-12T12:53:19Z\",\n        \"transaction\": {\n            \"id\": \"8fc5940f-7f85-4519-9166-c8fedfb3eb8e\",\n            \"status\": \"patient_unknown\",\n            \"chcPayerId\": \"87726\",\n            \"x12-271\": \"ISA*00*          *01*SomePwd   *ZZ*EMDEON         *ZZ*TPG00000       *230101*1253*^*00501*000000001*0*T*:~GS*HB*EMDEON*TPG00000*20230101*1253*1*X*005010X279A1~ST*271*0001*005010X279A1~BHT*0022*13*10001234*20230101*1253*TH~HL*1**20*1~NM1*PR*2*SOURCE NAME*****PI*SOURCEID~HL*2*1*21*1~NM1*1P*2*RECEIVER NAME*****PI*RECEIVERID~HL*3*2*22*0~NM1*IL*1*SUBSCRIBER NAME****MI*SUBSCRIBERID~DTP*291*RD8*20230101-20230101~EB*I**30~SE*10*0001~GE*1*1~IEA*1*000000001~\"\n        }\n    },\n    \"discoveryPaths\": {\n        \"successful\": [],\n        \"unsuccessful\": [\n            {\n                \"id\": \"223c0f2d-8127-4b3d-a833-7682f9fe608f\",\n                \"name\": \"Search - SB700 Subscriber Member ID\",\n                \"timestamp\": \"2025-04-12T21:14:01Z\",\n                \"transaction\": {\n                    \"id\": \"26e1c315-fcab-4190-bf57-23eee4422df7\",\n                    \"status\": \"patient_unknown\",\n                    \"chcPayerId\": \"SB700\",\n                    \"x12-271\": \"ISA*00*          *01*SomePwd   *ZZ*EMDEON         *ZZ*TPG00000       *230101*1253*^*00501*000000001*0*T*:~GS*HB*EMDEON*TPG00000*20230101*1253*1*X*005010X279A1~ST*271*0001*005010X279A1~BHT*0022*13*10001234*20230101*1253*TH~HL*1**20*1~NM1*PR*2*SOURCE NAME*****PI*SOURCEID~HL*2*1*21*1~NM1*1P*2*RECEIVER NAME*****PI*RECEIVERID~HL*3*2*22*0~NM1*IL*1*SUBSCRIBER NAME****MI*SUBSCRIBERID~DTP*291*RD8*20230101-20230101~EB*I**30~SE*10*0001~GE*1*1~IEA*1*000000001~\"\n                }\n            },\n            {\n                \"id\": \"c9d39b8f-98d6-4508-a475-c978b096ec64\",\n                \"name\": \"Search - SB700 Subscriber Member ID, Subscriber First Name, Subscriber Last Name\",\n                \"timestamp\": \"2025-04-12T21:14:01Z\",\n                \"transaction\": {\n                    \"id\": \"ae86ffb5-71c9-42ed-9109-848e781cf617\",\n                    \"status\": \"patient_unknown\",\n                    \"chcPayerId\": \"SB700\",\n                    \"x12-271\": \"ISA*00*          *01*SomePwd   *ZZ*EMDEON         *ZZ*TPG00000       *230101*1253*^*00501*000000001*0*T*:~GS*HB*EMDEON*TPG00000*20230101*1253*1*X*005010X279A1~ST*271*0001*005010X279A1~BHT*0022*13*10001234*20230101*1253*TH~HL*1**20*1~NM1*PR*2*SOURCE NAME*****PI*SOURCEID~HL*2*1*21*1~NM1*1P*2*RECEIVER NAME*****PI*RECEIVERID~HL*3*2*22*0~NM1*IL*1*SUBSCRIBER NAME****MI*SUBSCRIBERID~DTP*291*RD8*20230101-20230101~EB*I**30~SE*10*0001~GE*1*1~IEA*1*000000001~\"\n                }\n            }\n        ],\n        \"pending\": [],\n        \"skipped\": []\n    }\n}",
							"options": {
								"raw": {
									"language": "json"
								}
							}
						},
						"url": {
							"raw": "{{whitelisted_callback_url}}",
							"host": [
								"{{whitelisted_callback_url}}"
							]
						}
					},
					"response": []
				}
			]
		},
		{
			"name": "Token Invalid",
			"item": [
				{
					"name": "Failure: Callback - Invalid Token",
					"event": [
						{
							"listen": "prerequest",
							"script": {
								"exec": [
									""
								],
								"type": "text/javascript"
							}
						},
						{
							"listen": "test",
							"script": {
								"exec": [
									"pm.test(\"Invalid or Expired Token\", function () {\r",
									"    pm.expect(pm.response.code).to.eql(401);\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    \"tenantName\": \"\",\n    \"traceId\": \"4c22f47b-1cca-7f48-373c-af7d887443b0\",\n    \"correlationId\": \"91d76432-ac2b-4ae2-b031-f8a6615a2df4\",    \n    \"name\": \"Commercial + HMO\",\n    \"type\": \"serial\",\n    \"startDateTime\": \"2025-05-02T13:33:19Z\",\n    \"endDateTime\": \"2025-05-03T03:47:35Z\",\n    \"realTime\": {},\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}",
							"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"
		}
	]
}
  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

(Optional) Populate Collection Variables At Root

Collection Variables

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

  1. 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.
  2. 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

  1. In the Collections tab, Navigate back to the imported "Customer Callback Example API"
  2. Click on the root of the collection to expand it and navigate to the "Authorization" tab.
  3. 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.
  4. A new screen will appear to select the button "Use Token" as seen below
  5. You will notice that the Available Token section is now populated.
  6. 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

There are three folder options provided in the collection:

Callback: Coverage Discovery Task (No Hydrated Realtime Response)

This folder provides request body examples for customers receiving a standard Coverage Discovery Task callback response.

✅ Success: Callback - Successful Task Concluded

  • Request: Valid bearer token and success payload
  • Expected Response: 204 No Content
  • Purpose: Represents a successful Coverage Discovery task where coverage was found and the task completed without errors.

✅ Success: Callback - Failure Task Concluded

  • Request: Valid bearer token and failure payload
  • Expected Response: 204 No Content
  • Purpose: Represents a Coverage Discovery task that completed but did not find coverage, resulting in a failure status.

Consolidated Callback: Real Time Response

This folder provides request body examples for customers receiving a consolidated Callback option with the hydrated RealTime response included in the Coverage Discovery Task.

✅ Success: Callback - Successful Task Concluded, RealTime Patient Unknown

  • Request: Valid bearer token and success payload
  • Expected Response: 204 No Content
  • Purpose: Represents a successful Coverage Discovery task where the RealTime response indicates the patient is unknown.

✅ Success: Callback - Failure Task Concluded, RealTime Success

  • Request: Valid bearer token and failure payload
  • Expected Response: 204 No Content
  • Purpose: Demonstrates a scenario where RealTime successfully finds coverage, but the Coverage Discovery task fails due to unmet path conditions.

✅ Success: Callback - Failure Task Concluded, RealTime Patient Unknown

  • Request: Valid bearer token and failure payload
  • Expected Response: 204 No Content
  • Purpose: Represents a failed Coverage Discovery task where the RealTime response also indicates the patient is unknown, and no successful discovery paths are found.

Token Invalid

❌ Failure: Callback - Invalid Token

  • Request: No bearer token or an invalid one
  • Expected Response: 401 Unauthorized
  • Purpose: Validates that your callback API enforces authentication and rejects unauthorized 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

📞

Need help? See Troubleshooting and Support

↪️

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