Skip to main content

Submit Service Request Message

This message provides the required information to open a Service Request (a.k.a., Referral) in Netsmart Referral Manager.

{
// ...
"eventCoding": {
"system": "http://ntst.com/fhir/message-events",
"code": "submit-service-request"
}
// ...
}

Authorization

This message will require the application obtain authorization using one of the following custom scopes based on SMART.

  • v1: [patient|user|system]/Messaging.[write|*]
  • v2: To be determined. (future)

Workflow

Payload

The payload for this message will consist of a Bundle with the type message and additional resources that make up the relevant information for the Service Request.

ResourceCardinalityNote
MessageHeader1..1Required for all FHIR messages and must be the first entry in the Bundle.
ServiceRequest1..1Details of the ServiceRequest.
Patient1..1Subject of the ServiceRequest.
Condition0..*Associated conditions for this ServiceRequest.
Coverage0..*Associated insurance coverage for this ServiceRequest.
Location0..*Locations reference by the ServiceRequest or PractitionerRoles.
Observation0..*Associated Observations for this ServiceRequest.
Organization0..*Organizations referenced by the ServiceRequest or other resources.
Practitioner0..*Practitioners referenced by the ServiceRequest or other resources.
PractitionerRole0..*PractitionerRoles referenced by the ServiceRequest or other resources.
QuestionnaireResponse0..*Supporting information for the ServiceRequest. These should be listed in MessageHeader.focus since they are not referenced elsewhere in the Bundle.

Entity Relationship Diagram

Each resource included in the reference must be referenced by another resource within the Bundle. The diagram below illustrates the relationships and references.

Examples

Sample Request Payload

