This data model communicates patient demographic and clinical information from a referring provider to send the patient's case to another provider.
This typically differs from a consultation, where a provider may review a patient without assuming authority over the patient’s care. Referrals can be internal to an organization (e.g., from one department to another) or external between organizations.
A referral is useful to maintain the administrative aspects of a referral order. You can receive notifications when:
- A new referral order is placed.
- An existing referral order is modified or canceled.
- An authorization review is requested or responded to.
Or, you can search for referral orders based on a patient's demographic and insurance information.
Receive a notification after a payer or third party reviews an authorization request.
The Referral object is deprecated in favor of the Authorization object.
Request Body Schema
- Metarequired, object- DataModelrequired, stringReliableReferral 
- EventTyperequired, stringReliableAuthResponse 
- EventDateTimestring, nullReliableDisplays the UTC date and time that an outgoing request is delivered or an incoming request is received. 
 ISO 8601 Format
- Testboolean, nullReliableIndicates whether the request is a test or not. 
- SourceobjectContains the information for the system initiating the message, including the source ID and name. 
 Included in messages from Redox- IDstring, nullReliableIdentifies the system initiating the message. If you have multiple OAuth API keys per environment type, this value is required. If you have only one OAuth API key per environment type, or you're using legacy API keys, this value is optional. 
 UUID
- Namestring, nullReliableDisplays the name of the system initiating the message. 
 
- DestinationsArray of objectContains the information for the endpoint(s) receiving the request. A request must contain at least one destination, but asynchronous requests can have more than one destination. Synchronous requests like queries can only support one destination. 
 Required when sending data to Redox.- IDstring, nullReliableIdentifies the endpoint that the request is directed to. 
 UUID
- Namestring, nullReliableDisplays the name of the endpoint that the request is directed to. 
 
- LogsArray of objectContains the log identifier(s) for the request. - IDstring, nullReliableIdentifies the request log(s) that correspond to this request. You can use this value to locate the relevant log in the Redox dashboard for support and reference. 
 UUID
- AttemptIDstring, nullReliableIdentifies the request log attempt value, which is useful when retries are possible. 
 UUID
 
- FacilityCodestring, nullPossibleCode for the facility related to the message. 
 Only use this field if a health system indicates you should. The code is specific to the health system's EHR and might not be unique across health systems. In general, the facility fields within the data models (e.g. OrderingFacility) are more reliable and informative.
 
- Patientrequired, object- Identifiersrequired, Array of objectList of IDs and ID types that identify the patient - IDrequired, stringReliableID for the patient 
- IDTyperequired, stringReliableType of ID. 
 E.g. MRN, EPI
 
- Demographicsobject- FirstNamestring, nullReliablePatient's first name 
- MiddleNamestring, nullPossiblePatient's middle name or middle initial. For patients with multiple middle names, all their middle names are included in this field. 
- LastNamestring, nullReliablePatient's last name 
- DOBstring, nullReliablePatient's date of birth. 
 In ISO 8601 format
- SSNstring, nullProbablePatient's social security number 
- Sexstring, nullReliableValue SetPatient's sex 
- Racestring, nullPossibleValue SetPatient's race 
- IsHispanicboolean, nullPossibleValue SetIndicates if the patient is of hispanic origin. 
- Religionstring, nullPossibleValue SetPatient's religious affiliation 
- MaritalStatusstring, nullPossibleValue SetPatient's marital status 
- IsDeceasedboolean, nullPossibleIndicates if the patient is deceased 
- DeathDateTimestring, nullPossibleDate and Time the patient was proclaimed deceased. 
 ISO 8601 Format
- PhoneNumberobject- Homestring, nullProbablePatient's home phone number. 
 In E. 164 Format. (e.g. +16085551234)
- Officestring, nullProbablePatient's office phone number. 
 In E. 164 Format. (e.g. +16085551234)
- Mobilestring, nullProbablePatient's mobile phone number. 
 In E. 164 Format. (e.g. +16085551234)
 
- EmailAddressesArray of stringPatient's email address(es) 
- Languagestring, nullPossibleValue SetPatient's primary spoken language. 
 In ISO 639-1 alpha values (e.g. 'en'). Supported Values
