Getting Started

Once successfully onboarded (see Onboarding), download the OpenAPI specification from the Overview page and use the starter collections provided in this developer portal to begin testing. This guide replaces the older shared Postman workspace flow, which is no longer maintained.

This page is the developer quickstart.

Use it for:

first API calls
headers and IDs you must persist
starter Postman and Insomnia flows
basic client-generation workflow

Do not use this page for product onboarding, clearinghouse ownership, feature enrollment approvals, or callback payload interpretation details. For those topics, see Onboarding for Providers & Channel Partners, Developer Onboarding, and Customer Callback Example API.

Choose a Starting Path

Use the option that best matches how your team works:

curl for the fastest first request
Postman for an importable collection with automatic bearer-token retrieval
Insomnia for an alternative desktop client workflow
OpenAPI Generator for SDK wrappers and typed client code

Portal Resources

OpenAPI specification: download it from the OpenAPI button on the Overview page
Postman collection: copy the raw JSON block from this guide into Postman
Postman Sandbox environment: copy the raw JSON block from this guide into Postman
Postman Production environment: copy the raw JSON block from this guide into Postman
Insomnia export: copy the raw JSON block from this guide into Insomnia

Before You Test

You will need:

Optum-issued client_id
Optum-issued client_secret
Your target base URL
- Sandbox: https://sandbox-apigw.optum.com
- Production: https://apigw.optum.com
Sandbox and Production use separate OAuth credentials. Use the Sandbox client_id and client_secret only with the Sandbox base URL, and use the Production client_id and client_secret only with the Production base URL.
Optional x-optum-subtenant-id only when Optum has explicitly assigned one to you

❗️
Protected Health Information (PHI) must not be transmitted or stored in the Sandbox environment.

If you need predictable Sandbox-only canned responses, use Sandbox Mock Scenarios. That guide lists the shared mock scenario headers that work for both JSON and X12 Enhanced Eligibility RTE requests, including scenarios that can create linked Coverage Discovery mock responses when Coverage Discovery is enabled in Sandbox.

Testing In Sandbox

Use this quick split:

For standard JSON Sandbox testing, use POST /rcm/eligibility/v1 with the normal supported Sandbox request values.
For predictable JSON or X12 canned responses, send the x-optum-rcmelig-mock-scenarios header with a supported scenario value from Sandbox Mock Scenarios.
The mock scenario header works with JSON requests to POST /rcm/eligibility/v1 and X12 requests to POST /rcm/eligibility/v1/real-time/x12.
Supported mock scenarios can create linked Coverage Discovery mock responses when Coverage Discovery is enabled in Sandbox.
Mock header scenario support and linked Coverage Discovery mock responses require the relevant Sandbox configuration to be completed before testing.
The mock scenario header is Sandbox-only and requires an exact, case-sensitive scenario value.
Do not send PHI in Sandbox.

Which Endpoint Should I Use?

Use this table when you are deciding where to start.

If you want to...	Use this endpoint	Notes
Start with the simplest real-time request shape	`POST /rcm/eligibility/v1`	Best default starting point for most teams. Send normalized JSON. `controlNumber` is optional. In Sandbox, shared mock scenario headers can apply when configured.
Submit a raw X12 270 request and still get the normalized JSON response	`POST /rcm/eligibility/v1/real-time/x12`	Best when your system already produces X12. In Sandbox, shared mock scenario headers can apply when configured.
Let Coverage Discovery run automatically when enrolled conditions are met	Start with either real-time endpoint above	This is the normal path for most customers. Check the response `link` header for related discovery task resources.
Submit Coverage Discovery directly using canonical JSON models	`POST /rcm/eligibility/v1/coverage-discovery`	Advanced pattern only. Use this only if you already have `canonicalEligibilityRequest` and, when needed, `canonicalEligibilityResponse`.
Submit Coverage Discovery directly using processed X12 payloads	`POST /rcm/eligibility/v1/coverage-discovery/x12`	Advanced pattern only. Often easier than direct canonical JSON if you already have `x12-270` and `x12-271`.

Headers And IDs

Item	Where	When to use it	Why it matters
`Authorization: Bearer <token>`	Request header	Every API call except token acquisition	Authenticates the request
`x-optum-correlation-id`	Request header	Recommended on every request	Lets your application and Optum support tie later records back to the original request
`x-optum-subtenant-id`	Request header	Only when Optum explicitly assigned one	Activates customer-specific configuration
`x-optum-tenant-id`	Response header	Every response	Confirms tenant context
`x-optum-trace-id`	Response header	Every response	Primary support trace key
`link`	Response header	Real-time responses that trigger integrated Coverage Discovery, list endpoints with pagination	Contains related discovery resources or pagination links
`location`	Response header	Direct Coverage Discovery `202 Accepted` responses	Contains the created discovery task resource
`x-total-count`	Response header	List queries when count is returned	Helps operational reporting and pagination

Store these values from your first tests:

Your original x-optum-correlation-id
The returned transaction id
Any discovery task id obtained from a link or location header
x-optum-trace-id
The environment used for the request
x-optum-subtenant-id when applicable
Request timestamp and payer ID

This data lets your application correlate later Coverage Discovery results and gives Support the minimum context needed for triage.

Quick Test With curl

This is the fastest way to confirm that your credentials work and that you can submit a real-time eligibility request.

1. Get an access token

export BASE_URL="https://sandbox-apigw.optum.com"
export CLIENT_ID="<your-client-id>"
export CLIENT_SECRET="<your-client-secret>"

ACCESS_TOKEN=$(
  curl -sS \
    -u "$CLIENT_ID:$CLIENT_SECRET" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "grant_type=client_credentials" \
    "$BASE_URL/apip/auth/v2/token" | jq -r '.access_token'
)

2. Submit a real-time JSON eligibility request

curl -sS \
  -X POST "$BASE_URL/rcm/eligibility/v1" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "x-optum-correlation-id: quickstart-001" \
  -d '{
    "tradingPartnerServiceId": "AETNA",
    "provider": {
      "organizationName": "Example Medical Center",
      "npi": "1234567893"
    },
    "informationReceiverName": {
      "address": {
        "state": "TX"
      }
    },
    "subscriber": {
      "memberId": "SUB123",
      "firstName": "JOHN",
      "lastName": "DOE",
      "dateOfBirth": "19500102",
      "ssn": "111223333",
      "additionalIdentification": {
        "patientAccountNumber": "PAN-1001"
      },
      "address": {
        "address1": "123 Main St",
        "city": "Dallas",
        "state": "TX",
        "postalCode": "75001"
      }
    },
    "encounter": {
      "dateOfService": "20250115",
      "serviceTypeCodes": ["30"]
    }
  }'

controlNumber is optional for Enhanced Eligibility JSON requests. If you omit it, Enhanced Eligibility generates one for you.

3. Save the returned transaction `id`

Use the returned id with:

GET /rcm/eligibility/v1/transactions/{id}
GET /rcm/eligibility/v1/transactions

If Coverage Discovery is enabled for your tenant, also inspect the HTTP link response header for related discovery task resources.

Persist both the transaction id and the response x-optum-trace-id. If a link header is returned, also persist each related discovery task id immediately.

4. Inspect `sourceType` on transaction responses

Transaction metadata can help you understand how a record was created and whether prior-result reuse affected the request. Use the transaction response details when you need to investigate request history.

Postman

Use the included collection when you want a ready-made test harness that handles token acquisition for you.

What the included collection does

Retrieves and refreshes the bearer token automatically before requests run
Uses the OAuth2 client credentials flow against /apip/auth/v2/token
Stores transaction_id from real-time responses
Stores discovery_id from Coverage Discovery receipts when a location header is returned
Includes starter requests for the most common real-time, transaction, discovery, and healthcheck flows

Import steps

Open Postman.
Click Import.
Choose Raw text.
Copy the raw JSON for the Postman collection and paste it into the import window.
Import one environment the same way by pasting the raw JSON for:
- the Sandbox environment
- or the Production environment
Complete the import.
In the imported environment, populate:
- client_id
- client_secret
Leave subtenant_id blank unless Optum explicitly instructed you to send it.
Select the imported environment and send a request.

Use the client_id and client_secret issued for the selected environment. Sandbox and Production credentials are separate.

Notes

The collection uses collection variables for token caching. In normal use, you should not need to fetch a token manually.
If you switch between Sandbox and Production, select the correct environment before sending the next request.
x-optum-subtenant-id is included as an optional variable-driven header. Do not populate it unless you were told to do so.
If you want predictable Sandbox canned responses, use Sandbox Mock Scenarios. The JSON and X12 starter requests include the same disabled mock header, which you can enable in Sandbox after the relevant Sandbox configuration is complete.

Insomnia

Use Insomnia if your team prefers it over Postman. The included export gives you the same core request set as the Postman collection.

Import steps

Open Insomnia.
Click Create or Import.
Choose the option to import from clipboard, raw text, or pasted JSON.
Copy the raw JSON for the Insomnia export and paste it into the import dialog.
Complete the import.
Update the base environment values:
- base_url
- client_id
- client_secret
- optional subtenant_id

Authentication behavior

The included export is configured for OAuth 2.0 client credentials against:

{{ _.base_url }}/apip/auth/v2/token

If your Insomnia version does not preserve OAuth settings exactly on import, use either of these fallbacks:

Import the downloaded OpenAPI specification directly into Insomnia and configure OAuth 2.0 client credentials once.
Copy one request from the included export, then set:
- Grant Type: Client Credentials
- Access Token URL: {{ _.base_url }}/apip/auth/v2/token
- Client ID: {{ _.client_id }}
- Client Secret: {{ _.client_secret }}

Recommended Insomnia flow

Submit Eligibility (JSON)
Copy the returned transaction id
Get Transaction By Id
If enrolled in Coverage Discovery, run a dry run first

If you want predictable Sandbox canned responses, use Sandbox Mock Scenarios. The JSON and X12 starter requests include the same disabled mock header, which you can enable in Sandbox after the relevant Sandbox configuration is complete.

Generate SDK Wrappers With OpenAPI Generator

If your team wants typed client wrappers in code instead of calling raw HTTP directly, download the OpenAPI specification from the Overview page.

openapi-generator-cli generate \
  -i <downloaded-openapi-file> \
  -g typescript-fetch \
  -o generated/typescript-fetch

Common generator targets include typescript-fetch, typescript-axios, python, java, csharp, and go. Generate into a dedicated directory and wrap the generated client with your own service layer for retries, logging, correlation ID generation, and optional subtenant header injection.

Next Guides

OpenAPI spec download: use the OpenAPI button on the Overview page
API Authentication: Security and Authorization
Sandbox canned-response testing: Sandbox Mock Scenarios
Callback implementation guide: Customer Callback Example API
Onboarding prerequisites: Onboarding
Product and feature enrollment: Onboarding for Providers & Channel Partners
Value-added feature behavior: Value-Added Features
Troubleshooting: Troubleshooting and Support

Raw JSON for Postman Collection

Copy everything in this block and paste it into Postman Import -> Raw text.

{
  "info": {
    "_postman_id": "4e27cb77-6624-44a2-b017-0bc7d6089458",
    "name": "Enhanced Eligibility API",
    "description": "Starter collection for the Enhanced Eligibility API. The collection retrieves a bearer token automatically with the OAuth2 client_credentials flow and includes common first-test requests for real-time eligibility, transaction lookup, coverage discovery, and healthcheck.",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "auth": {
    "type": "bearer",
    "bearer": [
      {
        "key": "token",
        "value": "{{access_token}}",
        "type": "string"
      }
    ]
  },
  "event": [
    {
      "listen": "prerequest",
      "script": {
        "type": "text/javascript",
        "exec": [
          "const token = pm.collectionVariables.get('access_token');",
          "const expiry = Number(pm.collectionVariables.get('access_token_expires_at') || '0');",
          "const now = Date.now();",
          "if (token && expiry - now > 60000) {",
          "  return;",
          "}",
          "",
          "const baseUrl = pm.collectionVariables.get('base_url');",
          "const clientId = pm.collectionVariables.get('client_id');",
          "const clientSecret = pm.collectionVariables.get('client_secret');",
          "",
          "if (!baseUrl || !clientId || !clientSecret) {",
          "  throw new Error('Set base_url, client_id, and client_secret before sending requests.');",
          "}",
          "",
          "const basic = CryptoJS.enc.Base64.stringify(CryptoJS.enc.Utf8.parse(clientId + ':' + clientSecret));",
          "",
          "pm.sendRequest({",
          "  url: baseUrl + '/apip/auth/v2/token',",
          "  method: 'POST',",
          "  header: [",
          "    { key: 'Authorization', value: 'Basic ' + basic },",
          "    { key: 'Content-Type', value: 'application/x-www-form-urlencoded' }",
          "  ],",
          "  body: {",
          "    mode: 'urlencoded',",
          "    urlencoded: [",
          "      { key: 'grant_type', value: 'client_credentials' }",
          "    ]",
          "  }",
          "}, function (err, res) {",
          "  if (err) {",
          "    throw err;",
          "  }",
          "  if (!res || res.code >= 400) {",
          "    throw new Error('Token request failed with status ' + (res && res.code));",
          "  }",
          "  const json = res.json();",
          "  if (!json.access_token) {",
          "    throw new Error('Token response did not include access_token.');",
          "  }",
          "  const expiresIn = Number(json.expires_in || 3300);",
          "  pm.collectionVariables.set('access_token', json.access_token);",
          "  pm.collectionVariables.set('access_token_expires_at', String(Date.now() + expiresIn * 1000));",
          "});"
        ]
      }
    }
  ],
  "variable": [
    { "key": "base_url", "value": "https://sandbox-apigw.optum.com" },
    { "key": "client_id", "value": "" },
    { "key": "client_secret", "value": "" },
    { "key": "access_token", "value": "" },
    { "key": "access_token_expires_at", "value": "0" },
    { "key": "correlation_id", "value": "quickstart-001" },
    { "key": "subtenant_id", "value": "" },
    { "key": "transaction_id", "value": "" },
    { "key": "discovery_id", "value": "" },
    { "key": "callback_url", "value": "https://example-customer.test/callbacks/coverage-discovery" }
  ],
  "item": [
    {
      "name": "Eligibility Requests",
      "item": [
        {
          "name": "Submit Eligibility (JSON)",
          "event": [
            {
              "listen": "test",
              "script": {
                "type": "text/javascript",
                "exec": [
                  "if (pm.response.code === 200) {",
                  "  const json = pm.response.json();",
                  "  if (json.id) {",
                  "    pm.collectionVariables.set('transaction_id', json.id);",
                  "  }",
                  "}"
                ]
              }
            }
          ],
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json", "type": "text" },
              { "key": "x-optum-correlation-id", "value": "{{correlation_id}}", "type": "text" },
              { "key": "x-optum-rcmelig-mock-scenarios", "value": "{{mock_elig_scenario}}", "type": "text", "disabled": true },
              { "key": "x-optum-subtenant-id", "value": "{{subtenant_id}}", "type": "text", "disabled": true }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"tradingPartnerServiceId\": \"AETNA\",\n  \"provider\": {\n    \"organizationName\": \"Example Medical Center\",\n    \"npi\": \"1234567893\"\n  },\n  \"informationReceiverName\": {\n    \"address\": {\n      \"state\": \"TX\"\n    }\n  },\n  \"subscriber\": {\n    \"memberId\": \"SUB123\",\n    \"firstName\": \"JOHN\",\n    \"lastName\": \"DOE\",\n    \"dateOfBirth\": \"19500102\",\n    \"ssn\": \"111223333\",\n    \"additionalIdentification\": {\n      \"patientAccountNumber\": \"PAN-1001\"\n    },\n    \"address\": {\n      \"address1\": \"123 Main St\",\n      \"city\": \"Dallas\",\n      \"state\": \"TX\",\n      \"postalCode\": \"75001\"\n    }\n  },\n  \"encounter\": {\n    \"dateOfService\": \"20250115\",\n    \"serviceTypeCodes\": [\"30\"]\n  }\n}"
            },
            "url": {
              "raw": "{{base_url}}/rcm/eligibility/v1",
              "host": [ "{{base_url}}" ],
              "path": [ "rcm", "eligibility", "v1" ]
            },
            "description": "Submit a normalized JSON real-time eligibility request. `controlNumber` is optional and Enhanced Eligibility will generate one if omitted. In Sandbox, optionally enable `x-optum-rcmelig-mock-scenarios` for a configured canned mock response from Sandbox Mock Scenarios. If Coverage Discovery is enrolled, inspect the response `link` header for related discovery task resources."
          }
        },
        {
          "name": "Submit Eligibility (X12)",
          "event": [
            {
              "listen": "test",
              "script": {
                "type": "text/javascript",
                "exec": [
                  "if (pm.response.code === 200) {",
                  "  const json = pm.response.json();",
                  "  if (json.id) {",
                  "    pm.collectionVariables.set('transaction_id', json.id);",
                  "  }",
                  "}"
                ]
              }
            }
          ],
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json", "type": "text" },
              { "key": "x-optum-correlation-id", "value": "{{correlation_id}}", "type": "text" },
              { "key": "x-optum-rcmelig-mock-scenarios", "value": "{{mock_elig_scenario}}", "type": "text", "disabled": true },
              { "key": "x-optum-subtenant-id", "value": "{{subtenant_id}}", "type": "text", "disabled": true }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"x12\": \"ISA*00*          *01*SomePwd   *ZZ*TPG00000       *ZZ*EMDEON         *220304*0343*^*00501*123456789*0*T*:~GS*HS*LLX1210001*MTEXE*20131015*2219*123456789*X*005010X279A1~ST*270*0001*005010X279A1~BHT*0022*13*1-622233a9-6fca5eb41ae6862b269452c9*20220304*0343~HL*1**20*1~NM1*PR*2*CMS*****PI*CMSMED~HL*2*1*21*1~NM1*1P*2*HAPPY DOCTORS GROUP PRACTICE*****XX*1234567893~HL*3*2*22*0~TRN*1*123456789*9877281234~NM1*IL*1*DOEONE*JOHNONE*M***MI*0000000000~N3*123 address1~N4*SEATTLE*WA*981010000~DMG*D8*18800102*F~DTP*291*RD8*20210101-20211231~EQ*30~SE*20*0001~GE*1*123456789~IEA*1*123456789~\"\n}"
            },
            "url": {
              "raw": "{{base_url}}/rcm/eligibility/v1/real-time/x12",
              "host": [ "{{base_url}}" ],
              "path": [ "rcm", "eligibility", "v1", "real-time", "x12" ]
            },
            "description": "Submit a JSON request body with `x12` set to the raw X12 270 payload, and receive the normalized JSON response model. In Sandbox, optionally enable `x-optum-rcmelig-mock-scenarios` for a configured canned mock response from Sandbox Mock Scenarios. If Coverage Discovery is enrolled, inspect the response `link` header for related discovery task resources."
          }
        }
      ]
    },
    {
      "name": "Eligibility Transactions",
      "item": [
        {
          "name": "Get All Transactions",
          "request": {
            "method": "GET",
            "header": [
              { "key": "x-optum-correlation-id", "value": "{{correlation_id}}", "type": "text" }
            ],
            "url": {
              "raw": "{{base_url}}/rcm/eligibility/v1/transactions?limit=10&offset=0",
              "host": [ "{{base_url}}" ],
              "path": [ "rcm", "eligibility", "v1", "transactions" ],
              "query": [
                { "key": "limit", "value": "10" },
                { "key": "offset", "value": "0" }
              ]
            }
          }
        },
        {
          "name": "Get Transaction By Id",
          "request": {
            "method": "GET",
            "header": [
              { "key": "x-optum-correlation-id", "value": "{{correlation_id}}", "type": "text" }
            ],
            "url": {
              "raw": "{{base_url}}/rcm/eligibility/v1/transactions/{{transaction_id}}",
              "host": [ "{{base_url}}" ],
              "path": [ "rcm", "eligibility", "v1", "transactions", "{{transaction_id}}" ]
            },
            "description": "Run a real-time request first so transaction_id is captured automatically."
          }
        }
      ]
    },
    {
      "name": "Coverage Discovery",
      "item": [
        {
          "name": "Submit Discovery Dry Run (JSON)",
          "event": [
            {
              "listen": "test",
              "script": {
                "type": "text/javascript",
                "exec": [
                  "const location = pm.response.headers.get('location');",
                  "if (location) {",
                  "  const id = location.split('/').pop();",
                  "  pm.collectionVariables.set('discovery_id', id);",
                  "}"
                ]
              }
            }
          ],
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json", "type": "text" },
              { "key": "x-optum-correlation-id", "value": "{{correlation_id}}", "type": "text" },
              { "key": "x-optum-subtenant-id", "value": "{{subtenant_id}}", "type": "text", "disabled": true }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"canonicalEligibilityRequest\": {\n    \"controlNumber\": \"123456789\",\n    \"tradingPartnerServiceId\": \"CIGNA\",\n    \"provider\": {\n      \"organizationName\": \"Example Medical Center\",\n      \"npi\": \"1234567893\"\n    },\n    \"informationReceiverName\": {\n      \"address\": {\n        \"state\": \"TX\"\n      }\n    },\n    \"subscriber\": {\n      \"memberId\": \"0000000000\",\n      \"firstName\": \"johnOne\",\n      \"lastName\": \"doeOne\",\n      \"dateOfBirth\": \"18800102\",\n      \"ssn\": \"555443333\",\n      \"address\": {\n        \"address1\": \"123 Main St\",\n        \"city\": \"Dallas\",\n        \"state\": \"TX\",\n        \"postalCode\": \"75001\"\n      }\n    },\n    \"encounter\": {\n      \"dateOfService\": \"20250115\",\n      \"serviceTypeCodes\": [\"30\"]\n    }\n  },\n  \"callbackUrl\": \"{{callback_url}}\",\n  \"dryRun\": true\n}"
            },
            "url": {
              "raw": "{{base_url}}/rcm/eligibility/v1/coverage-discovery",
              "host": [ "{{base_url}}" ],
              "path": [ "rcm", "eligibility", "v1", "coverage-discovery" ]
            },
            "description": "Recommended first Coverage Discovery request. `canonicalEligibilityRequest` is always required. Use `dryRun=true` to validate request acceptance without creating a live workflow result or sending a callback."
          }
        },
        {
          "name": "Submit Discovery Dry Run (X12)",
          "request": {
            "method": "POST",
            "header": [
              { "key": "Content-Type", "value": "application/json", "type": "text" },
              { "key": "x-optum-correlation-id", "value": "{{correlation_id}}", "type": "text" },
              { "key": "x-optum-subtenant-id", "value": "{{subtenant_id}}", "type": "text", "disabled": true }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"x12-270\": \"ISA*00*          *01*SomePwd   *ZZ*TPG00000       *ZZ*EMDEON         *220304*0343*^*00501*123456789*0*T*:~GS*HS*LLX1210001*MTEXE*20131015*2219*123456789*X*005010X279A1~ST*270*0001*005010X279A1~BHT*0022*13*1-622233a9-6fca5eb41ae6862b269452c9*20220304*0343~HL*1**20*1~NM1*PR*2*CMS*****PI*CMSMED~HL*2*1*21*1~NM1*1P*2*HAPPY DOCTORS GROUP PRACTICE*****XX*1234567893~HL*3*2*22*0~TRN*1*123456789*9877281234~NM1*IL*1*DOEONE*JOHNONE*M***MI*0000000000~N3*123 address1~N4*SEATTLE*WA*981010000~DMG*D8*18800102*F~DTP*291*RD8*20210101-20211231~EQ*30~SE*20*0001~GE*1*123456789~IEA*1*123456789~\",\n  \"x12-271\": \"ISA*00*          *01*SomePwd   *ZZ*EMDEON         *ZZ*TPG00000       *220304*0343*^*00501*123456789*0*T*:~GS*HB*MTEXE*LLX1210001*20131015*2219*123456789*X*005010X279A1~ST*271*0001*005010X279A1~BHT*0022*11*1-622233a9-6fca5eb41ae6862b269452c9*20220304*0343~HL*1**20*1~NM1*PR*2*CMS*****PI*CMSMED~HL*2*1*21*1~NM1*1P*2*HAPPY DOCTORS GROUP PRACTICE*****XX*1234567893~HL*3*2*22*0~TRN*2*123456789*9877281234~TRN*2*1266798199*9MCK-TSHRT~NM1*IL*1*DOEONE*JOHNONE*M***MI*0000000000~N3*123 address1~N4*SEATTLE*WA*981010000~DMG*D8*18800102*F~INS*Y*18*001*25~DTP*307*RD8*20211020-20211020~EB*I**41^54~EB*1**88~EB*1**30^42^45^48^49^69^76^83^A5^A7^AG^BT^BU^BV*MA~DTP*291*D8*20041101~MSG*0-Beneficiary insured due to age OASI~EB*C**30*MA**26*1484~DTP*291*RD8*20210101-20211231~EB*C**30*MA**29*1484~DTP*291*RD8*20210101-20211231~EB*C**42^45*MA**26*0~DTP*292*RD8*20210101-20211231~EB*1**30^2^23^24^25^26^27^28^3^33^36^37^38^39^4^40^42^50^51^52^53^62^67^69^73^76^83^86^98^A4^A6^A8^AI^AJ^AK^AL^BT^BU^BV^DM^UC*MB~DTP*291*D8*20041101~MSG*0-Beneficiary insured due to age OASI~EB*C**30*MB**23*203~DTP*291*RD8*20210101-20211231~EB*C**30*MB**29*0~DTP*291*RD8*20210101-20211231~EB*A**30*MB**27**0.2~DTP*291*RD8*20210101-20211231~EB*C**42^67^AJ*MB**23*0~DTP*292*RD8*20210101-20211231~EB*A**42^67^AJ*MB**27**0~DTP*292*RD8*20210101-20211231~EB*R**88*OT~REF*18*S5601~REF*N6*203*SilverScript SmartRx~DTP*292*D8*20210101~LS*2120~NM1*PR*2*extra healthy insurance~N3*123 address1~N4*Nashville*TN*37203~PER*IC**TE*0000000000*UR*www.testwebsite.com~LE*2120~SE*50*0001~GE*1*123456789~IEA*1*123456789~\",\n  \"callbackUrl\": \"{{callback_url}}\",\n  \"dryRun\": true\n}"
            },
            "url": {
              "raw": "{{base_url}}/rcm/eligibility/v1/coverage-discovery/x12",
              "host": [ "{{base_url}}" ],
              "path": [ "rcm", "eligibility", "v1", "coverage-discovery", "x12" ]
            }
          }
        },
        {
          "name": "Get All Discovery Tasks",
          "request": {
            "method": "GET",
            "header": [
              { "key": "x-optum-correlation-id", "value": "{{correlation_id}}", "type": "text" }
            ],
            "url": {
              "raw": "{{base_url}}/rcm/eligibility/v1/coverage-discovery?limit=10&offset=0",
              "host": [ "{{base_url}}" ],
              "path": [ "rcm", "eligibility", "v1", "coverage-discovery" ],
              "query": [
                { "key": "limit", "value": "10" },
                { "key": "offset", "value": "0" }
              ]
            }
          }
        },
        {
          "name": "Get Discovery By Id",
          "request": {
            "method": "GET",
            "header": [
              { "key": "x-optum-correlation-id", "value": "{{correlation_id}}", "type": "text" }
            ],
            "url": {
              "raw": "{{base_url}}/rcm/eligibility/v1/coverage-discovery/{{discovery_id}}",
              "host": [ "{{base_url}}" ],
              "path": [ "rcm", "eligibility", "v1", "coverage-discovery", "{{discovery_id}}" ]
            }
          }
        }
      ]
    },
    {
      "name": "Healthcheck",
      "item": [
        {
          "name": "Get Healthcheck",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/rcm/eligibility/v1/healthcheck",
              "host": [ "{{base_url}}" ],
              "path": [ "rcm", "eligibility", "v1", "healthcheck" ]
            }
          }
        }
      ]
    }
  ]
}

Raw JSON for Postman Sandbox Environment

Copy everything in this block and paste it into Postman Import -> Raw text.

{
  "id": "e71953fe-3ac2-4747-96d7-547f20f24d5a",
  "name": "Enhanced Eligibility Sandbox",
  "values": [
    {
      "key": "base_url",
      "value": "https://sandbox-apigw.optum.com",
      "enabled": true
    },
    {
      "key": "client_id",
      "value": "",
      "enabled": true
    },
    {
      "key": "client_secret",
      "value": "",
      "enabled": true
    },
    {
      "key": "subtenant_id",
      "value": "",
      "enabled": true
    },
    {
      "key": "mock_elig_scenario",
      "value": "REPLACE_WITH_SCENARIO_HEADER_VALUE",
      "enabled": true
    }
  ],
  "_postman_variable_scope": "environment",
  "_postman_exported_at": "2026-04-07T00:00:00.000Z",
  "_postman_exported_using": "Postman"
}

Raw JSON for Postman Production Environment

Copy everything in this block and paste it into Postman Import -> Raw text.

{
  "id": "bc98a82e-d4de-48b0-9c27-e55174b1a7b0",
  "name": "Enhanced Eligibility Production",
  "values": [
    {
      "key": "base_url",
      "value": "https://apigw.optum.com",
      "enabled": true
    },
    {
      "key": "client_id",
      "value": "",
      "enabled": true
    },
    {
      "key": "client_secret",
      "value": "",
      "enabled": true
    },
    {
      "key": "subtenant_id",
      "value": "",
      "enabled": true
    }
  ],
  "_postman_variable_scope": "environment",
  "_postman_exported_at": "2026-04-07T00:00:00.000Z",
  "_postman_exported_using": "Postman"
}

Raw JSON for Insomnia Import

Copy everything in this block and paste it into Insomnia import.

{
  "_type": "export",
  "__export_format": 4,
  "__export_date": "2026-04-07T00:00:00.000Z",
  "__export_source": "insomnia",
  "resources": [
    {
      "_id": "wrk_enhanced_eligibility",
      "parentId": null,
      "modified": 1775529600000,
      "created": 1775529600000,
      "name": "Enhanced Eligibility API",
      "description": "Repo-maintained starter Insomnia export for the Enhanced Eligibility API.",
      "scope": "collection",
      "_type": "workspace"
    },
    {
      "_id": "env_enhanced_eligibility_base",
      "parentId": "wrk_enhanced_eligibility",
      "modified": 1775529600000,
      "created": 1775529600000,
      "name": "Base Environment",
      "data": {
        "base_url": "https://sandbox-apigw.optum.com",
        "client_id": "",
        "client_secret": "",
        "correlation_id": "quickstart-001",
        "subtenant_id": "",
        "transaction_id": "",
        "discovery_id": "",
        "callback_url": "https://example-customer.test/callbacks/coverage-discovery",
        "mock_elig_scenario": "REPLACE_WITH_SCENARIO_HEADER_VALUE"
      },
      "_type": "environment"
    },
    {
      "_id": "fld_eligibility_requests",
      "parentId": "wrk_enhanced_eligibility",
      "modified": 1775529600000,
      "created": 1775529600000,
      "name": "Eligibility Requests",
      "description": "Submit a normalized JSON real-time eligibility request. If Coverage Discovery is enrolled, inspect the response link header for related discovery task resources.",
      "environment": {},
      "_type": "request_group"
    },
    {
      "_id": "fld_transactions",
      "parentId": "wrk_enhanced_eligibility",
      "modified": 1775529600000,
      "created": 1775529600000,
      "name": "Eligibility Transactions",
      "description": "Submit a normalized JSON real-time eligibility request. controlNumber is optional and Enhanced Eligibility will generate one if omitted.",
      "environment": {},
      "_type": "request_group"
    },
    {
      "_id": "fld_discovery",
      "parentId": "wrk_enhanced_eligibility",
      "modified": 1775529600000,
      "created": 1775529600000,
      "name": "Coverage Discovery",
      "description": "",
      "environment": {},
      "_type": "request_group"
    },
    {
      "_id": "fld_healthcheck",
      "parentId": "wrk_enhanced_eligibility",
      "modified": 1775529600000,
      "created": 1775529600000,
      "name": "Healthcheck",
      "description": "",
      "environment": {},
      "_type": "request_group"
    },
    {
      "_id": "req_submit_eligibility_json",
      "parentId": "fld_eligibility_requests",
      "modified": 1775529600000,
      "created": 1775529600000,
      "url": "{{ _.base_url }}/rcm/eligibility/v1",
      "name": "Submit Eligibility (JSON)",
      "description": "",
      "method": "POST",
      "body": {
        "mimeType": "application/json",
        "text": "{\n  \"tradingPartnerServiceId\": \"AETNA\",\n  \"provider\": {\n    \"organizationName\": \"Example Medical Center\",\n    \"npi\": \"1234567893\"\n  },\n  \"informationReceiverName\": {\n    \"address\": {\n      \"state\": \"TX\"\n    }\n  },\n  \"subscriber\": {\n    \"memberId\": \"SUB123\",\n    \"firstName\": \"JOHN\",\n    \"lastName\": \"DOE\",\n    \"dateOfBirth\": \"19500102\",\n    \"ssn\": \"111223333\",\n    \"additionalIdentification\": {\n      \"patientAccountNumber\": \"PAN-1001\"\n    },\n    \"address\": {\n      \"address1\": \"123 Main St\",\n      \"city\": \"Dallas\",\n      \"state\": \"TX\",\n      \"postalCode\": \"75001\"\n    }\n  },\n  \"encounter\": {\n    \"dateOfService\": \"20250115\",\n    \"serviceTypeCodes\": [\"30\"]\n  }\n}"
      },
      "parameters": [],
      "headers": [
        { "name": "Content-Type", "value": "application/json" },
        { "name": "x-optum-correlation-id", "value": "{{ _.correlation_id }}" },
        { "name": "x-optum-rcmelig-mock-scenarios", "value": "{{ _.mock_elig_scenario }}", "disabled": true },
        { "name": "x-optum-subtenant-id", "value": "{{ _.subtenant_id }}", "disabled": true }
      ],
      "authentication": {
        "type": "oauth2",
        "grantType": "client_credentials",
        "accessTokenUrl": "{{ _.base_url }}/apip/auth/v2/token",
        "clientId": "{{ _.client_id }}",
        "clientSecret": "{{ _.client_secret }}",
        "scope": "",
        "credentialsInBody": false
      },
      "_type": "request"
    },
    {
      "_id": "req_submit_eligibility_x12",
      "parentId": "fld_eligibility_requests",
      "modified": 1775529600000,
      "created": 1775529600000,
      "url": "{{ _.base_url }}/rcm/eligibility/v1/real-time/x12",
      "name": "Submit Eligibility (X12)",
      "description": "Submit a JSON request body with `x12` set to the raw X12 270 payload, and receive the normalized JSON response model. In Sandbox, optionally enable x-optum-rcmelig-mock-scenarios for a configured canned mock response from Sandbox Mock Scenarios. If Coverage Discovery is enrolled, inspect the response link header for related discovery task resources.",
      "method": "POST",
      "body": {
        "mimeType": "application/json",
        "text": "{\n  \"x12\": \"ISA*00*          *01*SomePwd   *ZZ*TPG00000       *ZZ*EMDEON         *220304*0343*^*00501*123456789*0*T*:~GS*HS*LLX1210001*MTEXE*20131015*2219*123456789*X*005010X279A1~ST*270*0001*005010X279A1~BHT*0022*13*1-622233a9-6fca5eb41ae6862b269452c9*20220304*0343~HL*1**20*1~NM1*PR*2*CMS*****PI*CMSMED~HL*2*1*21*1~NM1*1P*2*HAPPY DOCTORS GROUP PRACTICE*****XX*1234567893~HL*3*2*22*0~TRN*1*123456789*9877281234~NM1*IL*1*DOEONE*JOHNONE*M***MI*0000000000~N3*123 address1~N4*SEATTLE*WA*981010000~DMG*D8*18800102*F~DTP*291*RD8*20210101-20211231~EQ*30~SE*20*0001~GE*1*123456789~IEA*1*123456789~\"\n}"
      },
      "parameters": [],
      "headers": [
        { "name": "Content-Type", "value": "application/json" },
        { "name": "x-optum-correlation-id", "value": "{{ _.correlation_id }}" },
        { "name": "x-optum-rcmelig-mock-scenarios", "value": "{{ _.mock_elig_scenario }}", "disabled": true },
        { "name": "x-optum-subtenant-id", "value": "{{ _.subtenant_id }}", "disabled": true }
      ],
      "authentication": {
        "type": "oauth2",
        "grantType": "client_credentials",
        "accessTokenUrl": "{{ _.base_url }}/apip/auth/v2/token",
        "clientId": "{{ _.client_id }}",
        "clientSecret": "{{ _.client_secret }}",
        "scope": "",
        "credentialsInBody": false
      },
      "_type": "request"
    },
    {
      "_id": "req_get_all_transactions",
      "parentId": "fld_transactions",
      "modified": 1775529600000,
      "created": 1775529600000,
      "url": "{{ _.base_url }}/rcm/eligibility/v1/transactions?limit=10&offset=0",
      "name": "Get All Transactions",
      "description": "",
      "method": "GET",
      "parameters": [],
      "headers": [
        { "name": "x-optum-correlation-id", "value": "{{ _.correlation_id }}" }
      ],
      "authentication": {
        "type": "oauth2",
        "grantType": "client_credentials",
        "accessTokenUrl": "{{ _.base_url }}/apip/auth/v2/token",
        "clientId": "{{ _.client_id }}",
        "clientSecret": "{{ _.client_secret }}",
        "scope": "",
        "credentialsInBody": false
      },
      "_type": "request"
    },
    {
      "_id": "req_get_transaction_by_id",
      "parentId": "fld_transactions",
      "modified": 1775529600000,
      "created": 1775529600000,
      "url": "{{ _.base_url }}/rcm/eligibility/v1/transactions/{{ _.transaction_id }}",
      "name": "Get Transaction By Id",
      "description": "Paste the transaction_id from a prior real-time response.",
      "method": "GET",
      "parameters": [],
      "headers": [
        { "name": "x-optum-correlation-id", "value": "{{ _.correlation_id }}" }
      ],
      "authentication": {
        "type": "oauth2",
        "grantType": "client_credentials",
        "accessTokenUrl": "{{ _.base_url }}/apip/auth/v2/token",
        "clientId": "{{ _.client_id }}",
        "clientSecret": "{{ _.client_secret }}",
        "scope": "",
        "credentialsInBody": false
      },
      "_type": "request"
    },
    {
      "_id": "req_submit_discovery_dry_run_json",
      "parentId": "fld_discovery",
      "modified": 1775529600000,
      "created": 1775529600000,
      "url": "{{ _.base_url }}/rcm/eligibility/v1/coverage-discovery",
      "name": "Submit Discovery Dry Run (JSON)",
      "description": "",
      "method": "POST",
      "body": {
        "mimeType": "application/json",
        "text": "{\n  \"canonicalEligibilityRequest\": {\n    \"controlNumber\": \"123456789\",\n    \"tradingPartnerServiceId\": \"CIGNA\",\n    \"provider\": {\n      \"organizationName\": \"Example Medical Center\",\n      \"npi\": \"1234567893\"\n    },\n    \"informationReceiverName\": {\n      \"address\": {\n        \"state\": \"TX\"\n      }\n    },\n    \"subscriber\": {\n      \"memberId\": \"0000000000\",\n      \"firstName\": \"johnOne\",\n      \"lastName\": \"doeOne\",\n      \"dateOfBirth\": \"18800102\",\n      \"ssn\": \"555443333\",\n      \"address\": {\n        \"address1\": \"123 Main St\",\n        \"city\": \"Dallas\",\n        \"state\": \"TX\",\n        \"postalCode\": \"75001\"\n      }\n    },\n    \"encounter\": {\n      \"dateOfService\": \"20250115\",\n      \"serviceTypeCodes\": [\"30\"]\n    }\n  },\n  \"callbackUrl\": \"{{ _.callback_url }}\",\n  \"dryRun\": true\n}"
      },
      "parameters": [],
      "headers": [
        { "name": "Content-Type", "value": "application/json" },
        { "name": "x-optum-correlation-id", "value": "{{ _.correlation_id }}" },
        { "name": "x-optum-subtenant-id", "value": "{{ _.subtenant_id }}", "disabled": true }
      ],
      "authentication": {
        "type": "oauth2",
        "grantType": "client_credentials",
        "accessTokenUrl": "{{ _.base_url }}/apip/auth/v2/token",
        "clientId": "{{ _.client_id }}",
        "clientSecret": "{{ _.client_secret }}",
        "scope": "",
        "credentialsInBody": false
      },
      "_type": "request"
    },
    {
      "_id": "req_get_discovery_by_id",
      "parentId": "fld_discovery",
      "modified": 1775529600000,
      "created": 1775529600000,
      "url": "{{ _.base_url }}/rcm/eligibility/v1/coverage-discovery/{{ _.discovery_id }}",
      "name": "Get Discovery By Id",
      "description": "Paste the discovery_id from a prior response or location header.",
      "method": "GET",
      "parameters": [],
      "headers": [
        { "name": "x-optum-correlation-id", "value": "{{ _.correlation_id }}" }
      ],
      "authentication": {
        "type": "oauth2",
        "grantType": "client_credentials",
        "accessTokenUrl": "{{ _.base_url }}/apip/auth/v2/token",
        "clientId": "{{ _.client_id }}",
        "clientSecret": "{{ _.client_secret }}",
        "scope": "",
        "credentialsInBody": false
      },
      "_type": "request"
    },
    {
      "_id": "req_healthcheck",
      "parentId": "fld_healthcheck",
      "modified": 1775529600000,
      "created": 1775529600000,
      "url": "{{ _.base_url }}/rcm/eligibility/v1/healthcheck",
      "name": "Get Healthcheck",
      "description": "",
      "method": "GET",
      "parameters": [],
      "headers": [],
      "authentication": {
        "type": "oauth2",
        "grantType": "client_credentials",
        "accessTokenUrl": "{{ _.base_url }}/apip/auth/v2/token",
        "clientId": "{{ _.client_id }}",
        "clientSecret": "{{ _.client_secret }}",
        "scope": "",
        "credentialsInBody": false
      },
      "_type": "request"
    }
  ]
}

📞
Need help? See Troubleshooting and Support

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

Getting Started

Choose a Starting Path

Portal Resources

Before You Test

❗️
Protected Health Information (PHI) must not be transmitted or stored in the Sandbox environment.

Testing In Sandbox

Which Endpoint Should I Use?

Headers And IDs

Quick Test With curl

1. Get an access token

2. Submit a real-time JSON eligibility request

3. Save the returned transaction `id`

4. Inspect `sourceType` on transaction responses

Postman

What the included collection does

Import steps

Recommended Postman flow

Notes

Insomnia

Import steps

Authentication behavior

Recommended Insomnia flow

Generate SDK Wrappers With OpenAPI Generator

Next Guides

Raw JSON for Postman Collection

Raw JSON for Postman Sandbox Environment

Raw JSON for Postman Production Environment

Raw JSON for Insomnia Import

📞
Need help? See Troubleshooting and Support

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

What’s Next

Choose a Starting Path

Portal Resources

Before You Test

❗️Protected Health Information (PHI) must not be transmitted or stored in the Sandbox environment.

Testing In Sandbox

Which Endpoint Should I Use?

Headers And IDs

Quick Test With curl

1. Get an access token

2. Submit a real-time JSON eligibility request

3. Save the returned transaction id

4. Inspect sourceType on transaction responses

Postman

What the included collection does

Import steps

Recommended Postman flow

Notes

Insomnia

Import steps

Authentication behavior

Recommended Insomnia flow

Generate SDK Wrappers With OpenAPI Generator

Next Guides

Raw JSON for Postman Collection

Raw JSON for Postman Sandbox Environment

Raw JSON for Postman Production Environment

Raw JSON for Insomnia Import

📞Need help? See Troubleshooting and Support

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

What’s Next

❗️
Protected Health Information (PHI) must not be transmitted or stored in the Sandbox environment.

3. Save the returned transaction `id`

4. Inspect `sourceType` on transaction responses

📞
Need help? See Troubleshooting and Support

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