openapi: 3.0.0
info:
version: 1.0.0
description: 'Pre-service Benefit Check API: Prior Auth, Benefit Coverages, and Referral Inquiry for
member services'
title: Benefit Check API
servers:
- url: https://sandbox-apigw.optum.com
paths:
/oihub/patient/benefit/check/v1:
post:
security:
- oAuth:
- read_healthcheck
operationId: benefitCheck
tags:
- Benefit Check
parameters:
- name: providerTaxId
in: header
description: Provider Tax ID
required: true
schema:
type: string
example: '123456789'
- name: x-optum-consumer-correlation-id
in: header
description: Unique UUID to track the transaction
required: false
schema:
type: string
example: 4d4a8964-e5fa-42dc-a37d-12345789
- name: environment
in: header
description: Environment
required: false
schema:
type: string
example: sandbox
requestBody:
content:
application/json:
schema:
description: Example for Benefit Check covering Prior Auth
properties:
operationName:
type: string
description: Name of the GraphQL operation to execute (e.g., CheckPriorAuthBenefitCoverage
query:
type: string
description: GraphQL query
variables:
description: Variables for the GraphQL query
type: object
properties:
benChkInput:
type: object
properties:
beneficiaryDetail:
description: Details of the beneficiary
$ref: '#/components/schemas/BeneficiaryDetailInput'
serviceLocation:
description: Service Location
$ref: '#/components/schemas/ServiceLocationInput'
caseDetailProvider:
description: Case Detail Provider
items:
$ref: '#/components/schemas/CaseDetailProviderInput'
type: array
diagnosisCodes:
description: Diagnosis codes
items:
$ref: '#/components/schemas/DiagnosisCodesInput'
type: array
facilityServiceDetail:
description: Facility service detail
$ref: '#/components/schemas/FacilityServiceDetailInput'
payerId:
description: Payer Id
example: '12345'
type: string
required:
- payerId
- facilityServiceDetail
- diagnosisCodes
- beneficiaryDetail
- serviceLocation
- caseDetailProvider
refInqInput:
type: object
properties:
beneficiaryDetail:
description: Details of the beneficiary
$ref: '#/components/schemas/BeneficiaryDetailInput'
providerDetail:
description: Details of the provider
$ref: '#/components/schemas/ProviderDetailInput'
payerId:
description: Payer Id
example: '12345'
type: string
required:
- payerId
- beneficiaryDetail
- providerDetail
benLangInput:
type: object
properties:
beneficiaryDetail:
description: Transaction ID from eligibility or benefit category lookup.
$ref: '#/components/schemas/BeneficiaryDetailInput'
eligibilityTransactionId:
description: Transaction ID returned from eligibility or Benefit Category operation
(Conditionally Required)
example: abcdefg
type: string
benefitId:
description: Benefit Id
example: ben-a111-b222-c333
type: string
payerId:
description: Payer Id
example: '12345'
type: string
required:
- payerId
- benefitId
benCatgInput:
type: object
properties:
beneficiaryDetail:
description: Details of the beneficiary
$ref: '#/components/schemas/BeneficiaryDetailInput'
searchPhrase:
description: Search Phrase
example: MRI
type: string
payerId:
description: Payer Id
example: '12345'
type: string
required:
- payerId
- beneficiaryDetail
type: object
required:
- query
- variables
examples:
ClaimBenefits:
summary: ClaimBenefits
value:
operationName: CheckPriorAuthBenefitCoverage
query: 'query CheckPriorAuthBenefitCoverage($benChkInput: CheckPriorAuthBenefitCoverageInput!)
{ checkPriorAuthBenefitCoverage(benChkInput: $benChkInput) { caseOutcome { casePriorAuth
{ requestMessages { messageText } requestOutcomeCode requestOutcomeCodeDescription
requestReferenceNumber } } caseSummary { member { groupNumber memberId } placeOfServiceCode
requestingProviderNPI requestingProviderTin } matchedPriorAuths { caseDecision caseServices
{ procedureCode serviceDecision serviceMessage } caseStatus serviceReferenceNumber
} serviceOutcomes { procedureCode procedureCodeDescription servicePriorAuth { isPriorAuthOnFile
messages { messageText } serviceOutcomeCode } } } }'
variables:
benChkInput:
beneficiaryDetail:
beneficiaryId: M123456789
dateOfBirth: '1985-06-15'
firstName: John
lastName: Doe
groupNumber: G123456
serviceStartDate: '2023-01-01'
serviceEndDate: '2023-01-01'
serviceLocation:
placeOfServiceCode: '11'
claimType: I
serviceDetail: Medical
serviceDescription: Scheduled
caseDetailProvider:
- providerType: Physician
providerTaxIdNumber: '123456789'
providerNPI: '9876543210'
providerFirstName: John
providerLastOrOrganizationName: Doe Clinic
address:
line1: 1234 CHARDAVE
line2: ''
city: Hastings
state: TX
zip: '12133'
zip4: '1001'
providerRoles:
- role: Requesting
procedureDetails:
- procedureCode: '99213'
codeType: CPT
isPrimary: true
serviceStartDate: '2025-08-01'
serviceEndDate: '2025-08-01'
diagnosisCode: J01.90
procedureUnitPerFrequencyCount: '1'
procedureUnitOfMeasure: UN
procedureFrequency: '1'
procedureUnitCount: '1'
procedureBilledChargeAmount: '100'
serviceDetailDescription: Medical
diagnosisCodes:
- diagnosisTypeCode: ABK
diagnosisCode: J01.90
facilityServiceDetail:
facilityServiceStartDate: '2025-08-01'
facilityServiceEndDate: '2025-08-01'
isPatientAdmitted: false
isPatientDischarged: false
payerId: '12345'
ReferralInquiry:
summary: ReferralInquiry
value:
operationName: ReferralInquiry
query: 'query ReferralInquiry($refInqInput: CheckReferralInquiryInput!) { referralInquiry(refInqInput:
$refInqInput) { referralIndicator } }'
variables:
refInqInput:
beneficiaryDetail:
beneficiaryId: M123456789
dateOfBirth: '1985-06-15'
firstName: John
lastName: Doe
groupNumber: G123456
serviceStartDate: '2023-01-01'
serviceEndDate: '2023-01-01'
providerDetail:
providerLastOrOrganizationName: Doe Clinic
providerFirstName: John
providerNPI: '9876543210'
payerId: '12345'
PlanBenefitLanguage:
summary: BenefitLanguage
value:
operationName: CheckPlanBenefitLanguage
query: 'query CheckPlanBenefitLanguage($benLangInput: CheckPlanBenefitLanguageInput!)
{ checkPlanBenefitLanguage(benLangInput: $benLangInput) { newBenefits benefits { benefitName
benefitDetails benefitInformationSection benefitNetworkSection { costs networkStatus
} limitsAndExceptions { description details } } } }'
variables:
benLangInput:
beneficiaryDetail:
beneficiaryId: M123456789
dateOfBirth: '1985-06-15'
firstName: John
lastName: Doe
groupNumber: G123456
serviceStartDate: '2023-01-01'
serviceEndDate: '2023-01-01'
eligibilityTransactionId: abcdefg
benefitId: ben-a111-b222-c333
payerId: '12345'
PlanBenefitCategory:
summary: BenefitCategory
value:
operationName: CheckPlanBenefitCategory
query: 'query CheckPlanBenefitCategory($benCatgInput: CheckPlanBenefitCategoryInput!)
{ checkPlanBenefitCategory(benCatgInput: $benCatgInput) { eligibilityTransactionId
newBenefits benefitCategory { categoryName categoryDetail { benefitId benefitName
benefitSummaryText } } } }'
variables:
benCatgInput:
beneficiaryDetail:
beneficiaryId: M123456789
dateOfBirth: '1985-06-15'
firstName: John
lastName: Doe
groupNumber: G123456
serviceStartDate: '2023-01-01'
serviceEndDate: '2023-01-01'
searchPhrase: MRI
payerId: '12345'
required: true
responses:
'200':
content:
application/json:
examples:
BenefitCheckResponse:
summary: ClaimBenefits
value:
data:
checkPriorAuthBenefitCoverage:
caseOutcome:
casePriorAuth:
requestMessages:
- messageText: Prior authorization required for the requested service
requestOutcomeCode: '1'
requestOutcomeCodeDescription: Authorization Required
requestReferenceNumber: REQ123456789
caseSummary:
member:
groupNumber: M123456789
memberId: G123456
placeOfServiceCode: '11'
requestingProviderNPI: '9876543210'
requestingProviderTin: '123456789'
matchedPriorAuths:
- caseDecision: Approved
caseServices:
- procedureCode: '99213'
serviceDecision: Approved
serviceMessage: Prior authorization valid through 2025-12-31
caseStatus: Closed
serviceReferenceNumber: AUTH123456
serviceOutcomes:
- procedureCode: '98941'
procedureCodeDescription: Chiropractic adjustment involving 3-4 areas of the
spine
servicePriorAuth:
isPriorAuthOnFile: false
messages:
- messageText: Prior authorization required for the requested service
serviceOutcomeCode: '1'
ReferralInquiryResponse:
summary: ReferralInquiry
value:
data:
referralInquiry:
referralIndicator: Y
BenefitLanguageResponse:
summary: PlanBenefitLanguage
value:
data:
checkPlanBenefitLanguage:
newBenefits: true
benefits:
benefitName: Hearing Aids
benefitDetails: 'What are hearing aids: Electronic amplifying devices designed
to bring sound more effectively into the ear.'
benefitInformationSection:
- text
benefitNetworkSection:
- costs: 'UHC Network: co-insurance after you pay the deductible. Is prior-auth
needed? No'
networkStatus:
- Your cost if you use Network benefits
limitsAndExceptions:
- description: General
details: No coverage for bone anchored hearing aids except Craniofacial anomalies.
BenefitCategoryResponse:
summary: PlanBenefitCategory
value:
data:
checkPlanBenefitCategory:
eligibilityTransactionId: abcdefg
newBenefits: true
benefitCategory:
- categoryName: MRI services
categoryDetail:
- benefitId: abc2fe-89b57
benefitName: X-Ray
benefitSummaryText: UnitedHealthcare X-Ray Program
schema:
type: object
properties:
data:
type: object
properties:
checkPlanBenefitLanguage:
$ref: '#/components/schemas/BenefitLanguageResponse'
checkPriorAuthBenefitCoverage:
$ref: '#/components/schemas/BenefitCheckResponse'
checkPlanBenefitCategory:
$ref: '#/components/schemas/BenefitCategoryResponse'
referralInquiry:
$ref: '#/components/schemas/ReferralInquiryResponse'
errors:
items:
type: object
properties:
code:
type: string
description: Error code identifying the specific error
description:
type: string
description: Detailed error message
description: List of errors if occurred during Benefit Check
type: array
description: "ClaimBenefits\n
\n - MISSING_REQUIRED_FIELD\n
\n \
\ - Missing mandatory header field: XXXXX
\n - Missing mandatory requestField:\
\ XXXXX
\n
\n \n - INVALID_FIELD\n
\n - Invalid\
\ field: XXXXX
\n - Missing or invalid information: XXXXX
\n
\n \n\
\ - INTERNAL_SERVER_ERROR\n
\n - An unexpected error occurred while\
\ processing the request
\n
\n \n - BAD_USER_INPUT\n
\n\
\ - Variable \"$benChkInput\" got invalid value { beneficiaryId: \"123456\", dateOfBirth:\
\ \"1976-08-27\", firstName: \"\", lastNamee: \"\", groupNumber: \"NMOFEX\", familyIndicator:\
\ \"Y\", serviceStartDate: \"2024-01-20\", serviceEndDate: \"2024-01-20\" } at \"benChkInput.beneficiaryDetail\"\
; Field \"lastNamee\" is not defined by type \"BeneficiaryDetailInput\". Did you mean \"lastName\"\
\ or \"firstName\"?
\n
\n \n
\n
\nReferralInquiry\n\n\
\ - VALIDATION_FAILED\n
\n - Invalid format: dateOfBirth
\n \
\ - Invalid format: Service Start Date
\n - Invalid format: Service End Date
\n\
\ - Need additional inputs to perform the search
\n - Invalid Coverage type
\n\
\ - Incorrect Timeline indicator. Allowed values - 1,2,3,4.
\n - Start Date\
\ must be within 6 years and End date should not exceed more than 1 year.
\n - Last\
\ Date of Service must be on or after the First Date of Service.
\n - Provider\
\ LastName Missing.
\n - One of Provider NPI, Provider Tax ID, or Provider MPIN\
\ must be provided
\n - Start Date must be within 7 years and End date should not\
\ exceed more than 1 year.
\n - Search by name and DOB is not allowed for AARP\
\ members. Please enter a member ID to proceed.
\n - Bad request - Your search\
\ period is greater than 12 months.
\n - Platform not supported for the consumer.
\n\
\ - Missing serviceStartDt. serviceStartDt and serviceEndDt are required to proceed\
\ with the search.
\n - Missing serviceEndDt. serviceStartDt and serviceEndDt are\
\ required to proceed with the search.
\n - To check eligibility and benefit information\
\ for USHG please visit https//provider.ushealthgroup.com or call 866-745-8744 to speak with\
\ a customer service representative.
\n - Missing Group Number. Group Number is\
\ required to proceed with the search.
\n - Missing Plan Benefit Type. Plan Benefit\
\ Type is required to proceed with the search.
\n - Missing Plan Business Division\
\ Code. Plan Business Division Code is required to proceed with the search.
\n - Missing\
\ Network ID. Network ID is required to proceed with the search.
\n - Missing Plan\
\ Code. Plan Code is required to proceed with the search.
\n - Missing Plan Variation\
\ Code. Plan Variation Code is required to proceed with the search.
\n - Missing\
\ Plan Product Code. Plan Product Code is required to proceed with the search.
\n \
\ - Missing IPA Number. IPA Number is required to proceed with the search.
\n \
\ - Missing Source System Code. Source System Code is required to proceed with the search\
\ to get delegatedInfo.
\n - Missing serviceStartDt or serviceEndDt. serviceStartDt\
\ and serviceEndDt are required to proceed with the search.
\n - FirstName, LastName,\
\ MemberId and DateOfBirth is mandatory when Policy number is available.
\n - Member\
\ not found.
\n - Member not found – Empty response from Identity backend service.
\n\
\ - Member not found - Partial response.
\n - Member not found - Policy\
\ unavailable.
\n - Member not found - No Data Found in backend service.
\n\
\ - Member not found - No Data found for the selected date range search.
\n \
\ - Multiple Member found - Please refine your search.
\n - Query Validation\
\ Error.
\n - No member found.
\n - No Policy found in the given date\
\ range.
\n - This plan is administered by a different payer. The payer ID is {payer\
\ ID}. (Non-AARP)
\n - This plan is administered by a different payerId. (For AARP)
\n\
\ - Member not found - General Exception.
\n - Found Multiple Identity API\
\ Identifier.
\n - This plan is administered by USN01.Please confirm Payer Name/Payer\
\ ID and resubmit your request for quickest results.
\n
\n \n - MISSING_REQUIRED_FIELD\n\
\
\n - Missing mandatory header field:XXXXX
\n - Missing mandatory\
\ required field:XXXXX
\n
\n \n - INVALID_FIELD\n
\n \
\ - Invalid date format, please submit yyyy-MM-dd format
\n - unsupported\
\ Payer ID,please verify and re-submit
\n
\n \n - INTERNAL_SERVER_ERROR\n\
\
\n - System Unavailable at this time. Please try again later
\n
\n\
\ \n - BAD_USER_INPUT\n
\n - Variable \"$benChkInput\" got invalid\
\ value { beneficiaryId: \"123456\", dateOfBirth: \"1976-08-27\", firstName: \"\", lastNamee:\
\ \"\", groupNumber: \"NMOFEX\", familyIndicator: \"Y\", serviceStartDate: \"2024-01-20\"\
, serviceEndDate: \"2024-01-20\" } at \"benChkInput.beneficiaryDetail\"; Field \"lastNamee\"\
\ is not defined by type \"BeneficiaryDetailInput\". Did you mean \"lastName\" or \"firstName\"\
?
\n
\n \n
\n
\nPlanBenefitCategory\n\n - VALIDATION_FAILED\n\
\
\n - Invalid transaction id
\n - One of the mandatory field(s)\
\ is passed as blank in the request
\n - No Policy Found
\n - No Members\
\ Found.
\n - Invalid benefitId.
\n - B360 Summary Benefit Categories\
\ not found.
\n - Benefit Category not found.
\n - The date is not in\
\ a valid format. Please enter it in the yyyy-MM-dd format
\n - Bad request or\
\ missing required parameters in request
\n - No unique member found and unable\
\ to derive platform
\n - Multiple Members Found. Please refine Search
\n \
\ - Unknown or unsupported Platform. Please review your search criteria, including the\
\ Payer Name/Payer ID, and try again
\n - No members found for the given Member\
\ ID and Date of birth
\n - UHG Employee data - no access allowed to UHG intake\
\ user
\n - UHG Employee data - no access allowed to UHG internal user
\n \
\ - Please contact the United HealthCare Global customer service number on the back\
\ of the member's ID card or at 800-718-1293
\n - Bad request - missing mandatory\
\ attributes
\n - Invalid NPI
\n - Invalid TIN
\n - Bad request\
\ or Internal server error while fetching consumer data
\n - Bad request, blocked\
\ payer, dynamic error message from exception
\n - Bad request, blocked Cirrus\
\ payer, dynamic error message from exception
\n - This plan is administered by\
\ USN01. Please confirm Payer Name/Payer ID and resubmit your request for quickest results
\n\
\ - Dynamic error response from response body, related to bad request
\n - Invalid\
\ provider information
\n - Last Date of Service must be on or after the First\
\ Date of Service
\n - Multiple patients found for the given search criteria. Please\
\ enter the patient's Member ID number to get a unique result
\n - Date of Birth\
\ must be on or before the Date of Service
\n - Your search exceeds the date of\
\ service parameters for this plan. Plans are required to respond back for at least 18 months\
\ in the past and until the end of the current month. Please revise your Date of Service selections
\n\
\ - The date of birth you entered does not match our records. Please review your search\
\ criteria, including the Payer Name/Payer ID, and try again
\n - Please enter\
\ a valid Member ID
\n - A duplicate record was found, please change your search\
\ type to include the patient's first name
\n - Your search returned no results.\
\ Please review your search criteria, including the Payer Name/Payer ID, and try again
\n\
\ - A duplicate record was found, please change your search type to include the patient's\
\ first name or member ID
\n - Member eligibility is currently on hold and we are\
\ unable to process your request at this time. Please try again later
\n - An unexpected\
\ system error occurred while processing your request, please try your search again
\n\
\ - This plan is administered by a different payer. The payer ID is <payer ID>.\
\ (Non-AARP)
\n - This plan is administered by a different payer. (For AARP)
\n\
\ - Last Date of Service must be on or after the First Date of Service
\n \
\ - Multiple members found in the retrigger response
\n - No active policy found\
\ in the retrigger response
\n - No data found for the given NPI/TIN Combination
\n\
\ - Member was found, but there is no active coverage for the searched Dates of Service.\
\ Please enter new Dates of service and resubmit
\n - No matching Benefits found\
\ for searched phrase
\n - The date is not in a valid format. Please enter it in\
\ the yyyy-MM-dd format.
\n
\n \n - PARTIAL_DATA_RECEIVED\n \
\
\n - Your search returned no policies; however, policies were found outside\
\ of the entered date range. Please update the service dates and try again
\n
\n\
\ \n - MISSING_REQUIRED_FIELD\n
\n - Missing mandatory header\
\ field: XXXXX
\n - Missing mandatory required field: XXXX
\n
\n \n\
\ - INVALID_FIELD\n
\n - Invalid date format, please submit yyyy-MM-dd\
\ format
\n
\n \n - INTERNAL_SERVER_ERROR\n
\n - System\
\ Unavailable at this time. Please try again later
\n
\n \n - BAD_USER_INPUT\n\
\
\n - Variable \"$benChkInput\" got invalid value { beneficiaryId: \"123456\"\
, dateOfBirth: \"1976-08-27\", firstName: \"\", lastNamee: \"\", groupNumber: \"NMOFEX\",\
\ familyIndicator: \"Y\", serviceStartDate: \"2024-01-20\", serviceEndDate: \"2024-01-20\"\
\ } at \"benChkInput.beneficiaryDetail\"; Field \"lastNamee\" is not defined by type \"BeneficiaryDetailInput\"\
. Did you mean \"lastName\" or \"firstName\"?
\n
\n \n
\n
\nPlanBenefitLanguage\n\
\n - VALIDATION_FAILED\n
\n - Invalid transaction id
\n \
\ - One of the mandatory field(s) is passed as blank in the request
\n - No\
\ Policy Found
\n - No Members Found.
\n - Invalid benefitCode.
\n\
\ - B360 Detail Benefit Section not found.
\n - Benefit Category not found.
\n\
\ - The date is not in a valid format. Please enter it in the yyyy-MM-dd format.
\n\
\ - Additional coverage response failure
\n
\n \n - MISSING_REQUIRED_FIELD\n\
\
\n - Missing mandatory header field: XXXXX
\n - Missing mandatory\
\ required field: XXXXX
\n - Either of Member data attributes or eligibilityTransactionId\
\ is required input
\n
\n \n - INVALID_FIELD\n
\n \
\ - Invalid date format, please submit yyyy-MM-dd format
\n
\n \n - INTERNAL_SERVER_ERROR\n\
\
\n - System Unavailable at this time. Please try again later
\n - Stargate\
\ level Authorization failure.
\n
\n \n - BAD_USER_INPUT\n \
\
\n - Variable \"$benChkInput\" got invalid value { beneficiaryId: \"123456\"\
, dateOfBirth: \"1976-08-27\", firstName: \"\", lastNamee: \"\", groupNumber: \"NMOFEX\",\
\ familyIndicator: \"Y\", serviceStartDate: \"2024-01-20\", serviceEndDate: \"2024-01-20\"\
\ } at \"benChkInput.beneficiaryDetail\"; Field \"lastNamee\" is not defined by type \"BeneficiaryDetailInput\"\
. Did you mean \"lastName\" or \"firstName\"?
\n
\n \n
\n"
'400':
content:
application/json:
examples:
Schema Validation Errors:
summary: Schema Validation Errors
value:
errors:
- code: GRAPHQL_VALIDATION_FAILED
description: Cannot query field "serviceOutcomeCode" on type "matchedPriorAuths"
schema:
type: object
properties:
data:
type: object
properties:
checkPlanBenefitLanguage:
$ref: '#/components/schemas/BenefitLanguageResponse'
checkPriorAuthBenefitCoverage:
$ref: '#/components/schemas/BenefitCheckResponse'
checkPlanBenefitCategory:
$ref: '#/components/schemas/BenefitCategoryResponse'
referralInquiry:
$ref: '#/components/schemas/ReferralInquiryResponse'
errors:
items:
type: object
properties:
code:
type: string
description: Error code identifying the specific error
description:
type: string
description: Detailed error message
description: List of errors if occurred during Benefit Check
type: array
description: "\n - GRAPHQL_VALIDATION_FAILED\n
\n - Cannot query field\
\ on type
\n
\n \n - GRAPHQL_PARSE_FAILED\n
\n\
\ - Syntax Error: Unexpected }
\n
\n \n
\n"
'401':
content:
application/json:
examples:
Invalid authentication token:
summary: Invalid authentication token
value:
message: 'Authentication failed: Invalid or expired token'
description: 'Authentication failed: Invalid or expired token'
'500':
content:
application/json:
examples:
General server error:
summary: General server error
value:
errors:
- code: INTERNAL_SERVER_ERROR
description: An unexpected error occurred while processing the request
schema:
type: object
properties:
errors:
type: array
items:
type: object
properties:
code:
type: string
description:
type: string
description: Internal server error - Problem occurred on the server
'504':
content:
application/json:
examples:
General server error:
summary: General server error
value:
message: System Unavailable at this time. Please try again later
schema:
type: object
properties:
message:
type: string
description: Error message
description: 504 Gateway Time-out
components:
schemas:
BenefitCheckResponseDataWrapper:
type: object
properties:
data:
description: Benefit Check response wrapper.
$ref: '#/components/schemas/BenefitCheckResponseWrapper'
description: Benefit Check response data wrapper.
BenefitCheckInputDTO:
type: object
properties:
beneficiaryDetail:
description: Details of the beneficiary
$ref: '#/components/schemas/BeneficiaryDetailInput'
serviceLocation:
description: Service Location
$ref: '#/components/schemas/ServiceLocationInput'
caseDetailProvider:
description: Case Detail Provider
items:
$ref: '#/components/schemas/CaseDetailProviderInput'
type: array
diagnosisCodes:
description: Diagnosis codes
items:
$ref: '#/components/schemas/DiagnosisCodesInput'
type: array
facilityServiceDetail:
description: Facility service detail
$ref: '#/components/schemas/FacilityServiceDetailInput'
payerId:
description: Payer Id
example: '12345'
type: string
description: BenefitCheckInputDTO
ReferralInquiryResponseDataWrapper:
type: object
properties:
data:
description: Referral Inquiry response wrapper.
$ref: '#/components/schemas/ReferralInquiryResponseWrapper'
description: Referral Inquiry response data wrapper.
ReferralInquiryInputDTO:
type: object
properties:
beneficiaryDetail:
description: Details of the beneficiary
$ref: '#/components/schemas/BeneficiaryDetailInput'
providerDetail:
description: Details of the provider
$ref: '#/components/schemas/ProviderDetailInput'
payerId:
description: Payer Id
example: '12345'
type: string
description: Input for checking referral requirements.
BenefitLanguageResponseDataWrapper:
type: object
properties:
data:
description: Benefit Language response wrapper.
$ref: '#/components/schemas/BenefitLanguageResponseWrapper'
description: Benefit Language response data wrapper.
BenefitLanguageInputDTO:
type: object
properties:
beneficiaryDetail:
description: Transaction ID from eligibility or benefit category lookup.
$ref: '#/components/schemas/BeneficiaryDetailInput'
eligibilityTransactionId:
description: Transaction ID returned from eligibility or Benefit Category operation (Conditionally
Required)
example: abcdefg
type: string
benefitId:
description: Benefit Id
example: ben-a111-b222-c333
type: string
payerId:
description: Payer Id
example: '12345'
type: string
description: BenefitLanguageInputDTO
BenefitCategoryResponseDataWrapper:
type: object
properties:
data:
description: Benefit Category response wrapper.
$ref: '#/components/schemas/BenefitCategoryResponseWrapper'
description: Benefit Category response data wrapper.
BenefitCategoryInputDTO:
type: object
properties:
beneficiaryDetail:
description: Details of the beneficiary
$ref: '#/components/schemas/BeneficiaryDetailInput'
searchPhrase:
description: Search Phrase
example: MRI
type: string
payerId:
description: Payer Id
example: '12345'
type: string
description: Input for retrieving plan benefit categories.
ServiceOutcome:
type: object
properties:
procedureCode:
description: cpt/hcpcs service procedure code
example: '98941'
type: string
procedureCodeDescription:
description: Description of the procedure code
example: Chiropractic adjustment involving 3-4 areas of the spine
type: string
servicePriorAuth:
description: Prior authorization details for the service
$ref: '#/components/schemas/ServicePriorAuth'
description: Outcome details for a requested service
BenefitDetail:
type: object
properties:
benefitId:
description: Unique identifier for the benefit sub-category.
example: abc2fe-89b57
type: string
benefitName:
description: Name of the benefit sub-category.
example: X-Ray
type: string
benefitSummaryText:
description: Summary text explaining the benefit.
example: UnitedHealthcare X-Ray Program
type: string
description: Details of a specific benefit.
ProviderDetailInput:
type: object
properties:
providerLastOrOrganizationName:
description: Provider Last Name or Organization Name
example: Doe Clinic
type: string
providerFirstName:
description: Provider (physician) First Name. Optional for facility/institutional provider
example: John
type: string
providerNPI:
description: National Provider Identifier
example: '9876543210'
type: string
required:
- providerLastOrOrganizationName
description: Details of the provider for referral inquiry.
CaseOutcome:
type: object
properties:
casePriorAuth:
description: Prior authorization details for the case
$ref: '#/components/schemas/CasePriorAuth'
description: Outcome details for the benefit check case
CasePriorAuth:
type: object
properties:
requestMessages:
description: Messages related to the prior authorization request
items:
$ref: '#/components/schemas/Message'
type: array
requestOutcomeCode:
description: prior auth case outcome code (valid values:-1/2/3/4/5)
example: '1'
type: string
requestOutcomeCodeDescription:
description: Description of the outcome code
example: Authorization Required
type: string
requestReferenceNumber:
description: unique payer identifier assigned to prior auth case
example: REQ123456789
type: string
description: Details of the prior authorization request
ProviderRoleInput:
type: object
properties:
role:
description: Role of the provider (BI:Billing/Requesting; AT:Attending; SF:Servicing; FA:Facility)
example: Requesting
type: string
required:
- role
description: Role of the provider in the case.
FacilityServiceDetailInput:
type: object
properties:
facilityServiceStartDate:
description: First date of service or admission date. The Facility start date will default to
the current date. Services can be performed any time during this date range.
example: '2025-08-01'
type: string
facilityServiceEndDate:
description: Last date of service or discharge date. The Facility end date will default to 90
Days after the Facility Start Date. Services can be performed any time during this date range.
example: '2025-08-01'
type: string
isPatientAdmitted:
description: Boolean flag if patient is admitted. Required when OPF or IP, Optional for OP
example: false
type: boolean
isPatientDischarged:
description: Boolean flag if patient is discharged. Required when OPF or IP, Optional for OP
example: false
type: boolean
required:
- facilityServiceStartDate
- facilityServiceEndDate
description: Details of the facility service.
CaseService:
type: object
properties:
procedureCode:
description: Procedure code for which the prior auth was submitted
example: '99213'
type: string
serviceDecision:
description: Decision for the service.
example: Approved
type: string
serviceMessage:
description: Message related to the service decision.
example: Prior authorization valid through 2025-12-31
type: string
description: Details of a service in a matched prior authorization case
CaseDetailProviderInput:
type: object
properties:
providerType:
description: Provider entity type (Physician, Facility, Allied Ancillary)
example: Physician
type: string
providerTaxIdNumber:
description: Provider tax identification number
example: '123456789'
type: string
providerNPI:
description: National Provider Identifier
example: '9876543210'
type: string
providerFirstName:
description: Provider first name (Required for Physician, Conditional for Facility)
example: John
type: string
providerLastOrOrganizationName:
description: Provider Last Name or Organization Name
example: Doe Clinic
type: string
address:
description: Address of the provider
$ref: '#/components/schemas/AddressInput'
providerRoles:
description: Provider Role inputs
items:
$ref: '#/components/schemas/ProviderRoleInput'
type: array
procedureDetails:
description: Procedure Detail Input
items:
$ref: '#/components/schemas/ProcedureDetailsInput'
type: array
required:
- address.line1
- address.city
- address.state
- address.zip
- procedureDetails[].procedureCode
- procedureDetails[].diagnosisCode
- procedureDetails[].serviceDetailDescription
- providerRoles[].role
- providerType
- providerTaxIdNumber
- providerNPI
- providerLastOrOrganizationName
- address
- providerRoles
- procedureDetails
description: Details of the provider involved in the case.
AddressInput:
type: object
properties:
line1:
description: First line of street address
example: 1234 CHARDAVE
type: string
line2:
description: Second line of street address
type: string
city:
description: City
example: Hastings
type: string
state:
description: State code
example: TX
type: string
zip:
description: ZIP code
example: '12133'
type: string
zip4:
description: Extended ZIP+4 code
example: '1001'
type: string
required:
- line1
- city
- state
- zip
description: Address of the provider.
CheckPriorAuthBenefitCoverage:
type: object
properties:
caseOutcome:
description: Outcome of the benefit check case including prior authorization details
$ref: '#/components/schemas/CaseOutcome'
caseSummary:
description: Summary of the case including member and provider details
$ref: '#/components/schemas/CaseSummary'
matchedPriorAuths:
description: List of matched prior authorization cases
items:
$ref: '#/components/schemas/MatchedPriorAuths'
type: array
serviceOutcomes:
description: List of outcomes for each requested service
items:
$ref: '#/components/schemas/ServiceOutcome'
type: array
description: Response type for Benefit Check operation
ProcedureDetailsInput:
type: object
properties:
procedureCode:
description: Procedure code
example: '99213'
type: string
codeType:
description: Procedure Code type (CPT/HCPCS).
example: CPT
type: string
isPrimary:
description: Indicates if the procedure code is primary.
example: true
type: boolean
serviceStartDate:
description: Expected start date of the procedure. Conditional for IP/OPF.Required for OP
example: '2025-08-01'
type: string
serviceEndDate:
description: If applicable, a physician order may be required for the requested service dates.
Conditional for IP/OPF.Required for OP
example: '2025-08-01'
type: string
diagnosisCode:
description: Diagnosis code related to the service.
example: J01.90
type: string
procedureUnitPerFrequencyCount:
description: The number of times in the specified frequency time span the procedure will occur.
Conditional for IP/OPF.Required for OP
example: '1'
type: string
procedureUnitOfMeasure:
description: The assigned unit value of a particular CPT or HCPCS code (MJ=Minutes; UN=Units).
Conditional for IP/OPF.Required for OP.
example: UN
type: string
procedureFrequency:
description: The rate at which the Count can be billed during the date range (1=Weekly; 4=Monthly;
6=Daily). Conditional for IP/OPF.Required for OP
example: '1'
type: string
procedureUnitCount:
description: Procedure unit count. Conditional for IP/OPF.Required for OP
example: '1'
type: string
procedureBilledChargeAmount:
description: Line item charge amount for the service.
example: '100'
type: string
serviceDetailDescription:
description: Description of the nature of the service.
example: Medical
type: string
required:
- procedureCode
- diagnosisCode
- serviceDetailDescription
description: Details of the procedure being checked.
BenefitCategoryResponseWrapper:
type: object
properties:
checkPlanBenefitCategory:
description: Benefit Category response
$ref: '#/components/schemas/CheckPlanBenefitCategory'
description: Benefit Category response wrapper.
ServicePriorAuth:
type: object
properties:
isPriorAuthOnFile:
description: boolean field to suggest if an existing prior auth is found for the procedure code
example: false
type: boolean
messages:
description: Message related to the request outcome
items:
$ref: '#/components/schemas/Message'
type: array
serviceOutcomeCode:
description: prior auth outcome code at service level (valid values:-1/2/3/4/5)
example: '1'
type: string
description: Prior authorization details for a service
BenefitCheckResponseWrapper:
type: object
properties:
checkPriorAuthBenefitCoverage:
description: Benefit Check response
$ref: '#/components/schemas/CheckPriorAuthBenefitCoverage'
description: Benefit Check response wrapper.
CaseSummary:
type: object
properties:
member:
description: Member information
$ref: '#/components/schemas/Member'
placeOfServiceCode:
description: place of service code (edi837 compliant two byte value)
example: '11'
type: string
requestingProviderNPI:
description: NPI of the requesting provider
example: '9876543210'
type: string
requestingProviderTin:
description: Tax ID of the requesting provider
example: '123456789'
type: string
description: Summary of the benefit check case
BeneficiaryDetailInput:
type: object
properties:
beneficiaryId:
description: Unique identifier for the patient/member
example: M123456789
type: string
dateOfBirth:
description: Date of birth of the patient
example: '1985-06-15'
type: string
firstName:
description: Patient first name
example: John
type: string
lastName:
description: Patient last name
example: Doe
type: string
groupNumber:
description: Group or Member Policy Number
example: G123456
type: string
serviceStartDate:
description: First date of service; Default is current date
example: '2023-01-01'
type: string
serviceEndDate:
description: End date of service; Default is current date
example: '2023-01-01'
type: string
required:
- beneficiaryId
- dateOfBirth
- firstName
- lastName
- groupNumber
description: Details of the member for benefit check.
ReferralInquiry:
type: object
properties:
referralIndicator:
description: referral indicator to describe if referral is required or not for the member policy/plan
example: Y
type: string
description: Response indicating whether a referral is required for the member's plan.
BenefitLanguage:
type: object
properties:
benefitName:
description: Name of the benefit.
example: Hearing Aids
type: string
benefitDetails:
description: Detailed explanation of the benefit.
example: 'What are hearing aids: Electronic amplifying devices designed to bring sound more
effectively into the ear.'
type: string
benefitInformationSection:
description: Informational data for the benefitId
example: text
items:
type: string
type: array
benefitNetworkSection:
description: Network-specific cost and coverage details.
items:
$ref: '#/components/schemas/BenefitNetworkSection'
type: array
limitsAndExceptions:
description: Limitations and exceptions applicable to the benefit.
items:
$ref: '#/components/schemas/LimitException'
type: array
description: Language details of a benefit including costs, network status, and exceptions.
BenefitNetworkSection:
type: object
properties:
costs:
description: cost details for the benefit
example: 'UHC Network: co-insurance after you pay the deductible. Is prior-auth needed? No'
type: string
networkStatus:
description: network status details on the benefit
example: Your cost if you use Network benefits
items:
type: string
type: array
description: Details of benefit coverage within a specific network.
ServiceLocationInput:
type: object
properties:
placeOfServiceCode:
description: CLM05-01 [Place of Service Code or Bill Type Code] from EDI837. Code identifying
where services were, or may be, performed.
example: '11'
type: string
claimType:
description: Code identifying the type of facility referenced (I=Instituitional, P=Professional
or D=Dental
example: I
type: string
serviceDetail:
description: Describes the nature of the service
example: Medical
type: string
serviceDescription:
description: Describes the nature of the service (Scheduled, Emergent or Urgent)
example: Scheduled
type: string
required:
- placeOfServiceCode
- claimType
- serviceDetail
- serviceDescription
description: Location and type of service.
MatchedPriorAuths:
type: object
properties:
caseDecision:
description: decision outcome on the matching prior auth existing in the system
example: Approved
type: string
caseServices:
description: List of services included in the matched prior authorization case
items:
$ref: '#/components/schemas/CaseService'
type: array
caseStatus:
description: current status of the existing prior auth
example: Closed
type: string
serviceReferenceNumber:
description: prior auth reference number for an existing matched prior auth submitted by the
provider for the member
example: AUTH123456
type: string
description: Details of matched prior authorization cases
Member:
type: object
properties:
groupNumber:
description: Group or policy number of the member
example: M123456789
type: string
memberId:
description: Unique identifier for the member
example: G123456
type: string
description: Member information
DiagnosisCodesInput:
type: object
properties:
diagnosisTypeCode:
description: Diagnosis type code (ex:ABK/ABJ for Primary ICD10 and BK/BJ for Primary ICD9; ABF/APR
for Secondary ICD10 and BF/BR for Secondary ICD9)
example: ABK
type: string
diagnosisCode:
description: Diagnosis Code example J01.90
example: J01.90
type: string
required:
- diagnosisTypeCode
- diagnosisCode
description: Diagnosis codes relevant to the case.
BenefitLanguageResponseWrapper:
type: object
properties:
checkPlanBenefitLanguage:
description: Benefit Language response
$ref: '#/components/schemas/CheckPlanBenefitLanguage'
description: Benefit Language response wrapper.
Message:
type: object
properties:
messageText:
description: Text of the message
example: Prior authorization required for the requested service
type: string
description: Message related to prior authorization or service outcome
CheckPlanBenefitCategory:
type: object
properties:
eligibilityTransactionId:
description: transaction id returned on the previous eligibility lookup (valid only for certain
timeperiod)
example: abcdefg
type: string
newBenefits:
description: boolean value:- true=>Benefit Language can be called for further details; false=>Benefit
Language not supported.
example: true
type: boolean
benefitCategory:
description: List of benefit categories.
items:
$ref: '#/components/schemas/BenefitCategory'
type: array
description: Response containing benefit categories available to the member.
BenefitCategory:
type: object
properties:
categoryName:
description: Parent category of the benefit.
example: MRI services
type: string
categoryDetail:
description: Details of the benefit sub-category.
items:
$ref: '#/components/schemas/BenefitDetail'
type: array
description: Benefit category and its details.
LimitException:
type: object
properties:
description:
description: Summary of the limitation or exception.
example: General
type: string
details:
description: Detailed explanation of the limitation or exception.
example: No coverage for bone anchored hearing aids except Craniofacial anomalies.
type: string
description: Limitations and exceptions for a benefit.
ReferralInquiryResponseWrapper:
type: object
properties:
referralInquiry:
description: Referral Inquiry response
$ref: '#/components/schemas/ReferralInquiry'
description: Referral Inquiry response wrapper.
CheckPlanBenefitLanguage:
type: object
properties:
newBenefits:
description: boolean value:- true=>Benefit Language can be called for further details; false=>Benefit
Language not supported.
example: true
type: boolean
benefits:
description: Detailed benefit language including cost shares, limits, and exceptions.
$ref: '#/components/schemas/BenefitLanguage'
description: Response containing language details for a specific benefit.
BenefitCheckInput:
type: object
properties:
beneficiaryDetail:
description: Details of the beneficiary
$ref: '#/components/schemas/BeneficiaryDetailInput'
serviceLocation:
description: Service Location
$ref: '#/components/schemas/ServiceLocationInput'
caseDetailProvider:
description: Case Detail Provider
items:
$ref: '#/components/schemas/CaseDetailProviderInput'
type: array
diagnosisCodes:
description: Diagnosis codes
items:
$ref: '#/components/schemas/DiagnosisCodesInput'
type: array
facilityServiceDetail:
description: Facility service detail
$ref: '#/components/schemas/FacilityServiceDetailInput'
payerId:
description: Payer Id
example: '12345'
type: string
description: BenefitCheckInputDTO
ReferralInquiryInput:
type: object
properties:
beneficiaryDetail:
description: Details of the beneficiary
$ref: '#/components/schemas/BeneficiaryDetailInput'
providerDetail:
description: Details of the provider
$ref: '#/components/schemas/ProviderDetailInput'
payerId:
description: Payer Id
example: '12345'
type: string
description: Input for checking referral requirements.
BenefitCheckResponse:
type: object
properties:
data:
description: Benefit Check response wrapper.
$ref: '#/components/schemas/BenefitCheckResponseWrapper'
description: Benefit Check response data wrapper.
ReferralInquiryResponse:
type: object
properties:
data:
description: Referral Inquiry response wrapper.
$ref: '#/components/schemas/ReferralInquiryResponseWrapper'
description: Referral Inquiry response data wrapper.
BenefitLanguageResponse:
type: object
properties:
data:
description: Benefit Language response wrapper.
$ref: '#/components/schemas/BenefitLanguageResponseWrapper'
description: Benefit Language response data wrapper.
BenefitCategoryResponse:
type: object
properties:
data:
description: Benefit Category response wrapper.
$ref: '#/components/schemas/BenefitCategoryResponseWrapper'
description: Benefit Category response data wrapper.
securitySchemes:
oAuth:
type: oauth2
description: This API uses OAuth 2 with the client_credentials grant flow.
flows:
clientCredentials:
tokenUrl: /apip/auth/sntl/v1/token
scopes:
read_txn: read transactions
create_txn: submit a new transaction request
read_coveragediscovery: read coverage discovery tasks
create_coveragediscovery: submit a new coverage discovery task
read_healthcheck: check the status of the system
x-readme:
explorer-enabled: true
proxy-enabled: true