Appointment Requests

Create

Request an appointment with a Provider who does not have any availabilities during a specific date/time.

Note

Please note that by requesting an appointment, MD Live will attempt to contact the requested provider on the patient’s behalf to schedule an appointment. This request does not guarantee an appointment, and the time of the appointment is subject to the provider’s availability.

HTTP Request

To request an appointment with a provider, make a request to:

POST {server_url}/api/v2/patients/{patient_id}/appointment_requests

Headers

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

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

URL Parameters

The following parameters need to be included in the URL of the request:

Attribute	Required	Description
patient_id	true	MD Live ID for patient

Request Body Parameters

Attribute	Required	Description
appointment_request	true	Parent attribute for appointment_request
↳ provider_id	true	ID of the requested provider. Needed only when the patient would like to schedule a visit with a specific provider.
↳ chief_complaint	true	Reason for the appointment
↳ chief_complaint_comments	false	Any additional description of the reason the patient is making the appointment
↳ contact_number	true	Preferred phone number to contact the patient
↳ appointment_date	true	Requested date for appointment
↳ appointment_method	true	Requested type of appointment for the patient, should be ‘video’ or ‘phone’
↳ preferred_time	true	Preferred time of appointment. Should be one of: First Available Morning Afternoon Evening
↳ state_abbrev	false	Requested U.S. state for the appointment request
↳ provider_type_id	true	ID of provider type being requested

Example Request

Shell

curl -X POST {server_url}/api/v2/patients/{patient_id}/appointment_requests \
  -H 'Authorization: Bearer {jwt_token}' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'
  -d '{
        "appointment_request": {
          "provider_id": "1",
          "chief_complaint": "Depressed",
          "chief_complaint_comments": "Have been feeling sad the past couple of weeks",
          "contact_number": "888-632-2738",
          "appointment_date": "2025-04-01",
          "appointment_method": "phone",
          "preferred_time": "morning",
          "state_abbrev": "FL",
          "provider_type_id": "5"
        }
      }'

Ruby

RestClient::Request.new(
  :method => :get,
  :url => '{server_url}/api/v2/patients//{patient_id}/appointment_requests',
  :headers => {
    'Authorization' => 'Bearer {jwt_token}',
    'Content-type' => 'application/json',
    'Accept' => 'application/json'
  }
  :payload => {
                 "appointment_request"=> {
                   "provider_id"=> "1",
                   "chief_complaint"=> "Depressed",
                   "chief_complaint_comments"=> "Have been feeling sad the past couple of weeks",
                   "contact_number"=> "888-632-2738",
                   "appointment_date"=> "2025-04-01",
                   "appointment_method"=> "phone",
                   "preferred_time"=> "morning",
                   "state_abbrev"=> "FL",
                   "provider_type_id"=> "5"
                 }
               }
).execute

Example Response

The above command returns 200 OK with the following response:

{
    "appointment_request": {
        "id": 13,
        "patient_id": 3,
        "provider_id": 1,
        "chief_complaint": "Depressed",
        "contact_number": "888-632-2738",
        "appointment_date": "18-12-20",
        "appointment_method": "phone",
        "preferred_time": "morning",
        "state_abbrev": "FL",
        "provider_type_id": "5"
    }
}

Cancel

Cancel a pending appointment request with a Provider.

HTTP Request

To cancel a pending appointment request with a provider, make a request to:

POST {server_url}/api/v2/patients/{patient_id}/appointment_requests/{appointment_request_id}/cancel

Headers

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

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

URL Parameters

The following parameters need to be included in the URL of the request:

Attribute	Required	Description
patient_id	true	MD Live ID for patient
appointment_request_id	true	Appointment Request ID that is being canceled

Example Request

Shell

curl -X POST {server_url}/api/v2/patients/{patient_id}/appointment_requests/{appointment_request_id}/cancel \
  -H 'Authorization: Bearer {jwt_token}' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

Ruby

RestClient::Request.new(
  :method => :get,
  :url => '{server_url}/api/v2/patients/{patient_id}/appointment_requests/{appointment_request_id}/cancel',
  :headers => {
    'Authorization' => 'Bearer {jwt_token}',
    'Content-type' => 'application/json',
    'Accept' => 'application/json'
  }
).execute

Example Response

The above command returns 200 OK with the following JSON structured response:

{
    "message": "Your appointment request has been cancelled"
}

Remind

Remind a Provider with regards to a pending appointment request.

HTTP Request

To remind a provider about a pending appointment request, make a request to:

POST {server_url}/api/v2/patients/{patient_id}/appointment_requests/{appointment_request_id}/remind

Headers

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

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

URL Parameters

The following parameters need to be included in the URL of the request:

Attribute	Required	Description
patient_id	true	MD Live ID for patient
appointment_request_id	true	Appointment Request ID that is being reminded

Example Request

Shell

curl -X POST {server_url}/api/v2/patients/{patient_id}/appointment_requests/{appointment_request_id}/remind \
  -H 'Authorization: Bearer {jwt_token}' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

Ruby

RestClient::Request.new(
  :method => :get,
  :url => '{server_url}/api/v2/patients/{patient_id}/appointment_requests/{appointment_request_id}/remind',
  :headers => {
    'Authorization' => 'Bearer {jwt_token}',
    'Content-type' => 'application/json',
    'Accept' => 'application/json'
  }
).execute

Example Response

The above command returns 200 OK with the following JSON structured response:

{
    "message": "The Provider was reminded about your appointment request"
}