- CitizenshipArray of stringPatient's nation(s) of citizenship. 
 In ISO 3166 alpha 2 format (e.g. 'US').
- AddressobjectPatient's home address - StreetAddressstring, nullProbableStreet address 
- Citystring, nullProbableCity 
- Statestring, nullProbableState 
- ZIPstring, nullProbableZIP 
- Countystring, nullPossibleCounty 
- Countrystring, nullPossibleValue SetCountry 
 
 
- NotesArray of stringPatient-level notes 
- ContactsArray of object- FirstNamestring, nullPossibleFirst name of the contact 
- MiddleNamestring, nullPossibleMiddle name of the contact 
- LastNamestring, nullPossibleLast name of the contact 
- AddressobjectAddress of the contact - StreetAddressstring, nullPossibleStreet address 
- Citystring, nullPossibleCity 
- Statestring, nullPossibleState 
- ZIPstring, nullPossibleZIP 
- Countystring, nullPossibleCounty 
- Countrystring, nullPossibleValue SetCountry 
 
- PhoneNumberobject- Homestring, nullPossibleHome phone number. 
 In E. 164 Format. (e.g. +16085551234)
- Officestring, nullPossibleOffice phone number. 
 In E. 164 Format. (e.g. +16085551234)
- Mobilestring, nullProbableMobile phone number. 
 In E. 164 Format. (e.g. +16085551234)
 
- RelationToPatientstring, nullPossibleValue SetPersonal relationship to the patient. 
 e.x. Father, Spouse
- EmailAddressesArray of stringEmail address(es) of the contact person 
- RolesArray of stringRole of this contact for the patient. 
 e.x. Employer, Emergency Contact
 
- InsurancesArray of objectList of insurance coverages for the patient - Planobject- IDstring, nullProbableIdentifier of insurance plan 
- IDTypestring, nullProbableID type of insurance plan 
- Namestring, nullProbableName of insurance plan 
- Typestring, nullPossibleType of insurance plan 
 
- MemberNumberstring, nullPossiblePatient member number 
- Companyobject- IDstring, nullProbableID of insurance company (payor) 
- IDTypestring, nullProbableID type of insurance company (payor) 
- Namestring, nullProbableName of insurance company (payor) 
- AddressobjectInsurance company's address - StreetAddressstring, nullProbableStreet address 
- Citystring, nullProbableCity 
- Statestring, nullProbableState 
- ZIPstring, nullProbableZIP 
- Countystring, nullPossibleCounty 
- Countrystring, nullPossibleValue SetCountry 
 
- PhoneNumberstring, nullProbableInsurance companys phone number. 
 In E. 164 Format (i.e. +16085551234)
 
- GroupNumberstring, nullProbableInsurance policy group number 
- GroupNamestring, nullProbableInsurance policy group name 
- EffectiveDatestring, nullProbableEffect date of this insurance policy. 
 In YYYY-MM-DD format
- ExpirationDatestring, nullProbableExpiration date of this insurance policy. 
 In YYYY-MM-DD format
- PolicyNumberstring, nullProbableInsurance policy number 
- Prioritystring, nullPossibleValue SetThe insurance priority sequence. 
 If the insurance works in conjunction with other insurance plans, this field contains priority sequence.
- AgreementTypestring, nullProbableValue SetType of insurance agreement. 
- CoverageTypestring, nullProbableValue SetType of insurance agreement. 
 Indicates who will be receiving the bill for the service.
- InsuredobjectIndividual who has the agreement with the insurance company for the related policy - IdentifiersArray of objectList of IDs and ID types that identify the insured - IDstring, nullPossibleID for the insured 
- IDTypestring, nullPossibleType of ID. 
 E.g. MRN, EPI
 
- LastNamestring, nullPossibleLast name of the insured 
- MiddleNamestring, nullPossibleMiddle name of the insured 
- FirstNamestring, nullPossibleFirst name of the insured 
- SSNstring, nullPossibleInsured's social security number 
- Relationshipstring, nullPossibleValue SetRelationship of the insured to the patient 
- DOBstring, nullPossibleDate of birth of the insured. 
 In YYYY-MM-DD format