{
"resourceType": "Bundle",
"id": "607e4728-5d96-43a8-8be0-418313050140",
"type": "message",
"entry": [
{
"fullUrl": "https://fhir.netsmartcloud.com/v4/MessageHeader/2605ab80-d03a-44b7-95b5-f76bf53cb36a",
"resource": {
"resourceType": "MessageHeader",
"id": "2605ab80-d03a-44b7-95b5-f76bf53cb36a",
"eventCoding": {
"system": "http://ntst.com/fhir/message-events",
"code": "submit-service-request"
},
"focus": [
{
"reference": "urn:uuid:eff3c2b7-a6f4-40fd-8513-d599f45875ff"
}
]
}
},
{
"fullUrl": "https://fhir.netsmartcloud.com/v4/ServiceRequest/eff3c2b7-a6f4-40fd-8513-d599f45875ff",
"resource": {
"resourceType": "ServiceRequest",
"id": "eff3c2b7-a6f4-40fd-8513-d599f45875ff",
"extension": [
// We can support multiple extension data types via the message. However, these will only be read if configured in Referral Manager.
],
"identifier": [
// We can support the exchange of identifiers as well. Configure the Systems in Referral Manager to add to the Referral.
],
"status": "active",
"intent": "proposal",
"subject": {
"reference": "urn:uuid:9d72e641-d314-4fb7-afa5-5b48696b2d21"
},
"requester": {
"reference": "urn:uuid:aadf1331-510a-4cd0-8478-6031b56e24a8"
},
"performer": [
{
"reference": "urn:uuid:2583aae2-d7d0-4b69-8fee-2ed7a12e69eb"
},
{
"reference": "urn:uuid:acb89754-d395-4d0c-be7d-cd058ccb376b"
}
],
"locationReference": [
{
"reference": "urn:uuid:6d11f9fb-66d6-4856-b917-78fdc2d46926"
}
],
"insurance": [
{
"reference": "urn:uuid:07ad4455-a442-4c6f-b080-7053e8b38b07"
}
],
"supportingInfo": [
{
"reference": "urn:uuid:3d35ec04-bcdc-490e-9721-b5a4f68310d3"
},
{
"reference": "https://fhir.netsmartcloud.com/v4/DocumentReference/12345678"
},
{
"reference": "https://fhir.netsmartcloud.com/v4/DocumentReference/45689014"
},
{
"reference": "urn:uuid:70617260-8376-4fe3-a246-da6d012d58b4"
},
{
"reference": "urn:uuid:596bb1c8-10c1-4f66-a1c7-3e330d3eab0e"
}
],
"note": [
{
"text": "This can be a supporting note regarding the ServiceRequest."
},
{
"text": "Here's another note."
}
]
}
},
{
"fullUrl": "https://fhir.netsmartcloud.com/v4/Patient/9d72e641-d314-4fb7-afa5-5b48696b2d21",
"resource": {
"resourceType": "Patient",
"id": "9d72e641-d314-4fb7-afa5-5b48696b2d21",
"extension": [
{
"url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-race",
"extension": [
{
"url": "ombCategory",
"valueCoding": {
"system": "urn:oid:2.16.840.1.113883.6.238",
"code": "2106-3",
"display": "White"
}
},
{
"url": "detailed",
"valueCoding": {
"system": "urn:oid:2.16.840.1.113883.6.238",
"code": "2106-3",
"display": "White"
}
},
{
"url": "text",
"valueString": "White"
}
]
},
{
"url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-ethnicity",
"extension": [
{
"url": "ombCategory",
"valueCoding": {
"system": "urn:oid:2.16.840.1.113883.6.238",
"code": "2186-5",
"display": "Not Hispanic or Latino"
}
},
{
"url": "detailed",
"valueCoding": {
"system": "urn:oid:2.16.840.1.113883.6.238",
"code": "2186-5",
"display": "Not Hispanic or Latino"
}
},
{
"url": "text",
"valueString": "Not Hispanic or Latino"
}
]
},
{
"url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-birthsex",
"valueCode": "M"
},
{
"url": "http://hl7.org/fhir/StructureDefinition/patient-citizenship",
"extension": [
{
"url": "code",
"valueCodeableConcept": {
"coding": [
{
"system": "urn:iso:std:iso:3166",
"code": "US"
}
]
}
},
{
"url": "code",
"valuePeriod": {
"start": "2000-03-12T05:00:00+00:00",
"end": "2017-08-31T05:00:00+00:00"
}
}
]
}
],
"identifier": [
// Supported
],
"name": [
{
"text": "First MI Last",
"family": "Last",
"given": [
"First",
"MI"
],
"suffix": "JR"
}
],
"telecom": [
{
"use": "home",
"system": "phone",
"value": "5556667788",
"rank": 1
},
{
"use": "work",
"system": "phone",
"value": "5556321478"
},
{
"use": "home",
"system": "email",
"value": "myemail20004@gmail.com"
}
],
"gender": "male",
"birthDate": "1997-01-16",
"deceasedBoolean": false,
"address": [
{
"use": "home",
"line": [
"4950 College Blvd."
],
"city": "Overland Park",
"state": "KS",
"postalCode": "66211",
"country": "US",
"period": {
"start": "2015-06-22T05:00:00+00:00"
}
}
],
"maritalStatus": {
"coding": [
{
"system": "urn:oid:2.16.840.1.113883.4.642.3.29",
"code": "C",
"display": "Common Law"
}
]
},
"communication": [
{
"language": {
"coding": [
{
"system": "urn:oid:1.0.639.1",
"code": "en",
"display": "English"
}
]
},
"preferred": true
}
]
}
},
{
"fullUrl": "https://fhir.netsmartcloud.com/v4/PractitionerRole/aadf1331-510a-4cd0-8478-6031b56e24a8",
"resource": {
"resourceType": "PractitionerRole",
"id": "aadf1331-510a-4cd0-8478-6031b56e24a8",
"practitioner": {
"reference": "urn:uuid:5877a408-b99a-4844-932b-d1b6cc4b2923"
},
"organization": {
"reference": "urn:uuid:e9e36e9c-3c58-407d-b599-726c1bfd5132"
}
}
},
{
"fullUrl": "https://fhir.netsmartcloud.com/v4/PractitionerRole/2583aae2-d7d0-4b69-8fee-2ed7a12e69eb",
"resource": {
"resourceType": "PractitionerRole",
"id": "2583aae2-d7d0-4b69-8fee-2ed7a12e69eb",
"practitioner": {
"reference": "urn:uuid:2150a55b-87f6-4e9d-8d55-60cb8d8e3d55"
},
"organization": {
"reference": "Organization/90123"
}
}
},
{
"fullUrl": "https://fhir.netsmartcloud.com/v4/Practitioner/5877a408-b99a-4844-932b-d1b6cc4b2923",
"resource": {
"resourceType": "Practitioner",
"id": "5877a408-b99a-4844-932b-d1b6cc4b2923",
"name": [
{
"family": "Family",
"given": [
"Given"
]
}
],
"telecom": [
{
"system": "phone",
"value": "5551234567"
},
{
"system": "email",
"value": "my.username@org.com"
}
]
}
},
{
"fullUrl": "https://fhir.netsmartcloud.com/v4/Practitioner/2150a55b-87f6-4e9d-8d55-60cb8d8e3d55",
"resource": {
"resourceType": "Practitioner",
"id": "2150a55b-87f6-4e9d-8d55-60cb8d8e3d55",
"extension": [
// Supported
],
"identifier": [
// Supported
],
"name": [
{
"family": "Last",
"given": [
"First"
]
}
]
}
},
{
"fullUrl": "https://fhir.netsmartcloud.com/v4/Practitioner/acb89754-d395-4d0c-be7d-cd058ccb376b",
"resource": {
"resourceType": "Practitioner",
"id": "acb89754-d395-4d0c-be7d-cd058ccb376b",
"extension": [
// Supported
],
"name": [
{
"family": "Another",
"given": [
"Name"
]
}
]
}
},
{
"fullUrl": "https://fhir.netsmartcloud.com/v4/Organization/e9e36e9c-3c58-407d-b599-726c1bfd5132",
"resource": {
"resourceType": "Organization",
"id": "e9e36e9c-3c58-407d-b599-726c1bfd5132",
"extension": [
// Supported
],
"identifier": [
{
"system": "http://hl7.org/fhir/sid/us-npi",
"value": "2134567890"
},
],
"active": true,
"type": [
{
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/organization-type",
"code": "prov",
"display": "Healthcare Provider"
}
]
}
],
"name": "Hospital Name",
"telecom": [
{
"system": "phone",
"value": "9998887777"
}
],
"address": [
{
"line": [
"123 Main Street",
"Apt B"
],
"city": "Springfield",
"state": "MO",
"postalCode": "65803",
"country": "USA"
}
]
}
},
{
"fullUrl": "https://fhir.netsmartcloud.com/v4/Organization/43780bd3-2d72-4146-9b90-9b61c54261a3",
"resource": {
"resourceType": "Organization",
"id": "43780bd3-2d72-4146-9b90-9b61c54261a3",
"extension": [
// Supported
],
"identifier": [
// Supported
],
"active": true,
"type": [
{
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/organization-type",
"code": "pay",
"display": "Payer"
}
]
}
],
"name": "Some Payer",
"telecom": [
{
"system": "phone",
"value": "444558888"
}
],
"address": [
{
"line": [
"9900 Center Street",
"Ste 310"
],
"city": "Minneapolis",
"state": "MN",
"postalCode": "55111",
"country": "USA"
}
]
}
},
{
"fullUrl": "https://fhir.netsmartcloud.com/v4/QuestionnaireResponse/596bb1c8-10c1-4f66-a1c7-3e330d3eab0e",
"resource": {
"resourceType": "QuestionnaireResponse",
"id": "596bb1c8-10c1-4f66-a1c7-3e330d3eab0e",
"identifier": {
"value": "MQ_3641833"
},
"basedOn": [
{
"reference": "urn:uuid:eff3c2b7-a6f4-40fd-8513-d599f45875ff"
}
],
"questionnaire": "Questionnaire/ABC",
"status": "in-progress",
"subject": "urn:uuid:9d72e641-d314-4fb7-afa5-5b48696b2d21",
"item": [
{
"linkId": "P-01",
"text": "Text of the first prompt?",
"answer": [
{
"valueString": "Free-text answer"
}
]
},
{
"linkId": "P-02",
"text": "Text the second prompt?",
"answer": [
{
"valueBoolean": false
}
]
}
]
}
},
{
"fullUrl": "https://fhir.netsmartcloud.com/v4/Location/6d11f9fb-66d6-4856-b917-78fdc2d46926",
"resource": {
"resourceType": "Location",
"id": "6d11f9fb-66d6-4856-b917-78fdc2d46926",
"extension": [
// Supported
],
"identifier": [
// Supported
],
"status": "active",
"name": "Facility Name",
"description": "Facility description.",
"mode": "instance",
"telecom": [
{
"use": "work",
"system": "phone",
"value": "2328"
},
{
"system": "email",
"value": "facility@domain.com"
}
],
"address": {
"use": "work",
"line": [
"Street 1",
"Street 2"
],
"city": "City",
"postalCode": "12345+6789",
"country": "US"
},
"position": {
"longitude": -83.6945691,
"latitude": 42.25475478,
"altitude": 0
},
"managingOrganization": {
"reference": "Organization/90123"
},
"hoursOfOperation": [
{
"daysOfWeek": [
"mon",
"tue",
"wed",
"thu",
"fri"
],
"allDay": false,
"openingTime": "07:00:00",
"closingTime": "19:00:00"
},
{
"daysOfWeek": [
"sat"
],
"allDay": false,
"openingTime": "09:00:00",
"closingTime": "16:00:00"
}
]
}
},
{
"fullUrl": "https://fhir.netsmartcloud.com/v4/Coverage/07ad4455-a442-4c6f-b080-7053e8b38b07",
"resource": {
"resourceType": "Coverage",
"id": "07ad4455-a442-4c6f-b080-7053e8b38b07",
"status": "active",
"beneficiary": {
"reference": "urn:uuid:9d72e641-d314-4fb7-afa5-5b48696b2d21"
},
"payor": [
{
"reference": "urn:uuid:43780bd3-2d72-4146-9b90-9b61c54261a3"
}
]
}
},
{
"fullUrl": "https://fhir.netsmartcloud.com/v4/Condition/3d35ec04-bcdc-490e-9721-b5a4f68310d3",
"resource": {
"resourceType": "Condition",
"id": "3d35ec04-bcdc-490e-9721-b5a4f68310d3",
"clinicalStatus": {
"coding": [
"system": "http://terminology.hl7.org/CodeSystem/condition-clinical",
"code": "active"
]
},
"verificationStatus": {
"coding": [
"system": "http://terminology.hl7.org/CodeSystem/condition-ver-status",
"code": "confirmed"
]
},
"category": {
"coding": [
"system": "http://terminology.hl7.org/CodeSystem/condition-category",
"code": "problem-list-item"
]
},
"severity": {
"coding": [
{
"system": "http://snomed.info/sct",
"code": "24484000",
"display": "Severe"
}
]
},
"code": {
"coding": [
{
"system": "http://snomed.info/sct",
"code": "36225005",
"display": "Acute renal insufficiency specified as due to procedure"
}
]
},
"bodySite": [
{
"coding": [
{
"system": "http://snomed.info/sct",
"code": "181414000",
"display": "Kidney"
}
]
}
],
"subject": {
"reference": "urn:uuid:9d72e641-d314-4fb7-afa5-5b48696b2d21",
"type": "Patient"
},
// tbd
}
},
{
"fullUrl": "https://fhir.netsmartcloud.com/v4/Observation/70617260-8376-4fe3-a246-da6d012d58b4",
"resource": {
"resourceType": "Observation",
"id": "70617260-8376-4fe3-a246-da6d012d58b4",
"subject": {
"reference": "urn:uuid:9d72e641-d314-4fb7-afa5-5b48696b2d21",
"type": "Patient"
},
// tbd
}
}
]
}

