Appointment Booking

Table of contents

1. Appointment Booking
2. Appointment Booking without a Patient User
3. Patient Notifications and GDPR Compliance
4. Appointment Booking with Automated Payment
5. Prerequisites for Video Consultations (VC)
6. Enrolling for Earlier Appointment Notifications
7. 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.

You can optionally update the patient’s notification preferences during booking. Use allow_email_notifications and allow_sms_notifications together for granular control, or do_notification to set both to the same value. If omitted, the existing preferences from the patient’s profile are kept. For details, see Patient Notifications and GDPR Compliance.

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.

For notification consent parameters, see Patient Notifications and GDPR Compliance.

Sample Request (separate consent):

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
&allow_email_notifications=true
&allow_sms_notifications=false
&attendant[data][first_name]=Max
&attendant[data][last_name]=Mustermann
&attendant[data][email]=max@mustermann.de

Sample Request (legacy single consent):

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:

Patient Notifications and GDPR Compliance

Since the introduction of GDPR in May 25th 2018, patients need to explicitly opt in for notifications regarding appointment confirmations, postponements or cancellations. This applies to all booking flows (with or without a patient user).

There are two ways to specify notification consent:

Separate consent (recommended)

Use allow_email_notifications and allow_sms_notifications to control email and SMS consent independently. Both parameters must be provided together. If only one is sent, the API will return an invalid_form_data error.

This is the recommended approach as it gives patients granular control over their notification preferences.

Legacy single consent

Use do_notification to set both email and SMS consent to the same value. Setting do_notification=true enables both email and SMS notifications; setting it to false disables both.

If both allow_email_notifications/allow_sms_notifications and do_notification are provided, the individual parameters take precedence over do_notification.

When no consent parameters are provided

If none of the above parameters are sent, notification consent is derived from the existing patient profile.

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.

For notification consent parameters, see Patient Notifications and GDPR Compliance.

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 email notifications. The booking will fail with an invalid_form_data error if email consent is not given. You can specify email consent with allow_email_notifications=true and allow_sms_notifications (both required together, recommended) or do_notification=true 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.