- Sexstring, nullPossibleValue SetSex of the insured 
- AddressobjectAddress of the insured - StreetAddressstring, nullProbableStreet address 
- Citystring, nullProbableCity 
- Statestring, nullProbableState 
- ZIPstring, nullProbableZIP 
- Countystring, nullPossibleCounty 
- Countrystring, nullPossibleValue SetCountry 
 
 
 
 
- Referralobject- IDstring, nullReliableThe Health System ID of the referral 
- IDTypestring, nullReliableThe ID type 
- AlternateIDstring, nullReliableThe alternate ID of the referral, often used by external/3rd party systems 
- Typestring, nullReliableValue SetThe type of the referral 
- Categorystring, nullReliableValue SetThe category of the referral 
- Prioritystring, nullReliableValue SetThe priority of the referral 
- Statusstring, nullReliableValue SetThe status of the referral 
- DateTimestring, nullReliableThe date and time the referral is considered active. 
 ISO 8601 Format
- ExpirationDateTimestring, nullReliableThe date and time the referral expires. 
 ISO 8601 Format
- ProcessDateTimestring, nullReliableThe date and time the referral was processed. 
 ISO 8601 Format
- Reasonstring, nullProbableValue SetThe reason for the referral 
- ProviderSpecialtystring, nullPossibleThe provider specialty of the referral 
- DepartmentSpecialtystring, nullPossibleThe department specialty of the referral 
- NotesArray of stringReferral Notes 
- Authorizationobject- Planobject- IDstring, nullPossibleThe ID of the plan 
- IDTypestring, nullPossibleThe ID type 
- Namestring, nullPossibleThe name of the plan 
 
- Companyobject- IDstring, nullPossibleThe ID of the payor 
- IDTypestring, nullPossibleThe ID type 
- Namestring, nullPossibleThe name of the payor 
 
- DateTimestring, nullPossibleThe date and time the authorization is effective. 
 ISO 8601 Format
- ExpirationDateTimestring, nullPossibleThe date and time the authorization expires. 
 ISO 8601 Format
- Numberstring, nullPossibleThe identifier for the authorization assigned by the payor 
- ReimbursementLimitstring, nullPossibleThe reimbursement limit for this referral 
- RequestedTreatmentCountstring, nullPossibleThe number of treatments requested 
- RequestedTreatmentUnitsstring, nullPossibleThe units associated to the treatment count. 
 e.g. 'instances' or 'days'
- AuthorizedTreatmentCountstring, nullPossibleThe number of treatments authorized 
- NotesArray of stringNotes about the authorizations 
 
- DiagnosesArray of objectList of diagnoses - Codestring, nullProbableCode for the diagnoses 
- Codesetstring, nullProbableValue SetCode set used to identify the diagnoses. 
 One of the following: ICD-9, ICD-10, HCPCS, CPT
- Namestring, nullProbableName of the diagnoses 
- Typestring, nullPossibleValue SetType of the diagnosis 
- DocumentedDateTimestring, nullPossibleDateTime the diagnoses was documented. 
 ISO 8601 Format
- NotesArray of stringNotes about the diagnosis 
 
- ProceduresArray of objectOrdered procedure - Codestring, nullReliableCode for the procedure 
- Codesetstring, nullReliableCode set used to identify the procedure. 
 CPT, HCPCS, SNOMED, or LOINC. If no code set is specified, a health system specific identifier is being used.
- Descriptionstring, nullReliableDescription of the procedure 
- NotesArray of stringNotes about the procedure 
- Quantitystring, nullPossibleNumber of instances for the procedure 
- Unitsstring, nullPossibleRelated units associated to the procedure quantity 
- ModifiersArray of stringAssociated procedure modifiers 
- Statusstring, nullPossibleStatus of the procedure 
- StatusReasonstring, nullPossibleReason for the procedure status 
- Authorizationobject- DateTimestring, nullProbableThe date and time the authorization for this service is effective. 
 ISO 8601 Format
- ExpirationDateTimestring, nullProbableThe date and time the authorization for this service expires. 
 ISO 8601 Format
 
 