Sample Response Payload

{
"resourceType": "Bundle",
"id": "1a124350-e357-4b29-b780-1a4c9064c024",
"type": "message",
"entry": [
{
"fullUrl": "MessageHeader/3641833",
"resource": {
"resourceType": "MessageHeader",
"eventCoding": {
"system": "http://ntst.com/fhir/message-events",
"code": "submit-service-request"
},
"response": {
"identifier": "607e4728-5d96-43a8-8be0-418313050140",
"code": "ok"
},
"focus": [
{
"reference": "ServiceRequest/123456"
},
{
"reference": "QuestionnaireResponse/ABC-456789"
}
]
}
},
{
"fullUrl": "ServiceRequest/123456",
"resource": {
"resourceType": "ServiceRequest",
"id": "123456",
"extension": [
// We can support multiple extension data types via the message. However, these will only be read if configured in Referral Manager.
],
"identifier": [
// We can support the exchange of identifiers as well. Configure the Systems in Referral Manager to add to the Referral.
],
"status": "active",
"intent": "proposal",
"subject": {
"reference": "Patient/987654"
},
"requester": {
"reference": "PractitionerRole/45678"
},
"performer": [
{
"reference": "PractitionerRole/56789"
},
{
"reference": "Practitioner/888888888"
}
],
"locationReference": [
{
"reference": "Location/90456"
}
]
}
},
{
"fullUrl": "PractitionerRole/45678",
"resource": {
"resourceType": "PractitionerRole",
"id": "1176",
"practitioner": {
"reference": "Practitioner/444444444"
},
"organization": {
"reference": "Organization/90123"
}
}
},
{
"fullUrl": "PractitionerRole/56789",
"resource": {
"resourceType": "PractitionerRole",
"id": "56789",
"practitioner": {
"reference": "Practitioner/666666666",
"type": "Practitioner"
},
"organization": {
"reference": "Organization/90123",
"type": "Organization"
}
}
},
{
"fullUrl": "Practitioner/444444444",
"resource": {
"resourceType": "Practitioner",
"id": "444444444",
"name": [
{
"family": "Family",
"given": [
"Given"
]
}
],
"telecom": [
{
"system": "phone",
"value": "5551234567"
},
{
"system": "email",
"value": "my.username@org.com"
}
]
}
},
{
"fullUrl": "Practitioner/666666666",
"resource": {
"resourceType": "Practitioner",
"id": "900049",
"extension": [
// Supported
],
"identifier": [
// Supported
],
"name": [
{
"family": "Last",
"given": [
"First"
]
}
]
}
},
{
"fullUrl": "Practitioner/888888888",
"resource": {
"resourceType": "Practitioner",
"id": "8236756",
"extension": [
// Supported
],
"name": [
{
"family": "Another",
"given": [
"Name"
]
}
]
}
},
{
"fullUrl": "Organization/90123",
"resource": {
"resourceType": "Organization",
"id": "90123",
"extension": [
// Supported
],
"identifier": [
{
"system": "http://hl7.org/fhir/sid/us-npi",
"value": "2134567890"
},
],
"active": true,
"type": [
{
"coding": [
{
"system": "http://terminology.hl7.org/CodeSystem/organization-type",
"code": "prov",
"display": "Healthcare Provider"
}
]
}
],
"name": "Hospital Name",
"telecom": [
{
"system": "phone",
"value": "9998887777"
}
],
"address": [
{
"line": [
"123 Main Street",
"Apt B"
],
"city": "Springfield",
"state": "MO",
"postalCode": "65803",
"country": "USA"
}
]
},
{
"fullUrl": "Patient/987654",
"resource": {
"resourceType": "Patient",
"extension": [
{
"url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-race",
"extension": [
{
"url": "ombCategory",
"valueCoding": {
"system": "urn:oid:2.16.840.1.113883.6.238",
"code": "2106-3",
"display": "White"
}
},
{
"url": "detailed",
"valueCoding": {
"system": "urn:oid:2.16.840.1.113883.6.238",
"code": "2106-3",
"display": "White"
}
},
{
"url": "text",
"valueString": "White"
}
]
},
{
"url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-ethnicity",
"extension": [
{
"url": "ombCategory",
"valueCoding": {
"system": "urn:oid:2.16.840.1.113883.6.238",
"code": "2186-5",
"display": "Not Hispanic or Latino"
}
},
{
"url": "detailed",
"valueCoding": {
"system": "urn:oid:2.16.840.1.113883.6.238",
"code": "2186-5",
"display": "Not Hispanic or Latino"
}
},
{
"url": "text",
"valueString": "Not Hispanic or Latino"
}
]
},
{
"url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-birthsex",
"valueCode": "M"
},
{
"url": "http://hl7.org/fhir/StructureDefinition/patient-citizenship",
"extension": [
{
"url": "code",
"valueCodeableConcept": {
"coding": [
{
"system": "urn:iso:std:iso:3166",
"code": "US"
}
]
}
},
{
"url": "code",
"valuePeriod": {
"start": "2000-03-12T05:00:00+00:00",
"end": "2017-08-31T05:00:00+00:00"
}
}
]
}
],
"identifier": [
// Supported
],
"name": [
{
"text": "First MI Last",
"family": "Last",
"given": [
"First",
"MI"
],
"suffix": "JR"
}
],
"telecom": [
{
"use": "home",
"system": "phone",
"value": "5556667788",
"rank": 1
},
{
"use": "work",
"system": "phone",
"value": "5556321478"
},
{
"use": "home",
"system": "email",
"value": "myemail20004@gmail.com"
}
],
"gender": "male",
"birthDate": "1997-01-16",
"deceasedBoolean": false,
"address": [
{
"use": "home",
"line": [
"4950 College Blvd."
],
"city": "Overland Park",
"state": "KS",
"postalCode": "66211",
"country": "US",
"period": {
"start": "2015-06-22T05:00:00+00:00"
}
}
],
"maritalStatus": {
"coding": [
{
"system": "urn:oid:2.16.840.1.113883.4.642.3.29",
"code": "C",
"display": "Common Law"
}
]
},
"communication": [
{
"language": {
"coding": [
{
"system": "urn:oid:1.0.639.1",
"code": "en",
"display": "English"
}
]
},
"preferred": true
}
]
}
}
},
{
"fullUrl": "QuestionnaireResponse/ABC-456789",
"resource": {
"resourceType": "QuestionnaireResponse",
"identifier": {
"value": "MQ_3641833"
},
"basedOn": [
{
"reference": "ServiceRequest/123456"
}
],
"questionnaire": "Questionnaire/ABC",
"status": "in-progress",
"item": [
{
"linkId": "P-01",
"text": "Text of the first prompt?",
"answer": [
{
"valueString": "Free-text answer"
}
]
},
{
"linkId": "P-02",
"text": "Text the second prompt?",
"answer": [
{
"valueBoolean": false
}
]
}
]
}
},
{
"fullUrl": "Location/90456",
"resource": {
"resourceType": "Location",
"id": "90456",
"extension": [
// Supported
],
"identifier": [
// Supported
],
"status": "active",
"name": "Facility Name",
"description": "Facility description.",
"mode": "instance",
"telecom": [
{
"use": "work",
"system": "phone",
"value": "2328"
},
{
"system": "email",
"value": "facility@domain.com"
}
],
"address": {
"use": "work",
"line": [
"Street 1",
"Street 2"
],
"city": "City",
"postalCode": "12345+6789",
"country": "US"
},
"position": {
"longitude": -83.6945691,
"latitude": 42.25475478,
"altitude": 0
},
"managingOrganization": {
"reference": "Organization/90123"
},
"hoursOfOperation": [
{
"daysOfWeek": [
"mon",
"tue",
"wed",
"thu",
"fri"
],
"allDay": false,
"openingTime": "07:00:00",
"closingTime": "19:00:00"
},
{
"daysOfWeek": [
"sat"
],
"allDay": false,
"openingTime": "09:00:00",
"closingTime": "16:00:00"
}
]
}
},
]
}

Integration Patterns

Submission Workflow

  1. Prepare Message Bundle

    • Create MessageHeader with submit event
    • Include ServiceRequest with all required data
    • Add supporting resources (Patient, Practitioner, etc.)
  2. Validate Bundle Structure

    • Ensure all references are valid
    • Check required resource relationships
    • Validate against supported profiles
  3. Submit Message

    • POST to /$process-message endpoint
    • Handle response and extract IDs
    • Process any validation errors

Best Practices

  • Include complete patient demographics
  • Provide comprehensive clinical information
  • Use standard coding systems where possible
  • Maintain consistent identifier usage

Relationships to Other Resources

Error Handling

For comprehensive error handling information, see Common Errors.

Support

For technical support with Submit Service Request messages: