Sandbox Mock Scenarios

Use this guide when you want a canned Sandbox response for Enhanced Eligibility real-time (RTE) testing.

You do not need to know any predefined payer test values before starting. Pick one test case from the scenario table, copy the scenario header, and send the payer id shown in that row. The same scenario header can be used for either the JSON endpoint or the X12 endpoint.

Do not send PHI in Sandbox. All examples and responses are fake data for developer testing.

Quick Start

Sandbox supports two canned-response testing methods:

The rest of this guide focuses on scenario-header mocks.

For scenario-header mocks, only these requirements control the canned test flow:

All other request details are accepted as valid test input, but they may not appear in the response. The response body is canned. Subscriber, dependent, benefit, payer, and Coverage Discovery details may come from the selected mock scenario instead of from your request.

The sample names and member values in this guide are stable Sandbox test values and align with supported Medical Network Sandbox predefined values. Relationship values such as SELF are determined in the Enhanced Eligibility response; you do not need to send them in the request.

Request Options

Choose the request format you want to test.

Use only one row from the Scenario Table per request. The same scenario header works for both request formats. The scenario header and payer id must come from the same row.

Required Mock Header

Send this header in Sandbox:

x-optum-rcmelig-mock-scenarios: <scenario-header-value>

Rules:

• The value is case-sensitive.
• Use it only in Sandbox.
• Do not combine values from different scenario rows.
• The selected scenario controls the canned response outcome.

JSON Request

Use this format when you are sending normalized JSON.

Endpoint:

POST /rcm/eligibility/v1

Minimal subscriber-only request body:

{
  "tradingPartnerServiceId": "SB900",
  "provider": {
    "organizationName": "Example Medical Center",
    "npi": "1234567893"
  },
  "subscriber": {
    "memberId": "0000000005",
    "firstName": "JANEONE",
    "lastName": "DOEONE",
    "dateOfBirth": "1880-01-02",
    "address": {
      "address1": "123 Test Street",
      "city": "Dallas",
      "state": "TX",
      "postalCode": "75001"
    }
  },
  "encounter": {
    "dateOfService": "20260115",
    "serviceTypeCodes": [
      "30"
    ]
  }
}

For JSON tests, change tradingPartnerServiceId to the payer id from the scenario row you selected.

For dependent or spouse scenarios, you can include a dependent object so your request shape matches the scenario you are testing:

{
  "tradingPartnerServiceId": "SB900",
  "provider": {
    "organizationName": "Example Medical Center",
    "npi": "1234567893"
  },
  "subscriber": {
    "memberId": "0000000005",
    "firstName": "JANEONE",
    "lastName": "DOEONE",
    "dateOfBirth": "1880-01-02",
    "address": {
      "address1": "123 Test Street",
      "city": "Dallas",
      "state": "TX",
      "postalCode": "75001"
    }
  },
  "dependents": [
    {
      "memberId": "1111111111",
      "firstName": "JohnTwo",
      "lastName": "DoeOne",
      "dateOfBirth": "20120505"
    }
  ],
  "encounter": {
    "dateOfService": "20260115",
    "serviceTypeCodes": [
      "30"
    ]
  }
}

The dependent details above help your test request look like the scenario. The response is still canned and may not echo those values.

X12 Request

Use this format when you are sending an X12 270.

Endpoint:

POST /rcm/eligibility/v1/real-time/x12

Request body shape:

{
  "x12": "ISA*00*...~IEA*1*900000001~"
}

The request body is JSON. The x12 field contains the full X12 270 as a string.

Inside the X12 270, send the payer id in the payer NM1 segment:

NM1*PR*2*<PAYER NAME>*****PI*<payer id>~

Minimal X12 example using payer id SB900:

{
  "x12": "ISA*00*          *01*SomePwd   *ZZ*TPG00000       *ZZ*RECEIVER       *260101*1201*^*00501*900000001*0*T*:~GS*HS*SUBMITTER*RECEIVER*20260101*1201*900000001*X*005010X279A1~ST*270*900000001*005010X279A1~BHT*0022*13*123456789*20260101*120101~HL*1**20*1~NM1*PR*2*TEXAS BLUE CROSS BLUE SHIELD*****PI*SB900~HL*2*1*21*1~NM1*1P*2*EXAMPLE PROVIDER*****XX*1234567893~HL*3*2*22*0~NM1*IL*1*DOEONE*JANEONE****MI*0000000005~N3*123 TEST STREET~N4*DALLAS*TX*75001~DMG*D8*18800102*F~DTP*291*D8*20260115~EQ*30~SE*14*900000001~GE*1*900000001~IEA*1*900000001~"
}

For X12 tests, change only the payer id in PI*<payer id> unless the scenario row lists extra request data.

For dependent or spouse scenarios, include dependent patient loops if your test needs to match that request shape. The response is still canned and may not echo the submitted dependent values.

Scenario Table

Pick one row. Send the scenario header in x-optum-rcmelig-mock-scenarios and send the payer id shown in the row. The same scenario header can be used for either JSON or X12 requests.

• Coverage Discovery link headers are returned only when your Sandbox product is configured for Coverage Discovery.

Coverage Discovery Link Header

Scenarios marked Yes in the Coverage Discovery Link Header* column return a Coverage Discovery link header when your Sandbox product is configured for Coverage Discovery.

The link response header contains one or more related Coverage Discovery task URLs.

The linked Coverage Discovery response is asynchronous. It is not returned inside the first Enhanced Eligibility RTE response body.

To retrieve the Coverage Discovery response, read the task path from the link header and call:

GET /rcm/eligibility/v1/coverage-discovery/{id}

Example Enhanced Eligibility RTE response header:

link: </coverage-discovery/0716e3e8-87ee-11ee-b9d1-0242ac120002>; title="coverage discovery - Task 1"; rel="related"

Use the id from the linked path in the retrieval request:

GET /rcm/eligibility/v1/coverage-discovery/0716e3e8-87ee-11ee-b9d1-0242ac120002

If the link header contains more than one /coverage-discovery/{id} path, call the retrieval endpoint once for each id.

Expected Fake Member Story

These mock responses return fixed fake member stories:

• Spouse scenarios return subscriber JANEONE DOEONE and spouse/patient JOHNTWO DOEONE.
• Dependent child scenarios return subscriber JANEONE DOEONE and child/patient JOHNTWO DOEONE.
• Self scenarios using JANEONE return gender F.
• Self scenarios using JOHNONE return gender M.

The returned names, birth dates, gender values, payer names, benefit details, and Coverage Discovery results are canned. They may not match every field in your request.

The payer id you submit is the main request value reflected back in the response. JSON tradingPartnerServiceId or X12 payer PI is persisted as chcPayerId.

Other Sandbox Test Values

The JSON and X12 real-time endpoints also support standard Optum Medical Network Sandbox predefined canned values. These are separate from the scenario-header values in this guide.

Use the Medical Network Sandbox docs when you want those predefined values:

• Sandbox predefined fields and values
• Eligibility Sandbox API values and test responses

For JSON requests, send the documented values in the matching JSON fields, including tradingPartnerServiceId.

For X12 requests, send the documented values in the matching X12 270 segments. The payer id still goes in the payer NM1 segment's PI value.

Use only one Sandbox mock method per request:

Troubleshooting

If you do not get the expected mock response, check these items first: