Messages

Retrieve System Messages for a Patient

A patient can view messages from the MD Live system. The view a paginated list of system messages, make a request to:

HTTP Request

GET {server_url}/api/v1/patients/{patient_id}/messages/system?page=1&per=5

This request must include a valid User JWT token, please see our documentation

Header Parameter

Parameter	Default
Content-type	application/json
Accept	application/json
Authorization	Bearer {jwttoken}

URL Parameter

Parameter	Required	Description
patient_id	true	MD Live ID for patient
page	false	Page #
per	false	# of messages per page

Example Request

Shell

curl -X GET {server_url}/api/v1/patients/{patient_id}/messages/system?page=1&per=5
  -H "Content-type: application/json"
  -H "Authorization: Bearer 34a2sample-api-token"
  -H "Accept: application/json"

Ruby

RestClient::Request.new(
  :method => :get,
  :url => "{server_url}/api/v1/patients/{patient_id}/messages/system?page1&per=5",
  :headers => {
    "Content-type" => "application/json",
    "Authorization" => "Bearer 34a2sample-api-token",
    "Accept" => "application/json"
  },
).execute

Example Response

{
  "messages": [
    {
      "id": 99,
      "date_time": "2018-01-10T00:42:57+00:00",
      "from": "System Controller",
      "from_id": 2,
      "to": "Test Marino",
      "to_id": 3,
      "subject": "Appointment Scheduled",
      "message": "You have scheduled an appointment with Dr. Travis C Stork at 01/09/2018 at 07:43 PM (EST)",
      "unread_status": true,
      "replied_to_message_id": null
    },
    {
      "id": 97,
      "date_time": "2018-01-09T16:36:20+00:00",
      "from": "System Controller",
      "from_id": 2,
      "to": "Test Marino",
      "to_id": 3,
      "subject": "Appointment Scheduled",
      "message": "You have scheduled an appointment with Dr. Travis C Stork at 01/09/2018 at 11:37 AM (EST)",
      "unread_status": true,
      "replied_to_message_id": null
    },
    {
      "id": 94,
      "date_time": "2017-12-29T21:21:03+00:00",
      "from": "System Controller",
      "from_id": 2,
      "to": "Test Marino",
      "to_id": 3,
      "subject": "Appointment Scheduled",
      "message": "You have scheduled an appointment with Dr. Travis C Stork at 12/29/2017 at 09:30 PM (EST)",
      "unread_status": false,
      "replied_to_message_id": null
    },
    {
      "id": 92,
      "date_time": "2017-12-29T21:16:00+00:00",
      "from": "System Controller",
      "from_id": 2,
      "to": "Test Marino",
      "to_id": 3,
      "subject": "Appointment Scheduled",
      "message": "You have scheduled an appointment with Dr. Travis C Stork at 12/29/2017 at 07:30 PM (EST)",
      "unread_status": true,
      "replied_to_message_id": null
    },
    {
      "id": 64,
      "date_time": "2017-12-27T16:52:15+00:00",
      "from": "System Controller",
      "from_id": 2,
      "to": "Test Marino",
      "to_id": 3,
      "subject": "Appointment Scheduled",
      "message": "You have scheduled an appointment with Dr. Travis C Stork at 12/29/2017 at 11:15 AM (EST)",
      "unread_status": true,
      "replied_to_message_id": null
    }
  ],
  "unread": 25
}

Retrieve All Contacts

A patient can contact providers that they have previously seen or are scheduled to see. For a list of these providers, make a request to:

HTTP Request

GET {server_url}/api/v1/patients/{patient_id}/messages/contacts

This request must include a valid User JWT token, please see our documentation

Header Parameter

Parameter	Default
Content-type	application/json
Accept	application/json
Authorization	Bearer {jwttoken}

URL Parameter

Parameter	Required	Description
patient_id	true	MD Live ID for patient

Example Request

Shell

curl -X GET {server_url}/api/v1/patients/{patient_id}/messages/contacts
  -H "Content-type: application/json"
  -H "Authorization: Bearer 34a2sample-api-token"
  -H "Accept: application/json"

Ruby

RestClient::Request.new(
  :method => :get,
  :url => "{server_url}/api/v1/patients/{patient_id}/messages/contacts",
  :headers => {
    "Content-type" => "application/json",
    "Authorization" => "Bearer 34a2sample-api-token",
    "Accept" => "application/json"
  },
).execute

Example Response