- ProvidersArray of object- IDstring, nullPossibleID of the provider. 
 This ID is often required for Inpatient Visits.
- IDTypestring, nullPossibleID type of the ID for the provider 
- FirstNamestring, nullPossibleFirst name of the undefined 
- LastNamestring, nullPossibleLast name of the undefined 
- CredentialsArray of stringList of credentials for the undefined. 
 e.g. MD, PhD
- AddressobjectProvider's address - StreetAddressstring, nullPossibleStreet address 
- Citystring, nullPossibleCity 
- Statestring, nullPossibleState 
- ZIPstring, nullPossibleZIP 
- Countystring, nullPossibleCounty 
- Countrystring, nullPossibleValue SetCountry 
 
- EmailAddressesArray of stringProvider's email address(es) 
- PhoneNumberobject- Officestring, nullPossibleProvider's office phone number. 
 In E. 164 Format. (e.g. +16085551234)
 
- Typestring, nullPossibleValue SetThe type of provider 
- ContactInfostring, nullPossibleAdditional contact information for this provider 
- LocationobjectProvider's location - Typestring, nullPossibleType of location. 
 Examples: Clinic, Department, Home, Nursing Unit, Provider's Office, Phone
- Facilitystring, nullPossibleFacility. 
 Example: Community Hospital
- FacilityIdentifiersArray of objectList of IDs specific to this facility - IDstring, nullPossibleAn ID specific to this facility 
- IDTypestring, nullPossibleThe source or system to which this ID pertains. 
 Could be an OID or a human-readable name
 
- Departmentstring, nullPossibleDepartment 
- DepartmentIdentifiersArray of objectList of IDs specific to this department - IDstring, nullPossibleAn ID specific to this department 
- IDTypestring, nullPossibleThe source or system to which this ID pertains. 
 Could be an OID or a human-readable name
 
- Roomstring, nullPossibleRoom. 
 Example: 136
 
 
- Visitobject- VisitNumberstring, nullPossibleVisit Number. 
 Unique ID of the visit associated to the referral
 
- ServiceLocationstring, nullPossibleValue SetCode characterizing the location where the referral or service is to take place. 
- RequestTypestring, nullReliableValue SetCode indicating the type of request. 
- Code indicating a related illness or injury. 
- StatusReasonstring, nullPossibleThe reason for the status of the referral. 
 
- Authorizationobject- Requestobject- IDstring, nullReliableThe requesting system's ID for the authorization review request 
- IDTypestring, nullReliableThe requesting system's ID type for the authorization review request 
 
- AlternateIDstring, nullPossibleThe alternate ID of the authorization review request, often used by external/3rd party systems 
- Numberstring, nullReliableThe authorizing system's ID 
- Typestring, nullReliableValue SetThe type of authorization request 
- Categorystring, nullReliableValue SetThe category of authorization request 
- CertificationCodestring, nullReliableValue SetThe type of certification being sought by the requestor 
- ServiceTypestring, nullReliableValue SetThe type of service associated to the authorization request 
- ServiceLocationstring, nullReliableValue SetThe priority of the referral 
- Code indicating a related illness or injury. 
 One of the following: Accident, Employment, Other
- ServiceLevelstring, nullReliableValue SetThe priority of the referral 
- EventDatestring, nullReliableThe expected date of the requested service. 
 ISO 8601 Format
- Quantityobject- Valuestring, nullReliableApproved quantity 
- Unitsstring, nullReliableAssociated units to approved quantity 
 
