Appointment Booking

Table of contents

1. Appointment Booking
2. Appointment Booking without a Patient User
3. Appointment Booking with Automated Payment
4. Prerequisites for Video Consultations (VC)
5. Enrolling for Earlier Appointment Notifications
6. Specifying a Referral/Source Identifier

Appointment Booking

This endpoint can be used to book an appointment on behalf of a user. It requires previous authentication via OAuth with the required scope ‘appointments:book’ and expects a POST request.

Please note: In case the request is sent with an access token that doesn’t have the required scope, it will fall back to a guest booking.

The optional ref parameter is described in Specifying a Referral/Source Identifier.

The optional validate_patient_data parameter will enforce the mandatory patient data configured in the institution settings area. The call will fail with a 400 error if the provided patient data don’t contain data for all of the mandatory fields.

Sample Request:

POST /api/booking/v3/book HTTP/1.1
Host: patient.samedi.de
Authorization: Bearer SlAV32hkKG
Content-Type: application/x-www-form-urlencoded

client_id=CLIENT_ID
&event_category_id=14
&event_type_id=9
&starts_at=2011-06-01T12:00+02:00
&ref=my-company-name

Sample Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
   "success": true
}

Possible Errors:

Appointment Booking without a Patient User

Please note: a samedi Comfort package is required to use this option.

This endpoint allows for appointment booking without a samedi patient user. This is only possible if the appointment type allows for that (i.e. has an attendant_user_required value of false - this can be configured accordingly by the practice administrator). Authentication in this case is performed via the API Key and the request should be sent via POST.

The patient data must be sent separately as there is no patient account from which they can be retrieved. These data should be sent as a hash under the parameter name attendant. These data are used in order to create a new patient in the institution. The exact set of required fields for each patient are specified by each institution and can be retrieved via the Institution Details endpoint.

For a list of possible attendant data fields, see Patient Data Fields

Structured comment fields can be applied in the same manner that they would be applied in the normal appointment booking. See next section for further informations.

The optional ref parameter is described in Specifying a Referral/Source Identifier.

Patient Notifications and GDPR Compliance (25th May 2018)

Since the introduction of GDPR in May 25th 2018, patients need to explicitly opt in for notifications regarding appointment confirmations, postponements or cancellations.

If you have taken the patient’s explicit consent (e.g. by a checkbox on your form which is not pre-selected and it is not required, to comply with GDPR) you can set the do_notification parameter to true in order to trigger notifications for this patient. This may include e-mail and/or SMS notifications for appointment confirmations, postponements, and cancellations. The details depend on the institution’s notifications configuration. This consent will apply for the current and all future appointments with this institution.

If you do not set the do_notification flag at all, or set it to something other than true, notifications will be permanently turned off for this patient. This can be changed later from the institution on the patient’s data panel.

Sample Request:

POST /api/booking/v3/book HTTP/1.1
Host: patient.samedi.de
Content-Type: application/x-www-form-urlencoded

client_id=CLIENT_ID
&event_category_id=14
&event_type_id=9
&starts_at=2011-06-01T12:00+02:00
&do_notification=true
&attendant[data][first_name]=Max
&attendant[data][last_name]=Mustermann
&attendant[data][email]=max@mustermann.de

Sample Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
   "success": true
}

Possible Errors:

Same as normal booking appointment (see previous section), plus:

Appointment Booking with Automated Payment

PayPal Order ID Generation

Appointment booking with automated payment is only possible for institutions that have the Automated Payment for Patient Bookings samedi package. If that is correctly set up, you can generate the PayPal Order ID.

This endpoint expects a POST request.

Sample Request:

POST /api/automated_payment/v1/orders HTTP/1.1
Host: patient.samedi.de
Authorization: Bearer SlAV32hkKG
Content-Type: application/x-www-form-urlencoded

event_type_id=9
&client_id=CLIENT_ID

Sample Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "ID",
  "status": "CREATED",
  "links": [{
    "table": {
      "href": "https://api.paypal.com/v2/checkout/orders/ID",
      "rel": "self",
      "method": "GET"
    },
    "modifiable": true
  }, {
    "table": {
      "href": "https://www.paypal.com/checkoutnow?token=ID",
      "rel": "approve",
      "method": "GET"
    },
    "modifiable": true
  }, {
    "table": {
      "href": "https://api.paypal.com/v2/checkout/orders/ID",
      "rel": "update",
      "method": "PATCH"
    },
    "modifiable": true
  }, {
    "table": {
      "href": "https://api.paypal.com/v2/checkout/orders/ID/authorize",
      "rel": "authorize",
      "method": "POST"
    },
    "modifiable": true
  }]
}

Now you could use the PayPal JavaScript SDK to create PayPal payment button on your page. Make sure that you pass the returned id from the response, which is the Order ID PayPal needs to ask the user to pay.

Once the user pays and PayPal approves the transaction (onApprove), you can Complete the Booking

Possible Errors:

Complete the Booking

Now that the user has paid, you need to book the actual appointment. The Appointment Booking section has all the details for this endpoint. But you can also use the Appointment Booking without a Patient User if the appointment booking should be completed without a samedi patient user.

However, we also need to send: - order_url - so that samedi can check that the appointment has been actually paid. - billing_information - which is the billing information of the user, including all of the following fields: first_name, last_name, street, city, country, zip and email.

Please use ISO 3166-1 alpha-2 country codes for the country field. Ex. use DE for Germany.

The order_url should have the following format: https://api.paypal.com/v2/checkout/orders/PAYPAL_ORDER_ID where PAYPAL_ORDER_ID is the PayPal Order ID from the previous section.

Sample Request for Booking with a samedi Patient User:

It requires a previous authentication via OAuth.

POST /api/booking/v3/book HTTP/1.1
Host: patient.samedi.de
Authorization: Bearer SlAV32hkKG
Content-Type: application/x-www-form-urlencoded

client_id=CLIENT_ID
&order_url=https://api.paypal.com/v2/checkout/orders/PAYPAL_ORDER_ID
&billing_information[first_name]=Max
&billing_information[last_name]=Mustermann
&billing_information[street]=Teststr. 1
&billing_information[city]=Berlin
&billing_information[country]=DE
&billing_information[zip]=10115
&billing_information[email]=mustermann@mail.com
&event_category_id=14
&event_type_id=9
&starts_at=2011-06-01T12:00+02:00

Sample Request for Booking without a samedi Patient User:

Here we also need to send the patient data (attendant fields).

POST /api/booking/v3/book HTTP/1.1
Host: patient.samedi.de
Authorization: Bearer SlAV32hkKG
Content-Type: application/x-www-form-urlencoded

client_id=CLIENT_ID
&order_url=https://api.paypal.com/v2/checkout/orders/PAYPAL_ORDER_ID
&billing_information[first_name]=Max
&billing_information[last_name]=Mustermann
&billing_information[street]=Teststr. 1
&billing_information[city]=Berlin
&billing_information[country]=DE
&billing_information[zip]=10115
&billing_information[email]=mustermann@mail.com
&do_notification=true
&attendant[data][first_name]=Max
&attendant[data][last_name]=Mustermann
&attendant[data][email]=max@mustermann.de
&event_category_id=14
&event_type_id=9
&starts_at=2011-06-01T12:00+02:00

Sample Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
   "success": true
}

Possible Errors:

Same as the normal appointment booking (see section), plus:

Prerequisites for Video Consultation (VC)

If an appointment type is meant to be a video consultation is stated by the parameter is_video_consultation as part of the result of the Appointment Types request.

To be able to book a video consultation for patients without a samedi patient account, the patients email is mandatory, even if the Institution Details list the patient’s email address as optional. Furthermore the patient must give their consent to receive notifications, which you can specify with the parameter do_notification while booking the appointment

Enrolling for Earlier Appointment Notifications

Patients can subscribe to the earlier appointment list so that they receive a notification if an earlier appointment slot becomes available. Through this notification the patient is able to change their appointment to an earlier date and time or unsubscribe from future notifications regarding earlier appointments.

Not all appointment types support this feature. Those appointment types that do will have the parameter asap_list_enabled with a value true as part of the result of the Appointment Types request.

To be able to opt-in to such a list, the patient’s email is mandatory, no matter if the Institution Details may list the patient’s email address as optional. The email address must be provided as part of the booking with the parameter asap_list_opt_in. When this parameter is given with a valid email address the patient is enrolled to the earlier appointment list for this appointment.

Example Request

POST /api/booking/v3/book HTTP/1.1
Host: patient.samedi.de
Content-Type: application/x-www-form-urlencoded

client_id=CLIENT_ID
&event_category_id=14
&event_type_id=9
&starts_at=2011-06-01T12:00+02:00
&do_notification=false
&asap_list_opt_in[email]=mustermann@mail.com
&attendant[data][first_name]=Max
&attendant[data][last_name]=Mustermann

Specifying a Referral/Source Identifier

The optional parameter ref can be used to identify a specific channel or source that led to the appointment booking. Valid ref values include alphanumeric characters, dashes, and underscores, e.g. my_company_channel-1.