{
  "contacts": [
    {
      "id": 35,
      "prefix": "",
      "fullname": "demoprovider1 demoprovider1",
      "gender": "Male",
      "photo_url": "/users/35/photo",
      "specialty": "General Practice"
    },
    {
      "id": 37,
      "prefix": null,
      "fullname": "demoprovider3 demoprovider3",
      "gender": "Male",
      "photo_url": "/users/37/photo",
      "specialty": "General Practice"
    },
    {
      "id": 38,
      "prefix": null,
      "fullname": "demoprovider4 demoprovider4",
      "gender": "Male",
      "photo_url": "/users/38/photo",
      "specialty": "General Practice"
    }
  ]
}

Retrieve All Conversations for a Patient

To fetch a list of all the patient’s conversations with various providers, make a request to:

HTTP Request

GET {server_url}/api/v2/patients/{patient_id}/messages/conversations

This request must include a valid User JWT token, please see our documentation

Header Parameter

Parameter	Default
Content-type	application/json
Accept	application/json
Authorization	Bearer {jwttoken}

URL Parameter

Parameter	Required	Description
patient_id	true	MD Live ID for patient

Example Request

Shell

curl -X GET {server_url}/api/v2/patients/{patient_id}/messages/conversations
  -H "Content-type: application/json"
  -H "Authorization: Bearer 34a2sample-api-token"
  -H "Accept: application/json"

Ruby

RestClient::Request.new(
  :method => :get,
  :url => "{server_url}/api/v2/patients/{patient_id}/messages/conversations",
  :headers => {
    "Content-type" => "application/json",
    "Authorization" => "Bearer 34a2sample-api-token",
    "Accept" => "application/json"
  },
).execute

Example Response

{ conversations:
  [
    {
      "provider": {
        "id": 37,
        "prefix": null,
        "fullname": "demoprovider3 demoprovider3",
        "gender": "Male",
        "photo_url": "/users/37/photo",
        "specialty": "General Practice"
      },
      "unread_messages": null,
      "recent_message_body": "Hello, I am waiting for you to start the appointment",
      "last_message_at": "2018-01-22T10:38:07.000-05:00",
      "last_message_by": "patient"
    },
    {
      "provider": {
        "id": 4,
        "prefix": "DR",
        "fullname": "Travis C Stork",
        "gender": "Male",
        "photo_url": "/users/4/photo",
        "specialty": "General Practice"
      },
      "unread_messages": 2,
      "recent_message_body": "You can take 1 600mg every 4 hours as needed for pain.",
      "last_message_at": "2018-01-23T08:50:39.000-05:00",
      "last_message_by": "provider"
    }
  ]
}

Retrieve A Conversation between a Patient and Provider

To retrieve a paginated conversation thread between a patient and a particular provider, make a request to:

HTTP Request

GET {server_url}/api/v1/patients/{patient_id}/providers/{provider_id}/conversation

This request must include a valid User JWT token, please see our documentation

Header Parameter

Parameter	Default
Content-type	application/json
Accept	application/json
Authorization	Bearer {jwttoken}

URL Parameter

Parameter	Required	Description
patient_id	true	MD Live ID for patient
provider_id	true	MD Live ID for provider
page	false	Page #
per	false	# of messages per page

Example Request

Shell

curl -X GET {server_url}/api/v1/patients/{patient_id}/providers/{provider_id}/conversation?page=1&per=5
  -H "Content-type: application/json"
  -H "Authorization: Bearer 34a2sample-api-token"
  -H "Accept: application/json"

Ruby

RestClient::Request.new(
  :method => :get,
  :url => "{server_url}/api/v1/patients/{patient_id}/providers/{provider_id}/conversation?page=1&per=5",
  :headers => {
    "Content-type" => "application/json",
    "Authorization" => "Bearer 34a2sample-api-token",
    "Accept" => "application/json"
  },
).execute

Example Response

