Referral QueryResponse

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.

EHR support for Referral

EHR systems with advanced referral management capabilities and robust interfacing libraries typically support the Referral data model via an HL7v2 REF interface or their own proprietary API.

Alternatively, some EHR systems may not support the Referral data model. However, since a referral can be a specific type of order when it pertains to a transfer of patient responsibility for specialty care, an EHR system may support creating a referral with the Order data model instead. Just note that you may not be able to update the referral details after it’s created. This customized type of workflow varies per EHR system. Work with your connection and your Technical Account Manager to determine which data model is best for your referral workflow.

QueryResponse

Receive any matching referral order(s) based on the query parameters defined in Referral.Query. Any matches are listed in the Referrals array.

Beta

Request Body Schema

Show Required Fields Only

Show Translation Fields

Meta
required, object
- DataModel
  required, string
  Reliable
  Referral
- EventType
  required, string
  Reliable
  QueryResponse
- EventDateTime
  string, null
  Reliable
  Displays the UTC date and time that an outgoing request is delivered or an incoming request is received.
  ISO 8601 Format
- Test
  boolean, null
  Reliable
  Indicates whether the request is a test or not.
- Source
  object
  Contains the information for the system initiating the message, including the source ID and name.
  Included in messages from Redox
  ID
  string, null
  Reliable
  Identifies 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
  Name
  string, null
  Reliable
  Displays the name of the system initiating the message.
- Destinations
  Array of object
  Contains 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.
  ID
  string, null
  Reliable
  Identifies the endpoint that the request is directed to.
  UUID
  Name
  string, null
  Reliable
  Displays the name of the endpoint that the request is directed to.
- Logs
  Array of object
  Contains the log identifier(s) for the request.
  ID
  string, null
  Reliable
  Identifies 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
  AttemptID
  string, null
  Reliable
  Identifies the request log attempt value, which is useful when retries are possible.
  UUID
- FacilityCode
  string, null
  Possible
  Code 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.

Referrals

Array of object

The list of referrals

ID
string, null
Reliable
The Health System ID of the referral
IDType
string, null
Reliable
The ID type
AlternateID
string, null
Reliable
The alternate ID of the referral, often used by external/3rd party systems
Type
string, null
Reliable
Value Set
The type of the referral
Category
string, null
Reliable
Value Set
The category of the referral
Priority
string, null
Reliable
Value Set
The priority of the referral
Status
string, null
Reliable
Value Set
The status of the referral
DateTime
string, null
Reliable
The date and time the referral is considered active.
ISO 8601 Format
ExpirationDateTime
string, null
Reliable
The date and time the referral expires.
ISO 8601 Format
ProcessDateTime
string, null
Reliable
The date and time the referral was processed.
ISO 8601 Format
Reason
string, null
Probable
Value Set
The reason for the referral
ProviderSpecialty
string, null
Possible
The provider specialty of the referral
DepartmentSpecialty
string, null
Possible
The department specialty of the referral
Notes
Array of string
Referral Notes
Authorization
object
- Plan
  object
  ID
  string, null
  Possible
  The ID of the plan
  IDType
  string, null
  Possible
  The ID type
  Name
  string, null
  Possible
  The name of the plan
- Company
  object
  ID
  string, null
  Possible
  The ID of the payor
  IDType
  string, null
  Possible
  The ID type
  Name
  string, null
  Possible
  The name of the payor
- DateTime
  string, null
  Possible
  The date and time the authorization is effective.
  ISO 8601 Format
- ExpirationDateTime
  string, null
  Possible
  The date and time the authorization expires.
  ISO 8601 Format
- Number
  string, null
  Possible
  The identifier for the authorization assigned by the payor
- ReimbursementLimit
  string, null
  Possible
  The reimbursement limit for this referral
- RequestedTreatmentCount
  string, null
  Possible
  The number of treatments requested
- RequestedTreatmentUnits
  string, null
  Possible
  The units associated to the treatment count.
  e.g. 'instances' or 'days'
- AuthorizedTreatmentCount
  string, null
  Possible
  The number of treatments authorized
- Notes
  Array of string
  Notes about the authorizations
Diagnoses
Array of object
List of diagnoses
- Code
  string, null
  Probable
  Code for the diagnoses
- Codeset
  string, null
  Probable
  Value Set
  Code set used to identify the diagnoses.
  One of the following: ICD-9, ICD-10, HCPCS, CPT
- Name
  string, null
  Probable
  Name of the diagnoses
- Type
  string, null
  Possible
  Value Set
  Type of the diagnosis
- DocumentedDateTime
  string, null
  Possible
  DateTime the diagnoses was documented.
  ISO 8601 Format
- Notes
  Array of string
  Notes about the diagnosis
Procedures
Array of object
Ordered procedure
- Code
  string, null
  Reliable
  Code for the procedure
- Codeset
  string, null
  Reliable
  Code 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.
- Description
  string, null
  Reliable
  Description of the procedure
- Notes
  Array of string
  Notes about the procedure
- Quantity
  string, null
  Possible
  Number of instances for the procedure
- Units
  string, null
  Possible
  Related units associated to the procedure quantity
- Modifiers
  Array of string
  Associated procedure modifiers

Value
Other
Consultation
Laboratory
Radiology
Medical
Skilled Nursing
Home Care
Psychiatric

Value
Outpatient
Inpatient
Emergency
Ambulatory

Value
STAT
ASAP
Routine

Value
Accepted
Pending
Rejected
Expired
Closed

Value
Patient Preference
Second Opinion
Provider Ordered
Work Load

Value
ICD-10
ICD-9
HCPCS
CPT
Unknown
SNOMED CT

Value
Unknown
Admitting
Final
Self
Working
Principal

Providers

Array of object

ID
string, null
Possible
ID of the provider.
This ID is often required for Inpatient Visits.
IDType
string, null
Possible
ID type of the ID for the provider
FirstName
string, null
Possible
First name of the undefined
LastName
string, null
Possible
Last name of the undefined
Credentials
Array of string
List of credentials for the undefined.
e.g. MD, PhD

Address

object

Provider's address

StreetAddress
string, null
Possible
Street address
City
string, null
Possible
City
State
string, null
Possible
State
ZIP
string, null
Possible
ZIP
County
string, null
Possible
County

Country

string, null

Possible

Value Set

Country

EmailAddresses
Array of string
Provider's email address(es)
PhoneNumber
object
- Office
  string, null
  Possible
  Provider's office phone number.
  In E. 164 Format. (e.g. +16085551234)
Type
string, null
Possible
Value Set
The type of provider
ContactInfo
string, null
Possible
Additional contact information for this provider
Location
object
Provider's location
- Type
  string, null
  Possible
  Type of location.
  Examples: Clinic, Department, Home, Nursing Unit, Provider's Office, Phone
- Facility
  string, null
  Possible
  Facility.
  Example: Community Hospital
- FacilityIdentifiers
  Array of object
  List of IDs specific to this facility
  ID
  string, null
  Possible
  An ID specific to this facility
  IDType
  string, null
  Possible
  The source or system to which this ID pertains.
  Could be an OID or a human-readable name
- Department
  string, null
  Possible
  Department
- DepartmentIdentifiers
  Array of object
  List of IDs specific to this department
  ID
  string, null
  Possible
  An ID specific to this department
  IDType
  string, null
  Possible
  The source or system to which this ID pertains.
  Could be an OID or a human-readable name
- Room
  string, null
  Possible
  Room.
  Example: 136

Visit
object
- VisitNumber
  string, null
  Possible
  Visit Number.
  Unique ID of the visit associated to the referral

Value
AF
AX
AL
DZ
AS
AD
AO
AI
AQ
AG
AR
AM
AW
AU
AT
AZ
BS
BH
BD
BB
BY
BE
BZ
BJ
BM
BT
BO
IO
CM
CL
CO
CI
DK
EC
ER
FK
TF
GM
GI
GW
VA
IS
IM
JP
KI
LS
LT
MK
MV
MX
MS
NA
NC
MP
PK
PG
PL
RU
PM
SA
SG
SB
SS
SE
TZ
TO
TV
US
VN
EH
ZW
BQ
BR
BF
CA
TD
KM
CK
CU
DO
EE
FI
GE
GL
GN
GY
IN
IE
JE
KW
LB
LY
MO
ML
MR
MN
MM
NZ
NU
OM
PY
PT
RO
KN
SN
RS
ZA
LK
SJ
SY
TK
TM
UG
UM
UZ
WF
BA
BG
CV
CX
CD
CW
DJ
GQ
FO
PF
DE
GD
GG
HT
HK
IR
IL
KE
KG
LU
MY
MT
MU
ME
MZ
NP
NF
PW
PH
QA
BL
MF
ST
SX
SI
GS
SR
TJ
TG
TN
UA
VU
VG
BW
BN
KH
KY
CC
CR
CY
EG
FJ
FR
GH
GP
GU
HN
IQ
JM
KZ
KP
LA
LR
MW
MH
YT
MD
MA
NI
NG
NO
PA
PN
RE
RW
LC
SM
SC
SK
ES
CH
TH
TT
TR
GB
VE
VI
ZM
BV
BI
CF
CN
CG
HR
CZ
DM
SV
ET
GF
GA
GR
GT
HM
HU
ID
IT
JO
KR
LV
LI
MG
MQ
FM
MC
NR
NL
NE
PS
PE
PR
SH
VC
WS
SL
SO
SD
SZ
TW
TL
TC
AE
UY
YE
DR

Value
Referred To Provider
Referring Provider
Patient PCP
Other

Example

json

1
{
2
  "Meta": {
3
    "DataModel": "Referral",
4
    "EventType": "QueryResponse",
5
    "EventDateTime": "2025-10-31T18:29:39.481Z",
6
    "Test": true,
7
    "Source": {
8
      "ID": "7ce6f387-c33c-417d-8682-81e83628cbd9",
9
      "Name": "Redox Dev Tools"
10
    },
11
    "Destinations": [
12
      {
13
        "ID": "af394f14-b34a-464f-8d24-895f370af4c9",
14
        "Name": "Redox EMR"
15
      }
16
    ],
17
    "Logs": [
18
      {
19
        "ID": "d9f5d293-7110-461e-a875-3beb089e79f3",
20
        "AttemptID": "925d1617-2fe0-468c-a14c-f8c04b572c54"
21
      }
22
    ],
23
    "FacilityCode": null
24
  },
25
  "Referrals": [
26
    {
27
      "ID": "4356789876",
28
      "IDType": null,
29
      "AlternateID": "2133311",
30
      "Type": "Medical",
31
      "Category": "Outpatient",
32
      "Priority": "Routine",
33
      "Status": "Pending",
34
      "DateTime": "2015-05-05T00:00:00.000Z",
35
      "ExpirationDateTime": "2015-06-05T00:00:00.000Z",
36
      "ProcessDateTime": null,
37
      "Reason": "Provider Ordered",
38
      "ProviderSpecialty": null,
39
      "DepartmentSpecialty": null,
40
      "Notes": [],
41
      "Authorization": {
42
        "Plan": {
43
          "ID": "31572",
44
          "IDType": null,
45
          "Name": "HMO Deductible Plan"
46
        },
47
        "Company": {
48
          "ID": "60054",
49
          "IDType": null,
50
          "Name": "aetna (60054 0131)"
51
        },
52
        "DateTime": "2015-05-05T00:00:00.000Z",
53
        "ExpirationDateTime": "2015-06-05T00:00:00.000Z",
54
        "Number": "9140860055",
55
        "ReimbursementLimit": null,
56
        "RequestedTreatmentCount": null,
57
        "RequestedTreatmentUnits": null,
58
        "AuthorizedTreatmentCount": null,
59
        "Notes": []
60
      },
61
      "Diagnoses": [],
62
      "Procedures": [
63
        {
64
          "Code": "400500400",
65
          "Codeset": "CPT4",
66
          "Description": "Anticoag Therapy Referral",
67
          "Notes": [],
68
          "Quantity": null,
69
          "Units": null,
70
          "Modifiers": []
71
        }
72
      ],
73
      "Providers": [
74
        {
75
          "ID": "4236464757",
76
          "IDType": "NPI",
77
          "FirstName": "John",
78
          "LastName": "Slate",
79
          "Credentials": [
80
            "DO"
81
          ],
82
          "Address": {
83
            "StreetAddress": "500 First St.",
84
            "City": "Clayton",
85
            "State": "MO",
86
            "ZIP": "63105",
87
            "County": "Saint Louis",
88
            "Country": "USA"
89
          },
90
          "EmailAddresses": [],
91
          "PhoneNumber": {
92
            "Office": null
93
          },
94
          "Type": "Referring Provider",
95
          "ContactInfo": null,
96
          "Location": {
97
            "Type": null,
98
            "Facility": null,
99
            "FacilityIdentifiers": [],
100
            "Department": null,
101
            "DepartmentIdentifiers": [],
102
            "Room": null
103
          }
104
        }
105
      ],
106
      "Visit": {
107
        "VisitNumber": null
108
      }
109
    }
110
  ]
111
}

FHIR® is a registered trademark of Health Level Seven International (HL7) and is used with the permission of HL7. Use of this trademark does not constitute an endorsement of products/services by HL7®.