- AdmissionSourcestring, nullPossibleValue SetCode indicating the source of an inpatient admission 
- AdmissionTypestring, nullPossibleValue SetCode indicating the type of inpatient admission. 
- AdditionalDatesArray of objectCollection of additional dates related to the authorization - DateTimestring, nullProbable
- Typestring, nullProbableValue SetType of date value. 
 e.x. Service Period Start (https://ushik.ahrq.gov/ViewItemDetails?system=sdo&itemKey=133121000)
 
- Decisionstring, nullReliableValue SetAuthorization decision 
- DecisionReasonstring, nullReliableAssociated reason for the decision 
- IssueDatestring, nullProbableThe date the authorization's approval was issued. 
 ISO 8601 Format
- EffectiveDatestring, nullProbableThe effective date of the approved authorization. 
 ISO 8601 Format
- ExpirationDatestring, nullProbableThe date when the approval for the authorization expires. 
 ISO 8601 Format
- DiagnosesArray of objectList of diagnoses - Codestring, nullProbableCode for the diagnosis 
- Codesetstring, nullProbableValue SetCode set used to identify the diagnosis. 
 One of the following: ICD-9, ICD-10, HCPCS, CPT
- Namestring, nullProbableName of the diagnosis 
- Typestring, nullPossibleValue SetType of the diagnosis 
- DocumentedDateTimestring, nullPossibleDateTime the diagnosis was documented. 
 ISO 8601 Format
 
- NotesArray of stringNotes about the authorization 
- ServicesArray of objectServices included in the authorization review - Codestring, nullReliableCode for the service line 
- Codesetstring, nullReliableCode set used to identify the service line. 
 CPT, HCPCS, SNOMED, or LOINC. If no code set is specified, a health system specific identifier is being used.
- Descriptionstring, nullReliableDescription of the service line 
- RevenueCodestring, nullProbableInstitutional Revenue Code 
- Quantityobject- Valuestring, nullReliableApproved service line quantity 
- Unitsstring, nullReliableAssociated units to the approved quantity 
 
- ModifiersArray of stringService line modifiers 
- ServiceDatestring, nullProbableThe date the service line is to be performed, if different than the authorization's event date. 
 ISO 8601 Format
- AuthorizationNumberstring, nullProbableThe identifier assigned to the service by the reviewer 
- Decisionstring, nullReliableValue SetAuthorization service line decision 
- DecisionReasonstring, nullReliableAssociated reason for the decision 
- IssueDatestring, nullProbableThe date the service line's approval was issued, if different than the authorization's issue date. 
 ISO 8601 Format
- EffectiveDatestring, nullProbableThe effective date of the approved service line, if different than the authorization's effective date. 
 ISO 8601 Format
- ExpirationDatestring, nullProbableThe date when the approval for the service line expires, if different than the authorization's expiration date. 
 ISO 8601 Format
- NotesArray of stringNotes about the service line 
 
- ProvidersArray of object- IDstring, nullPossibleID of the provider. 
 This ID is often required for Inpatient Visits.
- IDTypestring, nullPossibleID type of the ID for the provider 
- FirstNamestring, nullPossibleFirst name of the undefined 
- LastNamestring, nullPossibleLast name of the undefined 
- CredentialsArray of stringList of credentials for the undefined. 
 e.g. MD, PhD
- AddressobjectProvider's address - StreetAddressstring, nullPossibleStreet address 
- Citystring, nullPossibleCity 
- Statestring, nullPossibleState 
- ZIPstring, nullPossibleZIP 
- Countystring, nullPossibleCounty 
- Countrystring, nullPossibleValue SetCountry 
 
- EmailAddressesArray of stringProvider's email address(es) 
- PhoneNumberobject- Officestring, nullPossibleProvider's office phone number. 
 In E. 164 Format. (e.g. +16085551234)
 
- Typestring, nullPossibleValue SetThe type of provider 
- ContactInfostring, nullPossibleAdditional contact information for this provider 
- LocationobjectProvider's location - Typestring, nullPossibleType of location. 
 Examples: Clinic, Department, Home, Nursing Unit, Provider's Office, Phone
- Facilitystring, nullPossibleFacility. 
 Example: Community Hospital
- FacilityIdentifiersArray of objectList of IDs specific to this facility - IDstring, nullPossibleAn ID specific to this facility 
- IDTypestring, nullPossibleThe source or system to which this ID pertains. 
 Could be an OID or a human-readable name
 
- Departmentstring, nullPossibleDepartment 
- DepartmentIdentifiersArray of objectList of IDs specific to this department - IDstring, nullPossibleAn ID specific to this department 
- IDTypestring, nullPossibleThe source or system to which this ID pertains. 
 Could be an OID or a human-readable name
 
- Roomstring, nullPossibleRoom. 
 Example: 136