{
  "messages": [
    {
      "id": 106,
        "date_time": "2018-01-23T13:50:39+00:00",
        "from": "DR Travis C Stork",
        "from_id": 4,
        "to": "Test Marino",
        "to_id": 3,
        "subject": "Re: Prescription",
        "message": "You can take 1 600mg every 4 hours as needed for pain.",
        "unread_status": true,
        "reply_allowed": true
    },
    {
      "id": 105,
      "date_time": "2018-01-23T02:33:13+00:00",
      "from": "Test Marino",
      "from_id": 3,
      "to": "DR Travis C Stork",
      "to_id": 4,
      "subject": "Prescription",
      "message": "Hello, I received a prescription for extra strength Ibuprofen. How often can I take the medicine?",
      "unread_status": false,
      "reply_allowed": false
    }
    {
      "id": 104,
      "date_time": "2018-01-23T02:32:39+00:00",
      "from": "DR Travis C Stork",
      "from_id": 4,
      "to": "Test Marino",
      "to_id": 3,
      "subject": "Start Appointment",
      "message": "Hello, I am ready for your appointment",
      "unread_status": true,
      "reply_allowed": true
    }
  ]
}

Create a Message from a Patient

Patients can only send messages to an authorized provider. A provider is authorized if the patient has a previous or upcoming appointment with that provider. To create a new message, make a request to:

Note

There are restrictions for when a patient can send a message to a provider. Please use the flag reply_allowed to know when sending a message to a Provider is acceptable (See: Messages - Retrieve A Conversation between a Patient and Provider).

HTTP Request

POST {server}/api/v1/patients/{patient_id}/messages

This request must include a valid User JWT token, please see our documentation

Header Parameter

Parameter	Default
Content-type	application/json
Accept	application/json
Authorization	Bearer {jwttoken}

URL Parameter

Parameter	Required	Description
patient_id	true	MD Live ID for patient

Request Body Parameters

Parameter	Type	Required	Description
message	object	true	Object containing the content of a message
↳  message_type	string	true	Type of message. For messages to providers, use the type: follow_up
↳  to_id	integer	true	MD Live ID of the provider recipient
↳  subject	string	true	Text subject of message
↳  message	string	true	Text body of message
↳  replied_to_message_id	integer	false	If a message is created in response to another message from the provider, the previous message’s ID must be supplied

Example Request

Shell

curl -X POST {server_url}/api/v1/patients/{patient_id}/messages
  -H "Content-type: application/json"
  -H "Authorization: Bearer 34a2sample-api-token"
  -H "Accept: application/json"
  -d '{
    "message": {
      "message_type": "follow_up",
      "to_id": 4,
      "subject": "Prescription",
      "message": "Hello, I received a prescription for extra strength Ibuprofen. How often can I take the medicine?",
      "replied_to_message_id": 104
    }
  }'

Ruby

RestClient::Request.new(
  :method => :post,
  :url => "{server_url}/api/v1/patients/{patient_id}/messages",
  :headers => {
    "Content-type" => "application/json",
    "Authorization" => "Bearer 34a2sample-api-token",
    "Accept" => "application/json"
  },
  :payload => {
    message: {
      message_type: "follow_up",
      to_id: 4,
      subject: "Prescription",
      message: "Hello, I received a prescription for extra strength Ibuprofen. How often can I take the medicine?",
      replied_to_message_id: 104
    }
  }
).execute

Example Response

{
  "message": {
    "id": 105,
    "date_time": "2018-01-23T02:33:13+00:00",
    "from": "Test Marino",
    "from_id": 3,
    "to": "Travis C Stork",
    "to_id": 4,
    "subject": "Prescription",
    "message": "Hello, I received a prescription for extra strength Ibuprofen. How often can I take the medicine?",
    "unread_status": true,
    "replied_to_message_id": 104
  }
}

Mark A Message as Read

A patient can only mark messages sent to them as read. To mark a message as read, make a request to:

HTTP Request

PUT {server}/api/v1/patients/{patient_id}/messages/{message_id}/mark_read

This request must include a valid User JWT token, please see our documentation

Header Parameter

Parameter	Default
Content-type	application/json
Accept	application/json
Authorization	Bearer {jwttoken}

URL Parameter

Parameter	Required	Description
patient_id	true	MD Live ID for patient
message_id	true	MD Live ID for message

Example Request

Shell

curl -X PUT {server_url}/api/v1/patients/{patient_id}/messages/{message_id}/mark_read
  -H "Content-type: application/json"
  -H "Authorization: Bearer 34a2sample-api-token"
  -H "Accept: application/json"

Ruby

RestClient::Request.new(
  :method => :put,
  :url => "{server_url}/api/v1/patients/{patient_id}/messages/{messages_id}/mark_read",
  :headers => {
    "Content-type" => "application/json",
    "Authorization" => "Bearer 34a2sample-api-token",
    "Accept" => "application/json"
  }
).execute

Example Response

The above command will return a 204 status code with no content in the body.