API & Services Connection™
Guides
Request Sandbox AccessMarketplaceCommunityQuick Reference

Getting Started

Suggest Edits

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:

  1. curl for the fastest first request
  2. Postman for an importable collection with automatic bearer-token retrieval
  3. Insomnia for an alternative desktop client workflow
  4. 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
  • 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.

Integration Decision Points

Before you build your first client, make these decisions:

  1. Use POST /rcm/eligibility/v1 for normalized JSON requests or POST /rcm/eligibility/v1/real-time/x12 for JSON request bodies with x12 set to the X12 270 payload
  2. Decide whether your implementation needs real-time eligibility only, or real-time eligibility with integrated Coverage Discovery
  3. Decide whether you will receive Coverage Discovery results by callback, polling, or both
  4. Decide whether your client ever needs to send x-optum-subtenant-id
  5. Decide whether you need enrolled value-added behavior disabled in any request path using x-optum-eligibility-disable-value-add

If you are considering direct Coverage Discovery:

  • treat it as an advanced pattern rather than the normal starting path
  • prefer POST /rcm/eligibility/v1/coverage-discovery/x12 if you already have the processed x12-270 and x12-271
  • use POST /rcm/eligibility/v1/coverage-discovery only if you already have the canonical eligibility request and, when needed, canonical eligibility response models

Request and Response Cheat Sheet

ItemWhereWhen to use itWhy it matters
Authorization: Bearer <token>Request headerEvery API call except token acquisitionAuthenticates the request
x-optum-correlation-idRequest headerRecommended on every requestLets your application and Optum support tie later records back to the original request
x-optum-subtenant-idRequest headerOnly when Optum explicitly assigned oneActivates customer-specific configuration
x-optum-tenant-idResponse headerEvery responseConfirms tenant context
x-optum-trace-idResponse headerEvery responsePrimary support trace key
linkResponse headerReal-time responses that trigger integrated Coverage Discovery, list endpoints with paginationContains related discovery resources or pagination links
locationResponse headerDirect Coverage Discovery 202 Accepted responsesContains the created discovery task resource
x-total-countResponse headerList queries when count is returnedHelps operational reporting and pagination

What Your Application Should Persist

At a minimum, store:

  • 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 materially reduces support turnaround time and lets your application safely correlate asynchronous discovery results.

Status Meanings

Real-time transaction statuses commonly include:

  • eligible: active coverage was returned
  • ineligible: the payer responded but coverage was not active for the requested context
  • patient_unknown: the payer could not match the submitted member details
  • payer_unavailable: the payer or upstream dependency could not be reached successfully
  • processing_error: the request could not be completed due to a processing problem

Coverage Discovery task statuses are:

  • pending: the task has been created but is not finalized
  • success: at least one discovery outcome completed successfully
  • failure: the task completed without a successful discovery outcome

Response Time Expectations

Developers should plan for materially different timing profiles between Real-Time Eligibility and Coverage Discovery.

Real-Time Eligibility

Real-Time Eligibility depends on payer and clearinghouse response time.

Important behavior:

  • the downstream clearinghouse timeout is 2 minutes
  • that timeout exists to allow for slower payer connectivity and heavier traffic periods such as the first or last day of the month
  • payer response time is the main driver of end-to-end RTE latency
  • Enhanced Eligibility platform touch time is much smaller than total payer-facing latency

Current RTE metrics:

  • end-to-end p95: 20.7 seconds
  • end-to-end p99: 30.6 seconds
  • Enhanced Eligibility touch time p95: 91.3 ms
  • Enhanced Eligibility touch time p99: 171 ms

Coverage Discovery

Coverage Discovery is asynchronous. Discovery paths and add-ons are enabled per customer and are not included automatically.

Customers who are highly sensitive to response time should understand:

  • Coverage Discovery is intentionally async for this reason
  • the non-Coverage-Insight paths are near-real-time relative to traditional discovery workflows
  • customers primarily concerned with strict turnaround should avoid enrolling in Coverage Insight

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 '{
    "controlNumber": "123456789",
    "tradingPartnerServiceId": "AETNA",
    "provider": {
      "organizationName": "Example Medical Center",
      "npi": "0123456789"
    },
    "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"]
    }
  }'

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

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

Recommended Postman flow

  1. Eligibility Requests / Submit Eligibility (JSON)
  2. Eligibility Transactions / Get Transaction By Id
  3. Eligibility Transactions / Get All Transactions
  4. If enabled, Coverage Discovery / Submit Discovery Dry Run (JSON)
  5. If a discovery task is created, Coverage Discovery / Get Discovery By Id

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.

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

  1. Open Insomnia.
  2. Click Create or Import.
  3. Choose the option to import from clipboard, raw text, or pasted JSON.
  4. Copy the raw JSON for the Insomnia export and paste it into the import dialog.
  5. Complete the import.
  6. 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:

  1. Import the downloaded OpenAPI specification directly into Insomnia and configure OAuth 2.0 client credentials once.
  2. 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

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

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.

Option A: openapi-generator-cli

Install or use an existing local installation of OpenAPI Generator, then run:

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

Option B: npx

npx @openapitools/openapi-generator-cli generate \
  -i <downloaded-openapi-file> \
  -g python \
  -o generated/python

Option C: Docker

docker run --rm \
  -v "${PWD}:/local" \
  openapitools/openapi-generator-cli generate \
  -i /local/<downloaded-openapi-file> \
  -g java \
  -o /local/generated/java

Common generator targets

  • typescript-fetch
  • typescript-axios
  • python
  • java
  • csharp
  • go

Recommended wrapper workflow

  1. Generate into a dedicated generated/ directory.
  2. Wrap the generated client with your own thin service layer for:
    • retries
    • logging
    • correlation-id generation
    • optional subtenant header injection
  3. Regenerate from the spec when the API changes instead of hand-editing generated files.

What To Test First

For most customers, this order gives the fastest path to confidence:

  1. Submit a real-time eligibility JSON request
  2. Retrieve the transaction by id
  3. Submit a real-time X12 request if your workflow uses a JSON request body with x12 set to the X12 270 payload
  4. If enrolled in Coverage Discovery, start with dryRun=true
  5. Move to callback or polling workflows after the initial request/response path is working

Treat direct Coverage Discovery submission as an advanced follow-on test, not as the default first integration step.

How Coverage Discovery Appears In Real-Time Flows

For most customers, Coverage Discovery appears as a follow-up to the real-time eligibility flow rather than as a separate starting point.

When Coverage Discovery is part of your enrolled workflow, a real-time eligibility response may include related Coverage Discovery resources in the link header.

Example: Real-Time Response With Related Coverage Discovery Resource

POST /rcm/eligibility/v1
{
  "controlNumber": "123456789",
  "tradingPartnerServiceId": "AETNA",
  "provider": {
    "organizationName": "Example Medical Center",
    "npi": "0123456789"
  },
  "informationReceiverName": {
    "address": {
      "state": "TX"
    }
  },
  "subscriber": {
    "memberId": "SUB123",
    "firstName": "JOHN",
    "lastName": "DOE",
    "dateOfBirth": "19500102",
    "ssn": "111223333",
    "additionalIdentification": {
      "patientAccountNumber": "PAN-1001"
    }
  },
  "encounter": {
    "dateOfService": "20250115",
    "serviceTypeCodes": ["30"]
  }
}

200 OK
link: </coverage-discovery/cd-task-1001>; title="coverage discovery - Task 1"; rel="related"

{
  "id": "rte-patient-unknown-123",
  "payer": {
    "chcPayerId": "AETNA"
  },
  "status": {
    "value": "patient_unknown"
  }
}

Customers should store the related discovery task id from the link header and then use callbacks or GET /coverage-discovery/{id} to retrieve later results.

The important customer-visible behavior is the same across real-time request types: when a related discovery task is created, store the link header value and use it for later polling or callback reconciliation.

Coverage Discovery Tips

  • Use dryRun=true first when testing a new Coverage Discovery request.
  • callbackUrl is still required on Coverage Discovery request bodies even when dryRun=true. In dry-run mode the callback is not invoked, but the field must still be present for request validation.
  • A 202 Accepted response means the task was created and will complete asynchronously.
  • A 207 Multi-Status response means the request produced more than one per-task outcome.
  • If you use callback delivery, your callback endpoint must be whitelisted and idempotent.
  • If you poll instead of using callbacks, use the location header or returned task resource path and poll GET /coverage-discovery/{id} until the root status is no longer pending.
  • Most customers should rely on integrated Coverage Discovery triggered from real-time eligibility rather than posting discovery directly.
  • If you submit discovery directly, prefer the X12 endpoint unless you already have canonical request and response models available.
  • For proof-of-concept work, Optum may also be able to provide a batch file containing x12-271 responses produced by Real-Time Eligibility and/or Coverage Discovery while your polling or callback solution is still being built.

