API & Services Connection ™
Guides
Request Sandbox AccessMarketplaceCommunity

Technical Reference Guide

The Optum Real APIs for Medical Providers Technical Reference Guide will contain all of the essential information the user will need to integrate with an API and serve as a ready reference source should you encounter a problem.

Note: This guide is intended to be referenced by information technology personnel.****

The Real Claim Inquiry API takes the standard X12 EDI 837 transaction. All API traffic is encrypted over HTTPS and authentication is handled with OAuth2.

Test API in sandbox or in production

  1. Use token generated using client ID and secret key for sandbox or production.
  2. Download API specs from overview page - every API overview section provides links to download the file in a JSON format, which generates our documentation for developers to use.
  3. Hit API endpoint through the following options:
  • Use Try It page to request complete API response or customize response for sandbox endpoint only.
    OR
  • Use Postman to request complete API response or customize response for Sandbox and Production API endpoint.

Sandbox use for live and mock data testing

  1. Customers must have purchased an API with status “subscribed” in the AI Marketplace account, please work with API consultant to associate provider TIN(s) before sending live data to sandbox environment.
  2. Customers must use their sandbox credentials to send live data to the sandbox environment for the API purchased.
    At this point, responses will be based on the live data submitted to the sandbox environment as opposed to mock data preloaded to the sandbox environment.
  3. The customer will retain the ability to query mock responses from a sandbox environment by using an optional request header called “environment”. By placing the value “sandbox" in the optional header, the request return mock responses.
    NOTE: Do not submit PHI or PII data in the TRY IT page.

Notes:
DO NOT perform load testing or production data testing in the sandbox environment. Please use the sandbox ONLY to view sample API responses to HTTP requests using our predefined values and to familiarize yourself with our APIs.

To perform load testing and production data testing, we recommend using our APIs in the production environment.

API endpoint

InstanceAPI EndpointDescription
Optum Real Claim Inquiry sandboxhttps://sandbox-apigw.optum.com/oihub/claim/inquiry/v1Use previously generated bearer token test API through this URL
Optum Real Claim Inquiry productionhttps://apigw.optum.com/oihub/claim/inquiry/v1Use previously generated production bearer token test API through this URL

HTTP response codes

CodeDescription
200Success response
401Unauthorized - authentication failed
500Internal server error - problem occurred on the server
400Bad request - includes schema level validation errors

Request Elements

Query ParameterTypeDescription
payerIdMandatoryFor all queries
documentIdConditionalOnly for GetDocument.
transactionIdConditionalOnly for Search277CA.
ticketTypeConditionalSpecify the Ticket Type like PEND or RECON or APPEAL.
claimNumberConditionalOnly needed for Search Claim by Claim #.
patientAccountNumberConditionalOnly needed for Search Claim by PAN.
memberIdConditionalOnly needed for Search Claim by Member.
memberFirstNameConditionalOnly needed for Search Claim by Member.
memberLastNameConditionalOnly needed for Search Claim by Member.
memberDateOfBirthConditionalOnly needed for Search Claim by Member.
memberPolicyConditionalOnly needed for Search Claim by Member.
serviceStartDateConditionalOnly needed for Search Claim by Member or Provider TIN.
serviceEndDateConditionalOnly needed for Search Claim by Member or Provider TIN.
coverageTypeOptionalDefault is Medical.
ticketNumberConditionalOnly for SearchClaimTicket by TicketNumber.
ticketFromDateConditionalOnly for SearchClaimTicket by a DOS range.
ticketToDateConditionalOnly for SearchClaimTicket by a DOS range.

Criteria by Operation

OperationDescriptionKey Parameters
SearchClaimRetrieve both summary and detailed information based on search parameters.Payer ID - Required
claimNumber (Only needed for Search Claim by claimnumber.)
patientAccountNumber (Only needed for Search Claim by PAN.)

Below are only needed as input if search claim by member:
memberId
memberFirstName
memberLastName
memberDateOfBirth
serviceStartDate
serviceEndDate
SearchClaimTicketSearch for claim RECON or PEND or APPEALTickets based on Ticket Number or date range (30 days max range).
Note: 'attachmentList' in response will only be available for a ticket number search.		ticketType(Required)

