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_infield 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 endpointx-optum-tenant-id: <your-tenant-id>— your tenant identifier assigned during onboardingx-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
- Download Postman (if applicable) and open the app.
- Go to your appropriate Workspace and navigate to the
Collectionstab. ClickImport.Click for Postman's instructions on Importing.
- Copy the
collection.jsonbelow and paste into thePaste raw textbox under theRaw Textoption.
{
"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"
}
]
}
- Click the
Continuebutton.
Step 4
- Then click the
Importbutton.
Step 5
- Next, navigate to the
Environmentstab in Postman. ClickImport. - Copy the
environment.jsonbelow and paste into thePaste raw textbox under theRaw Textoption.
{
"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 the
Continuebutton.
Step 8
- Then, click the
Importbutton.
Step 9
- Navigate to the newly imported "Customer Callback API ENV Example". Enter your own values for the following variables in
CURRENT_VALUEand save the changes:whitelisted_OAuth2_urlwhitelisted_callback_urlclient_idclient_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 asx-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-idin your original request), this value will be posted back on the concluded response asx-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
There are three folder options provided in the collection:
Callback: Coverage Discovery Task (No Hydrated Realtime Response)
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
Consolidated Callback: Real Time ResponseThis 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
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 OKfor successful token generation204 No Contentfor valid callback responses401 Unauthorizedfor invalid credentials or missing tokens403 Forbiddenif the token is present but lacks sufficient permissions
Need help? See Troubleshooting and Support
Looking for the homepage? Return to Enhanced Eligibility Overview here.
Updated about 1 month ago