Direct JSON Discovery Notes

If you call POST /rcm/eligibility/v1/coverage-discovery directly with canonical models:

  • canonicalEligibilityRequest is always required
  • whether canonicalEligibilityResponse is also required depends on the enrolled workflow
  • if you are unsure which inputs are needed, confirm the required payload pattern with Optum before implementing direct JSON discovery

Use dryRun=true when validating new task configuration or when you want to confirm request acceptance without creating a live workflow result.

Polling Guidance

If you poll for discovery completion:

  • Poll by task id using GET /rcm/eligibility/v1/coverage-discovery/{id} rather than broad list searches whenever possible
  • Use a modest interval appropriate for long-running async work rather than aggressive short-interval polling
  • Compare pending duration to the expectations for your enrolled workflow before treating a task as abnormally delayed.
  • Escalate to support when a task remains pending beyond the expected window for your enrolled discovery paths or when callbacks and polling disagree about the final state

If your team needs a temporary stop-gap before async retrieval is ready, ask whether a secure batch file delivery option is available for your POC. This can be simpler than relying on extensive pagination across GET /transactions or GET /coverage-discovery in high-volume scenarios.

Deduplication

Customer-configured deduplication

  • deduplication can be enabled for Real-Time Eligibility and separately for selected Coverage Discovery paths
  • the customer chooses the lookback period in days
  • the customer may also choose whether prior-month requests are excluded
  • when a duplicate is found, the clearinghouse is skipped and the prior response is returned
  • transaction details can help you confirm that reuse occurred

List Endpoint Usage

Use list endpoints for operational search and recovery, not as a substitute for storing returned IDs.

  • GET /rcm/eligibility/v1/transactions is useful for searching by correlation ID, patient details, payer ID, date range, and status
  • GET /rcm/eligibility/v1/coverage-discovery is useful for searching by correlation ID, date range, and task status
  • Use x-total-count and pagination links where available for reporting and back-office workflows

Helpful Links

Feature-Specific Developer Notes

Use this section for API-visible behavior related to optional features. Use Value-Added Features for customer-facing feature descriptions and enrollment context.

Deduplication

  • if enrolled, deduplication can be disabled per request with x-optum-eligibility-disable-value-add: deduplication
  • transaction details can help you confirm whether customer-configured deduplication affected a request

Payer And Provider Identifiers

  • the request-side payer identifier used for eligibility submission is tradingPartnerServiceId
  • transaction and discovery response payloads may surface payer identity as chcPayerId
  • operational search endpoints also expose a payerId filter
  • continue sending the request-side provider fields defined in the request model even when NPI Management is enrolled

Coverage Discovery Path Inputs

  • direct JSON discovery requires canonicalEligibilityRequest
  • whether canonicalEligibilityResponse is also required depends on the enrolled workflow
  • when in doubt, confirm the expected direct-discovery payload with Optum before implementing

Coverage Insight And RTCOB Observable Behavior

  • when your workflow has a Patient Account Number, use patientAccountNumber
  • in the JSON request model, patientAccountNumber is subscriber.additionalIdentification.patientAccountNumber
  • in direct canonical discovery payloads, use canonicalEligibilityRequest.subscriber.additionalIdentification.patientAccountNumber
  • in X12, patientAccountNumber maps from loop 2100C or 2100D REF where REF01=EJ and the value is in REF02

Consolidated Callback

  • when enabled, the callback payload may include the abbreviated parent real-time transaction under realTime
  • use Customer Callback Example API for callback payload structure and field interpretation

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-subtenant-id", "value": "{{subtenant_id}}", "type": "text", "disabled": true }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"controlNumber\": \"123456789\",\n  \"tradingPartnerServiceId\": \"AETNA\",\n  \"provider\": {\n    \"organizationName\": \"Example Medical Center\",\n    \"npi\": \"0123456789\"\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. 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-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. 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\": \"0123456789\"\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
    }
  ],
  "_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"
      },
      "_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": "",
      "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  \"controlNumber\": \"123456789\",\n  \"tradingPartnerServiceId\": \"AETNA\",\n  \"provider\": {\n    \"organizationName\": \"Example Medical Center\",\n    \"npi\": \"0123456789\"\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-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. 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-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\": \"0123456789\"\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.

Updated 4 days ago

What’s Next