Below are only needed as input if search claimticket by member:
ticketNumber
ticketFromDate and ticketToDate combinations
Search277CASearch for claim 277CA.transactionId (Required)

tin is Not Mandatory for this search
GetClaimLineActionRetrieve available actions at a service line level.claimActionIdentifier (Required)
lineKeys (Required)
GetDocumentDownload documentdocumentId (Required)

Supported Payer ID and Criteria

Payer IDMember ID + DOBPatient Account NumberClaim NumberProvider TIN + DOB
87726YYYY (except USP)
25463Y (Member FN, LN+ DOB)NNN
39026YYYN
74227Y (Member ID + DOB)NNN
LIFE1YNNN
WELM2YNNN
06111YYYN
96385YYYY
37602YYYY
03432YYYY
95467YYYY
86050YYYY
86047YYYY
95378YYYY

Query Sample for Request by Operation

Request OperationDescriptionQuery sample
SearchClaimRetrieve both summary and detailed information based on search parameters.{
"query": "query searchClaim($searchClaimInput: SearchClaimInput!) { searchClaimResponse(input: $searchClaimInput) {claims{ claimNumber claimReceiptLocatorNumber claimStatus hasClaimDetails member { subscriberId policyNumber firstName lastName dateOfBirth } provider { submitted{ billingTin billingProviderName billingNpi renderingProviderName } adjudicated{ billingTinPrefix billingTin billingTinSuffix billingProviderName billingNpi renderingProviderName } } claimEvents { receivedDate processedDate processedTime serviceStartDate serviceEndDate statusEffectiveDate } claimLevelInfo { patientAccountNumber claimType providerNetworkStatus claimFlagTag surpriseMedicalBillingIndicator surpriseMedicalBillingState } claimLevelTotalAmount { totalBilledChargeAmount totalProviderWriteOffAmount totalPatientNotCoveredAmount totalProviderNotCoveredAmount totalAllowedAmount totaldeductibleAmount totalCopayAmount totalCoinsAmount totalPaidAmount totalPatientResponsibilityAmount } payments { paymentNumber adjudicatedClaimPaymentNumber adjudicatedClaimPaymentAmount checkSeriesDesignator paymentModeCode paymentAmount paymentIssueDate claimPayeeAssignmentCode payeeName payeeAddress { addressLine cityName state zip } } claimStatusCrosswalkData{ claim507Code claim507CodeDesc claim508Code claim508CodeDesc adjudicatedClaimSuffixCode adjudicatedClaimPaymentNumber } claimAdjudicationCodes{ claimCodeType code description } documents { documentType documentCreatedDate documentReceivedDate documentName documentId } claimDetailedInformation{ claimNumber adjudicatedClaimSummaryStatus claimActionIdentifier allowedActions payerId coordinationOfBenefits{ cobPayerId claimOIPaidAmount otherInsuredName submittedCobIndicator cobPayerType cobDesc cobPolicyDesc cobPaymentType adjudicatedCobIndicator cobMedicalCalcType cobCommercialCalcType } diagnosisCodes{ diagnosisSequenceNumber diagnosisCode diagnosisCodeType } claimDetailEvents{ receivedDate initialDecisionDate lastDenialDate } claimLevelIndicators{ claimReprocessedIndicator paymentToEnrolleeCode isCapitationIndicator electronicPayerID placeOfService payerType } patientInfo{ patientName patientGroupNumber patientSubscriberNumber patientRelationship } claimLineActions{ ticketType allowedAction actionMessage allowedReconReasons requiredConsentForm note documentLink ticketDetails{ ticketNumber ticketSubmitDate ticketStatus ticketOutcome ticketReason isClosed lastUpdatedDate lastComment } } lines{ lineKey lineNumber unitCount serviceCode revenueCode linePaymentServiceCode procedureCode procedureTypeCode modifiers diagnosisPointers lineEvents { processedDate processedTime serviceStartDate serviceEndDate } lineLevelTotalAmounts{ billedChargeAmount notCoveredAmount providerNotCoveredAmount patientNotCoveredAmount providerWriteOffAmount allowedAmount deductibleAmount copayAmount coinsuranceAmount paidAmount memberResponsiblityAmount medicarePaidAmount reserveAmount qualifiedPaymentAmount } lineIndicators { inventoryControlNumberSuffix inventoryControlNumberSuffixVersion providerNetworkStatus transactionCode causeCode overrideCode planCoveragePercent capitationIndicator capFundType lineLevelPlaceOfService surpriseMedicalBillingIndicator surpriseMedicalBillingState providerGroupOfferPercentage } lineAdjudicationCodes { type code description } }} }pagination{ hasMoreRecords nextPageToken } } }",
"variables": {
"searchClaimInput": {
"claimNumber": "1234567890",
"patientAccountNumber": "1234567890",
"memberId": "1234567890",
"memberFirstName": "John",
"memberLastName": "Cena",
"memberDateOfBirth": "10/1/1975",
"memberPolicy": "002781",
"serviceStartDate": "01/01/2025",
"serviceEndDate": "10/01/2025",
"payerId": "87726"
}
},
"operationName": "searchClaim"
}
SearchClaimTicketSearch for claim RECON or PEND or APPEAL tickets based on Ticket Number or date range (30 days max range).
Note: 'attachmentList' in response will only be available for a ticket number search.		{
"query": "query searchClaimTicket($searchClaimTicketInput: SearchClaimTicketInput!) { searchClaimTicketResponse(input: $searchClaimTicketInput) { ticketDetails{ ticketNumber ticketStatus ticketSubmitDate ticketType lastUpdatedDate isClosed ticketOutcome ticketReason } comments{ addedBy addedOn comment } claimInfo { claimNumber isOwedAmountUnknown claimAmountOwed totalBilledChargedAmount claimStatus serviceStartDate patientAccountNumber claimType inventoryControlNumber } member { memberId dateOfBirth firstName middleInitial lastName policyNumber relationshipCode dependentSequenceNumber } provider{ adjudicated{ billingTin billingProviderName billingProviderMpin renderingProviderName renderingProviderMpin } } operatorInfo{ name emailId phoneNumber } payerInfo { payerName payerId } attachmentList{ ticketNumber ticketType fileName reportTypeCode reportTypeDesc documentId } }}",
"variables": {
"searchClaimTicketInput": {
"ticketNumber": "840868613",
"ticketType": "RECON",
"ticketFromDate": "2020-07-27",
"ticketToDate": "2020-08-27",
"payerId": "87726"
}
},
"operationName": "searchClaimTicket"
}
Search277CASearch for claim 277CA.{
"query": "query search277CA($search277CAInput: Search277CAInput!) { search277CAResponse(input: $search277CAInput) { responseType x12ResponseData statuscode message }}",
"variables": {
"search277CAInput": {
"transactionId": "840868613",
"payerId": "87726"
}
},
"operationName": "search277CA"
}
GetClaimLineActionRetrieve available actions at a service line level.{
"query": "query getClaimLineAction($claimLineActionInput: GetClaimLineActionInput!) { getClaimLineActionResponse(input: $claimLineActionInput) { claimLineActions { ticketType allowedAction actionMessage allowedReconReasons requiredConsentForm note documentLink ticketDetails { ticketNumber ticketStatus ticketSubmitDate ticketOutcome } } } }",
"variables": {
"claimLineActionInput": {
"claimActionIdentifier": "840868613",
"payerId": "87726",
"lineKeys": [
"1",
"2",
"5"
]
}
GetDocumentDownload document{
"query": "query getDocument($documentInput: GetDocumentInput!) { getDocumentResponse(input: $documentInput) { base64Document }}",
"variables": {
"documentInput": {
"documentID": "840868613",
"payerId": "87726"
}
},
"operationName": "getDocument"
}

Sample Response by Operation

Response DescriptionQuery response
SearchClaimTicketSearch for claim RECON or PEND or APPEAL Tickets based on Ticket Number or date range (30 days max range).
Note: 'attachmentList' in response will only be available for a ticket number search.		{
"data": {
"searchClaimTicketResponse": [
{
"ticketDetails": {
"ticketNumber": "RECON-001",
"ticketStatus": "Under Review",
"ticketSubmitDate": "07/27/2020",
"ticketType": "RECON",
"lastUpdatedDate": "07/27/2020",
"isClosed": false,
"ticketOutcome": "",
"ticketReason": ""
},
"comments": [
{
"addedBy": "Claim Specialist",
"addedOn": "05/04/2025",
"comment": "Review of this claim concluded that the claim processed appropriately according to the terms of the patient's health benefit plan. Questions? We're here to help. For more information about this claim decision, including a link to the applicable reimbursement policies, you can use the member info to search for this or any related claims. Once you've located your claim, in the CLAIM DETAILS - LINE ITEMS section, select 'view' under the details column."
},
{
"addedBy": "System",
"addedOn": "04/07/2025",
"comment": "Under Review"
}
],
"claimInfo": {
"claimNumber": "12344455",
"isOwedAmountUnknown": false,
"claimAmountOwed": "123.45",
"totalBilledChargedAmount": "46.00",
"claimStatus": "F",
"serviceStartDate": "06/01/2025",
"patientAccountNumber": "A12345",
"claimType": "P",
"inventoryControlNumber": "AB12345678"
},
"member": {
"memberId": "483865773",
"dateOfBirth": "09/16/1965",
"firstName": "John",
"lastName": "Cena",
"middleInitial": "A",
"policyNumber": "01234",
"relationshipCode": "EE",
"dependentSequenceNumber": "01"
},
"provider": {
"adjudicated": {
"billingTin": "483865773",
"billingProviderName": "Hospital Central",
"billingProviderMpin": "123345645",
"renderingProviderName": "Dr John",
"renderingProviderMpin": "123345645"
}
},
"operatorInfo": {
"name": "Cari Helly",
"emailId": "[email protected] ",
"phoneNumber": "91312121212"
},
"payerInfo": {
"payerName": "UnitedHealthcare",
"payerId": "UHC001"
},
"attachmentList": [
{
"ticketNumber": "PIQ-1234561",
"ticketType": "RECON",
"fileName": "2021-TEST-Calendar-United-States.pdf",
"reportTypeCode": "OZ",
"reportTypeDesc": "Support Data for Claim",
"documentId": "111111-11111-111-11-11111c79%attach_2021-11_v1~~~"
},
{
"ticketNumber": "PIQ-1234562",

"ticketType": "RECON", "fileName": "2021-TEST-Calendar-United-States2.pdf", "reportTypeCode": "OZ", "reportTypeDesc": "Support Data for Claim", "documentId": "111111-111112-111-11-11111c79%attach_2021-11_v1~~~" } ] } ] }
}
Search277CASearch for claim 277CA.{
"data": {
"search277CAResponse": {
"responseType": "277CA-CH",
"x12ResponseData": "X12RESPONSEDATA",
"statuscode": "000",
"message": ""
}
}
}
GetClaimLineActionRetrieve available actions at a service line level.claimActionIdentifier (required)
lineKeys (required)

{
"data": {
"getClaimLineActionResponse": {
"claimLineActions": [
{
"ticketType": "Recon",
"allowedAction": "create",
"actionMessage": "disallowed action message",
"allowedReconReasons": [
"RECON_REASON_1",
"RECON_REASON_2"
],
"requiredConsentForm": null,
"note": null,
"documentLink": null,
"ticketDetails": []
},
{
"ticketType": "Appeal",
"allowedAction": "create",
"actionMessage": "disallowed action message",
"allowedReconReasons": [],
"requiredConsentForm": "AOR",
"note": "Consent form is required only when the appeal is submitted on behalf of member.",
"documentLink": "https://maelstrom-dmz-nonprod.uhcprovider.com/cdn/uhcp/documents/claims/appeal-messaging/WOL.pdf",
"ticketDetails": [
{
"ticketNumber": "1234567890",
"ticketStatus": "",
"ticketSubmitDate": "06/06/2021",
"ticketOutcome": ""
}
]
}
]
}
}
}
GetDocumentDownload documentdocumentId (required)
{
"data": {
"getDocumentResponse": {
"base64Document": ""
}
}
}

Updated 11 days ago