openapi: 3.0.0 info: description: The GraphQL Auth Referral Submission API allows users to search for providers, submit referrals, search referrals, and search prior authorizations using GraphQL queries and mutations. title: Auth Referral Submission API version: 1.0.0 servers: - url: https://sandbox-apigw.optum.com paths: /oihub/patient/auth/referral/v1: post: security: - oAuth: - read_healthcheck operationId: authReferralSubmission tags: - Auth Referral Submission parameters: - name: providerTaxId in: header description: Provider Tax ID Number required: true schema: example: '123456789' type: string - name: x-optum-consumer-correlation-id in: header description: Unique UUID to track the transaction required: false schema: example: 4d4a8964-e5fa-42dc-a37d-12345789 type: string - name: environment in: header description: Environment required: false schema: example: sandbox type: string requestBody: required: true content: application/json: schema: type: object required: - query description: GraphQL queries/mutations for Auth Referral Submission properties: query: description: GraphQL query or mutation type: string variables: description: Variables for the GraphQL query/mutation type: object properties: providerSearchInput: properties: searchType: description: REQUESTING,SERVICING example: SERVICING type: string provider: $ref: '#/components/schemas/ProviderInput' patient: $ref: '#/components/schemas/PatientInput' pagination: $ref: '#/components/schemas/PaginationInput' payerId: description: payerId example: '87726' type: string type: object required: - searchType - provider - patient - payerId referralSubmitInput: properties: requestingProvider: $ref: '#/components/schemas/ReferralSubmitProviderInput' patient: $ref: '#/components/schemas/PatientInput' service: $ref: '#/components/schemas/ServiceInput' servicingProvider: description: Servicing provider information $ref: '#/components/schemas/ReferralSubmitProviderInput' payerId: description: payerId example: '87726' type: string type: object required: - requestingProvider - patient - service - servicingProvider - payerId referralSearchInput: properties: patient: $ref: '#/components/schemas/PatientInput' serviceStartDate: example: '2024-01-01' type: string serviceEndDate: example: '2024-12-31' type: string status: description: 'default: APPROVED' example: ALL type: string pagination: $ref: '#/components/schemas/PaginationInput' payerId: description: payerId example: '87726' type: string type: object required: - patient - serviceStartDate - serviceEndDate - payerId priorAuthSearchInput: properties: serviceReferenceNumber: description: PriorAuth unique case Id reference number. example: AXXXXXX type: string corporateTin: description: Corporate Tax Identification Number. example: '123456789' type: string provider: $ref: '#/components/schemas/PriorAuthSearchProviderInput' member: $ref: '#/components/schemas/PatientInput' serviceSetting: description: Filter by service setting type. example: Inpatient type: string status: description: Filter by case status. example: Open type: string startDate: description: Start date for the service period search (YYYY-MM-DD). Default will be current date. example: '2025-07-19' type: string endDate: description: End date for the service period search (YYYY-MM-DD). Default will be current date. example: '2025-10-17' type: string payerId: description: payerId example: '87726' type: string type: object required: - corporateTin - provider - member - payerId operationName: description: Name of the GraphQL operation to execute (optional) type: string examples: SearchProviders: summary: Search Providers value: query: 'query SearchProviders($providerSearchInput: ProviderSearchInput!) { searchProviders(providerSearchInput: $providerSearchInput) { providers { name firstName middleName lastName providerOrganizationName npi taxId contactName phoneNumber fax networkStatus address { addressLine1 addressLine2 city state zip zip4 } uniqueProviderIdentifier providerType providerSpeciality { code description } gender distance handicapAccessible } pagination { totalRecords nextPageToken } } }' variables: providerSearchInput: searchType: SERVICING provider: zip: '90210' radius: 50 firstName: Dr. Carlos lastOrOrgName: Rodriguez npi: '9876543210' taxId: '987654321' preferredLanguage: SPA specialityCode: CARD gender: M patient: firstName: Alice lastName: Johnson id: '1234567890' dateOfBirth: '1990-12-31' groupNumber: GRP321 pagination: nextPageToken: '2' payerId: '87726' operationName: SearchProviders SubmitReferral: summary: Submit Referral value: query: 'mutation SubmitReferral($referralSubmitInput: ReferralSubmitInput!) { submitReferral(referralSubmitInput: $referralSubmitInput) { referralId referralStatus payer { id name messages } requestingProvider { name firstName middleName lastName providerOrganizationName npi taxId contactName phoneNumber fax networkStatus address { addressLine1 addressLine2 city state zip zip4 } } servicingProvider { name firstName middleName lastName providerOrganizationName npi taxId contactName phoneNumber fax networkStatus address { addressLine1 addressLine2 city state zip zip4 } } patient { id firstName middleName lastName dateOfBirth groupNumber relationshipCode relationshipDesc } decisions { decisionType certificationAction reviewDecisionReason startDate endDate referralQuantity { quantity qualifier qualifierDesc remaining } } x12Response rejectionReasons { rejectionLevel reasonDescription rejectionCode followUpAction rejectionReason validRequestIndicator } } }' variables: referralSubmitInput: requestingProvider: npi: '1234567890' taxId: '98765432' zip: '90201' firstName: Carlos lastOrOrgName: Dr. Carlos Clinic specialityCode: CARD gender: M city: Healthcare City state: CA radius: 50 contactName: Carlos Benito phoneNumber: 555-222-3333 preferredLanguage: SPA patient: firstName: Alice lastName: Johnson id: '1234567890' dateOfBirth: '1990-12-31' groupNumber: GRP321 service: diagnosisCodes: - M79.3 referralQuantity: quantity: 10 qualifier: VS startDate: '2025-01-01' endDate: '2025-01-01' comment: Patient requires physical therapy for knee pain servicingProvider: npi: '1234567890' taxId: '98765432' zip: '90201' firstName: Carlos lastOrOrgName: Dr. Carlos Clinic specialityCode: CARD gender: M city: Healthcare City state: CA radius: 50 contactName: Carlos Benito phoneNumber: 555-222-3333 preferredLanguage: SPA payerId: '87726' operationName: SubmitReferral SubmitReferralRejection: summary: Submit Referral Rejection value: query: 'mutation SubmitReferral($referralSubmitInput: ReferralSubmitInput!) { submitReferral(referralSubmitInput: $referralSubmitInput) { referralId referralStatus payer { id name messages } requestingProvider { name firstName middleName lastName providerOrganizationName npi taxId contactName phoneNumber fax networkStatus address { addressLine1 addressLine2 city state zip zip4 } } servicingProvider { name firstName middleName lastName providerOrganizationName npi taxId contactName phoneNumber fax networkStatus address { addressLine1 addressLine2 city state zip zip4 } } patient { id firstName middleName lastName dateOfBirth groupNumber relationshipCode relationshipDesc } decisions { decisionType certificationAction reviewDecisionReason startDate endDate referralQuantity { quantity qualifier qualifierDesc remaining } } x12Response rejectionReasons { rejectionLevel reasonDescription rejectionCode followUpAction rejectionReason validRequestIndicator } } }' variables: referralSubmitInput: requestingProvider: npi: '1234567890' taxId: '98765432' zip: '90201' firstName: Carlos lastOrOrgName: Dr. Carlos Clinic specialityCode: CARD gender: M city: Healthcare City state: CA radius: 50 contactName: Carlos Benito phoneNumber: 555-222-3333 preferredLanguage: SPA patient: firstName: Alice lastName: Johnson id: '1234567890' dateOfBirth: '1990-12-31' groupNumber: GRP321 service: diagnosisCodes: - M79.3 referralQuantity: quantity: 10 qualifier: VS startDate: '2025-01-01' endDate: '2025-01-01' comment: Patient requires physical therapy for knee pain servicingProvider: npi: '1234567890' taxId: '98765432' zip: '90201' firstName: Carlos lastOrOrgName: Dr. Carlos Clinic specialityCode: CARD gender: M city: Healthcare City state: CA radius: 50 contactName: Carlos Benito phoneNumber: 555-222-3333 preferredLanguage: SPA payerId: '87726' operationName: SubmitReferral SearchReferrals: summary: Search Referrals value: query: 'query SearchReferrals($referralSearchInput: ReferralSearchInput!) { searchReferrals(referralSearchInput: $referralSearchInput) { referrals { referralId referralStatus referralStatusCode requestingProvider { name firstName middleName lastName providerOrganizationName npi taxId contactName phoneNumber fax networkStatus address { addressLine1 addressLine2 city state zip zip4 } providerSpeciality { code description } } servicingProvider { name firstName middleName lastName providerOrganizationName npi taxId contactName phoneNumber fax networkStatus address { addressLine1 addressLine2 city state zip zip4 } providerSpeciality { code description } } service { diagnosisCodes referralQuantity { quantity qualifier qualifierDesc remaining } startDate endDate comment } rejectionResponse { rejectionLevel reasonDescription rejectionCode followUpAction rejectionReason validRequestIndicator } } pagination { totalRecords nextPageToken } } }' variables: referralSearchInput: patient: firstName: Alice lastName: Johnson id: '1234567890' dateOfBirth: '1990-12-31' groupNumber: GRP321 serviceStartDate: '2024-01-01' serviceEndDate: '2024-12-31' status: ALL pagination: nextPageToken: '2' payerId: '87726' operationName: SearchReferrals SearchPriorAuths: summary: Search Prior Auths value: query: 'query SearchPriorAuths($priorAuthSearchInput: PriorAuthSearchInput!) { searchPriorAuths(priorAuthSearchInput: $priorAuthSearchInput) { caseSummary { serviceReferenceNumber memberID memberFirstName memberLastName serviceSetting placeOfService serviceDates caseStatus overallCoverageStatus } caseDescription { caseSearchMessages caseDetail { serviceReferenceNumber caseStatus caseStatusReason primaryCarePhysician advanceNotifyDateTime admissionNotifyDateTime expectedServiceStartDate expectedServiceEndDate actualServiceStartDate actualServiceEndDate } coverageStatus { overallCoverageStatus procedureCode description coverageStatus decisionDate geneticMolecularTestCode geneticMolecularTestReviewType } clinicalNotes { createdTime createdBy noteText } patientDetails { id firstName middleName lastName dateOfBirth groupNumber relationshipCode relationshipDesc product effectiveDate terminationDate insuranceType verbalLanguagePreference writtenLanguagePreference informationalMessage } submittingProvider { name firstName middleName lastName providerOrganizationName npi taxId contactName phoneNumber fax networkStatus address { addressLine1 addressLine2 city state zip zip4 } } admittingAttendingProvider { name firstName middleName lastName providerOrganizationName npi taxId contactName phoneNumber fax networkStatus address { addressLine1 addressLine2 city state zip zip4 } } orderingProvider { name firstName middleName lastName providerOrganizationName npi taxId contactName phoneNumber fax networkStatus address { addressLine1 addressLine2 city state zip zip4 } } facilityDetails { name firstName middleName lastName providerOrganizationName npi taxId contactName phoneNumber fax networkStatus address { addressLine1 addressLine2 city state zip zip4 } coverage } serviceDetails { placeOfService serviceDescription serviceDetails } facilityServiceDetails { startDate endDate serviceDescription isPatientAdmitted expectedAdmissionDate expectedDischargeDate actualAdmissionDateTime isPatientDischarged dischargeDate dischargeLocation } diagnosisDetails { codePointer code description } procedureCodeDetails { codePointer code description coverageStatus servicingProvider { name firstName middleName lastName providerOrganizationName npi taxId contactName phoneNumber fax networkStatus address { addressLine1 addressLine2 city state zip zip4 } } serviceDetail expectedFromDate expectedToDate procedureUnitPerFrequencyCount procedureUnitOfMeasure procedureFrequency procedureUnitCount dmeProcurementType dmeTotalCost dmeClinicalIllnessDescText dmeSupplyDescText dmeEnternalFeedingSSONutrInd dmeFormulaNameText dmeMedicalConditionText } expeditedRequestReview initialContact { contactName phoneNumber fax } followUpContact { contactName phoneNumber fax departmentType contactRoleType emailAddress medicalRecordNumber memberPhone } } } }' variables: priorAuthSearchInput: serviceReferenceNumber: AXXXXXX corporateTin: '123456789' provider: firstName: Dr. Carlos lastOrOrgName: Rodriguez address: addressLine1: 1234 Street addressLine2: Building A city: Healthcare City state: AZ zip: '90210' zip4: '0001' member: firstName: Alice lastName: Johnson id: '1234567890' dateOfBirth: '1990-12-31' groupNumber: GRP321 stateCode: AZ zipCode: '90210' serviceSetting: Inpatient status: Open startDate: '2025-07-19' endDate: '2025-10-17' payerId: '87726' operationName: SearchPriorAuths responses: '200': description: "SearchProviders\n\n\nSubmitReferral\n\ \n\nSearchReferrals\n\ \n\nPriorAuth Search\n\n" content: application/json: examples: SearchProviders: summary: Search Providers value: data: searchProviders: providers: - name: John J Doe firstName: John middleName: J lastName: Doe providerOrganizationName: Dr. John Doe Clinic npi: '1234567890' taxId: '987654321' contactName: Alison Johnson phoneNumber: 555-222-3333 fax: 555-222-4444 networkStatus: IN_NETWORK address: addressLine1: 123 Healthcare Drive addressLine2: Suite 200 city: Healthcare City state: CA zip: '90210' zip4: '0001' uniqueProviderIdentifier: enc_pvd_123456789abcdef providerType: INDIVIDUAL providerSpeciality: - code: 207Q00000X description: Family Medicine gender: Male distance: '2.5' handicapAccessible: true pagination: totalRecords: '147' nextPageToken: '3' SubmitReferral: summary: Submit Referral value: data: submitReferral: referralId: REF123456789 referralStatus: APPROVED payer: id: PAY001 name: UnitedHealthcare messages: - Referral approved for 12 visits requestingProvider: name: John J Doe firstName: John middleName: J lastName: Doe providerOrganizationName: Dr. John Doe Clinic npi: '1234567890' taxId: '987654321' contactName: Alison Johnson phoneNumber: 555-123-4567 fax: 555-222-4444 networkStatus: IN_NETWORK address: addressLine1: 123 Medical Drive addressLine2: Building A city: Healthcare City state: CA zip: '90210' zip4: '0001' servicingProvider: name: John J Doe firstName: John middleName: J lastName: Doe providerOrganizationName: Dr. John Doe Clinic npi: '1234567890' taxId: '987654321' contactName: Alison Johnson phoneNumber: 555-123-4567 fax: 555-222-4444 networkStatus: IN_NETWORK address: addressLine1: 123 Medical Drive addressLine2: Building A city: Healthcare City state: CA zip: '90210' zip4: '0001' patient: id: '123456789' firstName: Alice middleName: A lastName: Johnson dateOfBirth: '1990-12-31' groupNumber: GRP321 relationshipCode: '18' relationshipDesc: SELF decisions: - decisionType: EVENT certificationAction: A1 reviewDecisionReason: MEETS_CRITERIA startDate: '2024-11-30' endDate: '2024-11-30' referralQuantity: quantity: 12 qualifier: VS qualifierDesc: visits remaining: 8 x12Response: ISA*00* *00* *ZZ*SENDER *ZZ*RECEIVER *241010*1234*^*00501*000000001*0*P*:~ rejectionReasons: - rejectionLevel: REFERRAL reasonDescription: Insufficient medical documentation provided rejectionCode: R001 followUpAction: RESUBMIT_WITH_DOCUMENTATION rejectionReason: MISSING_DOCUMENTATION validRequestIndicator: N SubmitReferralRejection: summary: SubmitReferral Rejection value: data: submitReferral: referralId: '' referralStatus: REJECTED payer: id: PAY001 name: UnitedHealthcare messages: - Referral denied - see rejection reasons rejectionReasons: - rejectionLevel: REFERRAL reasonDescription: Insufficient medical documentation provided rejectionCode: R001 rejectionReason: MISSING_DOCUMENTATION followUpAction: RESUBMIT_WITH_DOCUMENTATION validRequestIndicator: N SearchReferrals: summary: Search Referrals value: data: searchReferrals: referrals: - referralId: REF123456789 referralStatus: APPROVED referralStatusCode: A1 requestingProvider: name: John J Doe firstName: John middleName: J lastName: Doe providerOrganizationName: Dr. John Doe Clinic npi: '1234567890' taxId: '987654321' contactName: Alison Johnson phoneNumber: 555-222-3333 fax: 555-222-4444 networkStatus: IN_NETWORK address: addressLine1: 123 Healthcare Drive addressLine2: Suite 200 city: Healthcare City state: CA zip: '90210' zip4: '0001' providerSpeciality: code: 207Q00000X description: Family Medicine servicingProvider: name: John J Doe firstName: John middleName: J lastName: Doe providerOrganizationName: Dr. John Doe Clinic npi: '1234567890' taxId: '987654321' contactName: Alison Johnson phoneNumber: 555-222-3333 fax: 555-222-4444 networkStatus: IN_NETWORK address: addressLine1: 123 Healthcare Drive addressLine2: Suite 200 city: Healthcare City state: CA zip: '90210' zip4: '0001' providerSpeciality: code: 207Q00000X description: Family Medicine service: diagnosisCodes: - M79.3 referralQuantity: quantity: 12 qualifier: VS qualifierDesc: visits remaining: 8 startDate: '2024-11-01' endDate: '2024-11-30' comment: Physical therapy for knee pain rejectionResponse: rejectionLevel: REFERRAL reasonDescription: Insufficient medical documentation provided rejectionCode: R001 followUpAction: RESUBMIT_WITH_DOCUMENTATION rejectionReason: MISSING_DOCUMENTATION validRequestIndicator: N pagination: totalRecords: '147' nextPageToken: '3' SearchPriorAuths: summary: Search PriorAuths value: data: searchPriorAuths: caseSummary: - serviceReferenceNumber: AXXXXXXXXX memberID: '953333333' memberFirstName: Alison memberLastName: Johnson serviceSetting: Inpatient placeOfService: Acute Hospital serviceDates: 10/02/2025-10/03/2025 caseStatus: Open overallCoverageStatus: Covered/Approved caseDescription: caseSearchMessages: - A decision has already been rendered on this case, though some updates are permitted as indicated in the enabled fields below. - To request an additional service for this member, please submit a new notification/prior authorization request for the member. caseDetail: serviceReferenceNumber: AXXXXXXXXX caseStatus: Open caseStatusReason: Open primaryCarePhysician: John advanceNotifyDateTime: 2025-01-01:00:00:01 admissionNotifyDateTime: 2025-01-01:00:00:01 expectedServiceStartDate: '2025-10-02' expectedServiceEndDate: '2025-10-03' actualServiceStartDate: '2025-10-02' actualServiceEndDate: '2025-10-03' coverageStatus: - overallCoverageStatus: Covered/Approved procedureCode: '99213' description: Established patient office or other outpatient visit coverageStatus: Covered decisionDate: '2025-09-15' geneticMolecularTestCode: null geneticMolecularTestReviewType: null clinicalNotes: - createdTime: 2025-01-01:00:00:01 createdBy: doctor noteText: note text detail patientDetails: id: '123456789' firstName: Alice middleName: A lastName: Johnson dateOfBirth: '1990-12-31' groupNumber: GRP321 relationshipCode: '18' relationshipDesc: SELF product: PPO - Options PPO effectiveDate: '2025-03-01' terminationDate: '2025-12-31' insuranceType: Medicare verbalLanguagePreference: English writtenLanguagePreference: English informationalMessage: A future timeline may be available for this member. For future coverage please call the telephone number located on the back of the member's Medical ID card. submittingProvider: name: John J Doe firstName: John middleName: J lastName: Doe providerOrganizationName: Dr. John Doe Clinic npi: '1234567890' taxId: '987654321' contactName: Alison Johnson phoneNumber: 555-123-4567 fax: 555-222-4444 networkStatus: IN_NETWORK address: addressLine1: 123 Medical Drive addressLine2: Building A city: Healthcare City state: CA zip: '90210' zip4: '0001' admittingAttendingProvider: name: John J Doe firstName: John middleName: J lastName: Doe providerOrganizationName: Dr. John Doe Clinic npi: '1234567890' taxId: '987654321' contactName: Alison Johnson phoneNumber: 555-123-4567 fax: 555-222-4444 networkStatus: IN_NETWORK address: addressLine1: 123 Medical Drive addressLine2: Building A city: Healthcare City state: CA zip: '90210' zip4: '0001' orderingProvider: name: John J Doe firstName: John middleName: J lastName: Doe providerOrganizationName: Dr. John Doe Clinic npi: '1234567890' taxId: '987654321' contactName: Alison Johnson phoneNumber: 555-123-4567 fax: 555-222-4444 networkStatus: IN_NETWORK address: addressLine1: 123 Medical Drive addressLine2: Building A city: Healthcare City state: CA zip: '90210' zip4: '0001' facilityDetails: name: John J Doe firstName: John middleName: J lastName: Doe providerOrganizationName: Dr. John Doe Clinic npi: '1234567890' taxId: 12345678 contactName: Alison Johnson phoneNumber: 555-123-4567 fax: 555-123-4568 networkStatus: In Network address: addressLine1: 123 Medical Drive addressLine2: Building A city: Healthcare City state: CA zip: '90210' zip4: '0001' coverage: Covered/Approved serviceDetails: placeOfService: Acute Hospital serviceDescription: Scheduled serviceDetails: Surgical facilityServiceDetails: startDate: '2025-10-02' endDate: '2025-10-02' serviceDescription: Scheduled isPatientAdmitted: 'Yes' expectedAdmissionDate: '2025-10-02' expectedDischargeDate: '2025-10-02' actualAdmissionDateTime: '2025-10-02' isPatientDischarged: 'Yes' dischargeDate: '2025-10-02' dischargeLocation: Home diagnosisDetails: - codePointer: Primary code: J01.90 description: acute sinusitis procedureCodeDetails: - codePointer: Primary code: '99213' description: Established patient office or other outpatient visit coverageStatus: Covered/Approved servicingProvider: name: John J Doe firstName: John middleName: J lastName: Doe providerOrganizationName: Dr. John Doe Clinic npi: '1234567890' taxId: '987654321' contactName: Alison Johnson phoneNumber: 555-123-4567 fax: 555-222-4444 networkStatus: IN_NETWORK address: addressLine1: 123 Medical Drive addressLine2: Building A city: Healthcare City state: CA zip: '90210' zip4: '0001' serviceDetail: Surgical expectedFromDate: '2025-10-02' expectedToDate: '2025-10-02' procedureUnitPerFrequencyCount: '1' procedureUnitOfMeasure: UN procedureFrequency: '1' procedureUnitCount: '1' dmeProcurementType: durable medical equipment procurement type dmeTotalCost: durable medical equipment total cost dmeClinicalIllnessDescText: durable medical equipment clinical description dmeSupplyDescText: durable medical equipment supply description dmeEnternalFeedingSSONutrInd: false dmeFormulaNameText: durable medical equipment formula name dmeMedicalConditionText: durable medical equipment condition text expeditedRequestReview: true initialContact: contactName: Bruce Wayne phoneNumber: 555-123-4567 fax: 555-123-4568 followUpContact: contactName: Bruce Wayne phoneNumber: 555-123-4567 fax: 555-123-4568 departmentType: null contactRoleType: Other emailAddress: tonystark@avengers.com medicalRecordNumber: EPIC 123456 987654 memberPhone: 555-111-1234 schema: properties: errors: description: List of errors if occurred during operation type: array items: properties: description: description: Detailed error message type: string code: description: Error code identifying the specific error type: string type: object data: properties: searchProviders: $ref: '#/components/schemas/ProviderSearchResponse' searchPriorAuths: $ref: '#/components/schemas/PriorAuthSearchResponse' searchReferrals: $ref: '#/components/schemas/ReferralSearchResponse' submitReferral: $ref: '#/components/schemas/ReferralSubmitResponse' type: object type: object '400': description: Bad Request content: application/json: example: errors: - description: Cannot query field... code: GRAPHQL_VALIDATION_FAILED schema: properties: errors: items: properties: description: type: string code: type: string type: object type: array type: object '401': description: Unauthorized content: application/json: example: errors: - description: Invalid or expired token code: AUTH_FAILURE schema: properties: errors: items: properties: description: type: string code: type: string type: object type: array type: object '500': description: Internal server error content: application/json: example: errors: - description: An unexpected error occurred. code: INTERNAL_SERVER_ERROR schema: properties: errors: items: properties: description: type: string code: type: string type: object type: array type: object components: schemas: SearchProvidersResponseDataWrapper: type: object properties: data: description: Search providers response wrapper $ref: '#/components/schemas/SearchProvidersResponseWrapper' description: Search providers response data wrapper ProviderSearchInput: type: object properties: searchType: description: REQUESTING,SERVICING example: SERVICING type: string provider: $ref: '#/components/schemas/ProviderInput' patient: $ref: '#/components/schemas/PatientInput' pagination: $ref: '#/components/schemas/PaginationInput' payerId: description: payerId example: '87726' type: string required: - patient.firstName - patient.lastName - patient.id - patient.dateOfBirth - patient.groupNumber - searchType - provider - patient - payerId SubmitReferralsResponseDataWrapper: type: object properties: data: description: Submit referral response wrapper $ref: '#/components/schemas/SubmitReferralsResponseWrapper' description: Submit referral response data wrapper ReferralSubmitInput: type: object properties: requestingProvider: $ref: '#/components/schemas/ReferralSubmitProviderInput' patient: $ref: '#/components/schemas/PatientInput' service: $ref: '#/components/schemas/ServiceInput' servicingProvider: description: Servicing provider information $ref: '#/components/schemas/ReferralSubmitProviderInput' payerId: description: payerId example: '87726' type: string required: - patient.firstName - patient.lastName - patient.id - patient.dateOfBirth - patient.groupNumber - requestingProvider.npi - requestingProvider.taxId - requestingProvider.zip - service.referralQuantity.quantity - service.referralQuantity.qualifier - service.diagnosisCodes - service.referralQuantity - service.startDate - requestingProvider - patient - service - servicingProvider - payerId SearchReferralsResponseDataWrapper: type: object properties: data: description: Search referrals response $ref: '#/components/schemas/SearchReferralsResponseWrapper' description: Search referrals response data wrapper ReferralSearchInput: type: object properties: patient: $ref: '#/components/schemas/PatientInput' serviceStartDate: example: '2024-01-01' type: string serviceEndDate: example: '2024-12-31' type: string status: description: 'default: APPROVED' example: ALL type: string pagination: $ref: '#/components/schemas/PaginationInput' payerId: description: payerId example: '87726' type: string required: - patient.firstName - patient.lastName - patient.id - patient.dateOfBirth - patient.groupNumber - patient - serviceStartDate - serviceEndDate - payerId SearchPriorAuthsResponseDataWrapper: type: object properties: data: description: Search prior auths response wrapper $ref: '#/components/schemas/SearchPriorAuthsResponseWrapper' description: Search prior auths response data wrapper PriorAuthSearchInput: type: object properties: serviceReferenceNumber: description: PriorAuth unique case Id reference number. example: AXXXXXX type: string corporateTin: description: Corporate Tax Identification Number. example: '123456789' type: string provider: $ref: '#/components/schemas/PriorAuthSearchProviderInput' member: $ref: '#/components/schemas/PatientInput' serviceSetting: description: Filter by service setting type. example: Inpatient type: string status: description: Filter by case status. example: Open type: string startDate: description: Start date for the service period search (YYYY-MM-DD). Default will be current date. example: '2025-07-19' type: string endDate: description: End date for the service period search (YYYY-MM-DD). Default will be current date. example: '2025-10-17' type: string payerId: description: payerId example: '87726' type: string required: - member.firstName - member.lastName - member.id - member.dateOfBirth - member.groupNumber - provider.address.addressLine1 - provider.address.state - provider.address.zip - provider.lastOrOrgName - provider.address - corporateTin - provider - member - payerId description: Input structure for the GraphQL search variables for prior-auth. ContactBase: type: object properties: contactName: description: full name of the contact for the case example: Bruce Wayne type: string phoneNumber: description: contact phone number example: 555-123-4567 type: string fax: description: contact fax number example: 555-123-4568 type: string ExtendedProvider: type: object properties: name: description: Provider full name example: John J Doe type: string firstName: description: Provider first name example: John type: string middleName: description: Provider middle name example: J type: string lastName: description: Provider last name example: Doe type: string providerOrganizationName: description: provider org name example: Dr. John Doe Clinic type: string npi: description: provider NPI example: '1234567890' type: string taxId: description: provider TIN example: '987654321' type: string contactName: description: Provider contact name example: Alison Johnson type: string phoneNumber: description: Provider phone number example: 555-222-3333 type: string fax: description: Provider fax number example: 555-222-4444 type: string networkStatus: description: provider network status example: IN_NETWORK type: string address: $ref: '#/components/schemas/AddressBase' uniqueProviderIdentifier: description: provider unique identifier example: enc_pvd_123456789abcdef type: string providerType: description: provider type example: INDIVIDUAL type: string providerSpeciality: type: array items: $ref: '#/components/schemas/ProviderSpeciality' gender: description: provider gender example: Male type: string distance: description: provider distance example: '2.5' type: string handicapAccessible: description: handicap accessibility of provider facility example: true type: boolean ReferralSubmitResponse: type: object properties: referralId: example: REF123456789 type: string referralStatus: example: APPROVED type: string payer: $ref: '#/components/schemas/Payer' requestingProvider: $ref: '#/components/schemas/Provider' servicingProvider: $ref: '#/components/schemas/Provider' patient: $ref: '#/components/schemas/Patient' decisions: type: array items: $ref: '#/components/schemas/Decision' x12Response: example: ISA*00* *00* *ZZ*SENDER *ZZ*RECEIVER *241010*1234*^*00501*000000001*0*P*:~ type: string rejectionReasons: type: array items: $ref: '#/components/schemas/RejectionReason' FollowUpContact: type: object properties: contactName: description: full name of the contact for the case example: Bruce Wayne type: string phoneNumber: description: contact phone number example: 555-123-4567 type: string fax: description: contact fax number example: 555-123-4568 type: string departmentType: description: follow-up contact department example: 'null' type: string contactRoleType: description: follow-up contact role example: Other type: string emailAddress: description: follow-up contact email example: tonystark@avengers.com type: string medicalRecordNumber: description: medical record number example: EPIC 123456 987654 type: string memberPhone: description: member phone number example: 555-111-1234 type: string PaginationInput: type: object properties: nextPageToken: description: page identifier for pagination example: '2' type: string DiagnosisDetail: type: object properties: codePointer: description: diagnosis code type example: Primary type: string code: description: diagnosis code example: J01.90 type: string description: description: diagnosis code description example: acute sinusitis type: string ReferralSearchResponse: type: object properties: referrals: type: array items: $ref: '#/components/schemas/ReferralSearchResult' pagination: $ref: '#/components/schemas/Pagination' SearchPriorAuthsResponseWrapper: type: object properties: searchPriorAuths: description: Search prior auths response $ref: '#/components/schemas/PriorAuthSearchResponse' description: Search prior auths response wrapper containing the operation result Decision: type: object properties: decisionType: description: '[ Event, Service ]' example: EVENT type: string certificationAction: description: referral decision certification action example: A1 type: string reviewDecisionReason: description: referral decision review reason example: MEETS_CRITERIA type: string startDate: description: referral decision start date example: '2024-11-30' type: string endDate: description: referral decision end date example: '2024-11-30' type: string referralQuantity: $ref: '#/components/schemas/ReferralQuantity' ReferralQuantityInput: type: object properties: quantity: example: 10 type: integer qualifier: description: quantity qualifier (FL:Units; DY:Days; HS:Hours; MN:Month; VS:Visits) example: VS type: string required: - quantity - qualifier Patient: type: object properties: id: description: Patient/member ID example: '123456789' type: string firstName: description: patient first name example: Alice type: string middleName: description: patient middle name example: A type: string lastName: description: patient last name example: Johnson type: string dateOfBirth: description: patient date of birth example: '1990-12-31' type: string groupNumber: description: patient policy number example: GRP321 type: string relationshipCode: description: patient relationship code example: '18' type: string relationshipDesc: description: patient relationship description example: SELF type: string ProviderSpeciality: type: object properties: code: description: provider taxonomy/speciality code example: 207Q00000X type: string description: description: provider taxonomy description example: Family Medicine type: string ServiceResponse: type: object properties: diagnosisCodes: description: Diagnosis code example: M79.3 type: array items: type: string referralQuantity: $ref: '#/components/schemas/ReferralQuantity' startDate: description: diagnosis start date example: '2024-11-01' type: string endDate: description: diagnosis end date example: '2024-11-30' type: string comment: description: diagnosis comments example: Physical therapy for knee pain type: string CaseDescription: type: object properties: caseSearchMessages: description: payer message(s) related to the case. example: A decision has already been rendered on this case, though some updates are permitted as indicated in the enabled fields below. To request an additional service for this member, please submit a new notification/prior authorization request for the member. type: array items: type: string caseDetail: $ref: '#/components/schemas/CaseDetail' coverageStatus: type: array items: $ref: '#/components/schemas/CoverageStatusItem' clinicalNotes: type: array items: $ref: '#/components/schemas/ClinicalNote' patientDetails: $ref: '#/components/schemas/PatientDetails' submittingProvider: $ref: '#/components/schemas/Provider' admittingAttendingProvider: $ref: '#/components/schemas/Provider' orderingProvider: $ref: '#/components/schemas/Provider' facilityDetails: $ref: '#/components/schemas/FacilityDetails' serviceDetails: $ref: '#/components/schemas/ServiceDetails' facilityServiceDetails: $ref: '#/components/schemas/FacilityServiceDetails' diagnosisDetails: type: array items: $ref: '#/components/schemas/DiagnosisDetail' procedureCodeDetails: type: array items: $ref: '#/components/schemas/ProcedureCodeDetail' expeditedRequestReview: description: expedited review requirement on the case:- true or false example: true type: boolean initialContact: $ref: '#/components/schemas/ContactBase' followUpContact: description: Follow-up contact information $ref: '#/components/schemas/FollowUpContact' description: Detailed information about a specific prior authorization case. CaseSummary: type: object properties: serviceReferenceNumber: description: unique prior auth case identification number example: AXXXXXXXXX type: string memberID: description: unique member identifier example: '953333333' type: string memberFirstName: description: member first name example: Alison type: string memberLastName: description: Member last name example: Johnson type: string serviceSetting: description: case service setting:- Inpatient, Outpatient or Outpatient Facility example: Inpatient type: string placeOfService: description: Place of service example: Acute Hospital type: string serviceDates: description: Service date range (e.g., MM/DD/YYYY-MM/DD/YYYY) example: 10/02/2025-10/03/2025 type: string caseStatus: description: current status of the prior auth case example: Open type: string overallCoverageStatus: description: overall coverage status for the member and services on the case example: Covered/Approved type: string description: A brief summary of a single prior authorization case found in the search. FacilityDetails: type: object properties: name: description: provider full name example: John J Doe type: string firstName: description: provider first name example: John type: string middleName: description: provider middle name example: J type: string lastName: description: provider last name example: Doe type: string providerOrganizationName: description: provider org name example: Dr. John Doe Clinic type: string npi: description: provider NPI example: '1234567890' type: string taxId: description: provider TIN example: 12345678 type: string contactName: description: provider contact name example: Alison Johnson type: string phoneNumber: description: provider phone number example: 555-123-4567 type: string fax: description: provider fax number example: 555-123-4568 type: string networkStatus: description: provider network status example: In Network type: string address: $ref: '#/components/schemas/AddressExt' coverage: description: coverage status example: Covered/Approved type: string PriorAuthSearchProviderInput: type: object properties: firstName: description: Provider first name example: Dr. Carlos type: string lastOrOrgName: description: Provider last name or organization example: Rodriguez type: string address: $ref: '#/components/schemas/ProviderAddressInput' required: - address.addressLine1 - address.state - address.zip - lastOrOrgName - address description: Search parameters related to the provider ReferralQuantity: type: object properties: quantity: description: quantity limit example: 12 type: integer qualifier: description: referral qualifier/unit example: VS type: string qualifierDesc: description: referral qualifier description example: visits type: string remaining: description: referral quantity remaining example: 8 type: integer Pagination: type: object properties: totalRecords: description: total records for the response example: '147' type: string nextPageToken: description: page offset for pagination example: '3' type: string AddressExt: type: object properties: addressLine1: description: Address line 1 example: 123 Medical Drive type: string addressLine2: description: Address line 2 example: Building A type: string city: description: City example: Healthcare City type: string state: description: State code (e.g., AZ, CA, NY etc). example: CA type: string zip: description: Standard ZIP code. example: '90210' type: string zip4: description: ZIP+4 suffix example: '0001' type: string ProviderAddressInput: type: object properties: addressLine1: description: Address line 1 example: 1234 Street type: string addressLine2: description: Address line 2 (optional). example: Building A type: string city: description: City example: Healthcare City type: string state: description: State code (e.g., AZ, CA, NY etc). example: AZ type: string zip: description: Standard ZIP code. example: '90210' type: string zip4: description: ZIP+4 suffix example: '0001' type: string required: - addressLine1 - state - zip CoverageStatusItem: type: object properties: overallCoverageStatus: description: overall coverage status for the member and services example: Covered/Approved type: string procedureCode: description: procedure code for the service example: '99213' type: string description: description: procedure code description example: Established patient office or other outpatient visit type: string coverageStatus: description: coverage status for the service example: Covered type: string decisionDate: description: date on which case decision is amde example: '2025-09-15' type: string geneticMolecularTestCode: description: geneticMolecularTestCode example: 'null' type: string geneticMolecularTestReviewType: description: geneticMolecularTestReviewType example: 'null' type: string AddressBase: type: object properties: addressLine1: description: Address line 1 example: 123 Healthcare Drive type: string addressLine2: description: Address line 2 (optional). example: Suite 200 type: string city: description: City example: Healthcare City type: string state: description: State code (e.g., AZ, CA, NY etc). example: CA type: string zip: description: Standard ZIP code. example: '90210' type: string zip4: description: ZIP+4 suffix example: '0001' type: string ServiceDetails: type: object properties: placeOfService: description: Place of service example: Acute Hospital type: string serviceDescription: description: service description:- Scheduled, Urgent, Emergent example: Scheduled type: string serviceDetails: description: service detail:- Surgical, Medical etc example: Surgical type: string ProviderInput: type: object properties: zip: description: provider zipcode example: '90210' type: string radius: description: provider facility to be searched in radius distance example: 25 type: integer firstName: description: provider first name example: Dr. Carlos type: string lastOrOrgName: description: Provider last name or organization name example: Rodriguez type: string npi: description: provider NPI example: '1234567890' type: string taxId: description: provider TIN example: '987654321' type: string preferredLanguage: description: provider language example: SPA type: string specialityCode: description: provider speciality example: CARD type: string gender: description: provider gender example: M type: string ServiceInput: type: object properties: diagnosisCodes: description: diagnosis codes example: M79.3 type: array items: type: string referralQuantity: $ref: '#/components/schemas/ReferralQuantityInput' startDate: description: referral start date example: '2025-01-01' type: string endDate: description: referral end date example: '2025-01-01' type: string comment: description: referral comments example: Patient requires physical therapy for knee pain type: string required: - referralQuantity.quantity - referralQuantity.qualifier - diagnosisCodes - referralQuantity - startDate SubmitReferralsResponseWrapper: type: object properties: submitReferral: description: Submit referral response $ref: '#/components/schemas/ReferralSubmitResponse' description: Submit referral response wrapper containing the operation result Payer: type: object properties: id: description: Payer ID example: PAY001 type: string name: description: Payer name example: UnitedHealthcare type: string messages: description: referral submission messages example: Referral approved for 12 visits type: array items: type: string SearchProvidersResponseWrapper: type: object properties: searchProviders: description: Search providers response $ref: '#/components/schemas/ProviderSearchResponse' description: Search providers response wrapper containing the operation result SearchReferralsResponseWrapper: type: object properties: searchReferrals: description: Search referrals response $ref: '#/components/schemas/ReferralSearchResponse' description: Search referrals response wrapper containing the operation result PatientInput: type: object properties: firstName: description: patient first name example: Alice type: string lastName: description: patient last name example: Johnson type: string id: description: patient identifier number example: '1234567890' type: string dateOfBirth: description: patient date of birth example: '1990-12-31' type: string groupNumber: description: patient policy number example: GRP321 type: string stateCode: description: patient state code example: AZ type: string zipCode: description: patient zip code example: '90210' type: string required: - firstName - lastName - id - dateOfBirth - groupNumber ProcedureCodeDetail: type: object properties: codePointer: description: procedure code type example: Primary type: string code: description: procedure code example: '99213' type: string description: description: procedure code description example: Established patient office or other outpatient visit type: string coverageStatus: description: procedure code coverage status example: Covered/Approved type: string servicingProvider: $ref: '#/components/schemas/Provider' serviceDetail: description: service detail type example: Surgical type: string expectedFromDate: description: expected service start date example: '2025-10-02' type: string expectedToDate: description: expected service end date example: '2025-10-02' type: string procedureUnitPerFrequencyCount: description: procedure unit per frequency example: '1' type: string procedureUnitOfMeasure: description: procedure unit of measure example: UN type: string procedureFrequency: description: procedure frequency example: '1' type: string procedureUnitCount: description: procedure unit count example: '1' type: string dmeProcurementType: description: procurement type example: durable medical equipment procurement type type: string dmeTotalCost: example: durable medical equipment total cost type: string dmeClinicalIllnessDescText: example: durable medical equipment clinical description type: string dmeSupplyDescText: example: durable medical equipment supply description type: string dmeEnternalFeedingSSONutrInd: example: false type: boolean dmeFormulaNameText: example: durable medical equipment formula name type: string dmeMedicalConditionText: example: durable medical equipment condition text type: string ReferralSubmitProviderInput: type: object properties: npi: description: provider NPI example: '1234567890' type: string taxId: description: provider TIN# example: '98765432' type: string zip: description: provider zip code example: '90201' type: string firstName: description: provider first name example: Carlos type: string lastOrOrgName: description: provider last name or organization name example: Dr. Carlos Clinic type: string specialityCode: description: provider speciality example: CARD type: string gender: description: provider gender example: M type: string city: description: Provider city example: Healthcare City type: string state: description: Provider state code example: CA type: string radius: description: provider search radius example: 50 type: integer contactName: description: contact name for provider example: Carlos Benito type: string phoneNumber: description: provider phone number example: 555-222-3333 type: string preferredLanguage: description: preferred language (SPA, ENG etc) example: SPA type: string required: - npi - taxId - zip Provider: type: object properties: name: description: provider full name example: John J Doe type: string firstName: description: provider first name example: John type: string middleName: description: provider middle name example: J type: string lastName: description: provider last name example: Doe type: string providerOrganizationName: description: provider org name example: Dr. John Doe Clinic type: string npi: description: provider NPI example: '1234567890' type: string taxId: description: provider TIN example: '987654321' type: string contactName: description: provider contact name example: Alison Johnson type: string phoneNumber: description: provider phone number example: 555-123-4567 type: string fax: description: provider fax number example: 555-222-4444 type: string networkStatus: description: provider network status example: IN_NETWORK type: string address: $ref: '#/components/schemas/AddressExt' FacilityServiceDetails: type: object properties: startDate: description: service start date example: '2025-10-02' type: string endDate: description: service end date example: '2025-10-02' type: string serviceDescription: description: service description:- Scheduled, Urgent, Emergent example: Scheduled type: string isPatientAdmitted: description: patient admission flag example: 'Yes' type: string expectedAdmissionDate: description: expected admission date example: '2025-10-02' type: string expectedDischargeDate: description: expected discharge date example: '2025-10-02' type: string actualAdmissionDateTime: description: actual admission date example: '2025-10-02' type: string isPatientDischarged: description: patient discharge flag example: 'Yes' type: string dischargeDate: description: actual discharge date example: '2025-10-02' type: string dischargeLocation: description: discharge location example: Home type: string PriorAuthSearchResponse: type: object properties: caseSummary: description: A list of summarized cases matching the search criteria type: array items: $ref: '#/components/schemas/CaseSummary' caseDescription: $ref: '#/components/schemas/CaseDescription' SearchProvider: type: object properties: name: description: Provider full name example: John J Doe type: string firstName: description: provider first name example: John type: string middleName: description: provider middle name example: J type: string lastName: description: provider last name example: Doe type: string providerOrganizationName: description: provider org name example: Dr. John Doe Clinic type: string npi: description: provider NPI example: '1234567890' type: string taxId: description: provider TIN example: '987654321' type: string contactName: description: provider contact name example: Alison Johnson type: string phoneNumber: description: provider phone number example: 555-222-3333 type: string fax: description: provider fax number example: 555-222-4444 type: string networkStatus: description: provider network status example: IN_NETWORK type: string address: $ref: '#/components/schemas/AddressBase' providerSpeciality: $ref: '#/components/schemas/ProviderSpeciality' ProviderSearchResponse: type: object properties: providers: type: array items: $ref: '#/components/schemas/ExtendedProvider' pagination: $ref: '#/components/schemas/Pagination' description: Response for provider search operation ReferralSearchResult: type: object properties: referralId: description: referral unique identifier example: REF123456789 type: string referralStatus: description: Referral status example: APPROVED type: string referralStatusCode: description: referral status code example: A1 type: string requestingProvider: $ref: '#/components/schemas/SearchProvider' servicingProvider: $ref: '#/components/schemas/SearchProvider' service: $ref: '#/components/schemas/ServiceResponse' rejectionResponse: $ref: '#/components/schemas/RejectionReason' CaseDetail: type: object properties: serviceReferenceNumber: description: unique prior auth case identification number example: AXXXXXXXXX type: string caseStatus: description: current status of the prior auth case example: Open type: string caseStatusReason: description: current status reason for the prior auth case example: Open type: string primaryCarePhysician: description: PCP for the member example: John type: string advanceNotifyDateTime: description: advance notification date-time example: 2025-01-01:00:00:01 type: string admissionNotifyDateTime: description: admission notification date-time example: 2025-01-01:00:00:01 type: string expectedServiceStartDate: description: expected service start date example: '2025-10-02' type: string expectedServiceEndDate: description: expected service end date example: '2025-10-03' type: string actualServiceStartDate: description: actual service start date example: '2025-10-02' type: string actualServiceEndDate: description: actual service end date example: '2025-10-03' type: string PatientDetails: type: object properties: id: description: patient/member id example: '123456789' type: string firstName: description: patient first name example: Alice type: string middleName: description: patient middle name example: A type: string lastName: description: patient last name example: Johnson type: string dateOfBirth: description: patient date of birth example: '1990-12-31' type: string groupNumber: description: patient policy number example: GRP321 type: string relationshipCode: description: patient relationship code example: '18' type: string relationshipDesc: description: patient relationship description example: SELF type: string product: description: member insurance product type example: PPO - Options PPO type: string effectiveDate: description: policy effective date example: '2025-03-01' type: string terminationDate: description: policy termination date example: '2025-12-31' type: string insuranceType: description: insurance type example: Medicare type: string verbalLanguagePreference: description: patient preferred verbal language example: English type: string writtenLanguagePreference: description: patient preferred written language example: English type: string informationalMessage: description: informational message example: A future timeline may be available for this member. For future coverage please call the telephone number located on the back of the member's Medical ID card. type: string RejectionReason: type: object properties: rejectionLevel: description: rejection level example: REFERRAL type: string reasonDescription: description: rejection reason description example: Insufficient medical documentation provided type: string rejectionCode: description: rejection code example: R001 type: string followUpAction: description: rejection follow up action example: RESUBMIT_WITH_DOCUMENTATION type: string rejectionReason: description: rejection reason example: MISSING_DOCUMENTATION type: string validRequestIndicator: description: rejection value request indicator example: N type: string ClinicalNote: type: object properties: createdTime: description: date time for clinical note entry example: 2025-01-01:00:00:01 type: string createdBy: description: clinical entry note created by example: doctor type: string noteText: description: clinical note text example: note text detail type: string SearchProvidersRequest: properties: query: type: string variables: properties: input: $ref: '#/components/schemas/ProviderSearchInput' type: object type: object SubmitReferralRequest: properties: query: type: string variables: properties: input: $ref: '#/components/schemas/ReferralSubmitInput' type: object type: object SearchReferralsRequest: properties: query: type: string variables: properties: input: $ref: '#/components/schemas/ReferralSearchInput' type: object type: object SearchPriorAuthsRequest: properties: query: type: string variables: properties: input: $ref: '#/components/schemas/PriorAuthSearchInput' type: object type: object 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