MyPatientPortal API

Disclaimer: this is a draft . It is not the final Portal API documentation and can still change

About this guide

This documentation is meant to be used as a quick-start guide only, to help you quickly create your first appointment using the API.

To understand the full capabilities of the APIs and get more conceived and production-ready examples, please see our Swagger documentation endpoint by endpoint.

The examples below include a Swagger documentation link to follow for more in-depth documentation about each endpoint involved.

Authorization

To access the API, you need samedi to generate an authorization token for you.

With that token, you’ll need to add the following HTTP header on every request to the Portal API as below:

Authorization: Bearer YOUR_TOKEN

This token must be kept secret and therefore not be exposed in the frontend or any public files as it can allow unauthorized parties to access sensitive information or perform malicious modifications.

Guest Booking and User Booking

You can book appointments on behalf of users without a patient account by omitting the patient_id parameter during the booking process.

This will always result in a new patient record in the corresponding healthcare institution, even if the patient data (e.g. name, date of birth) are identical. There is no matching possible as the data is encrypted upon booking.

For patients with an account (user booking), you must provide a unique patient_id parameter. The integrator is responsible for ensuring that a patient user has been properly authenticated and authorized before performing any action on their behalf.

Step 1: Getting the available insurance

First, let’s retrieve the available insurances for a given portal. Please note that we are passing the authorization HTTP header as described in the section Authorization:

curl -X 'GET' 'https://app.samedi.de/api/portal/v1/insurances' -H "Authorization: Bearer YOUR_TOKEN"

After fetching a list of insurances, you need to prompt your user about which insurance they would like to use. In this example, we’ll use insurance ID(136) for future usage.

Step 2: Getting the appointment category

To get the appointment categories specified on the Institution, by making use of the selected insurance’s ID(136), make the following request as in the cURL example below, as:

  curl -X 'GET' 'https://app.samedi.de/api/portal/v1/appointment_categories?insurance_id=136&page=1' -H "Authorization: Bearer YOUR_TOKEN"

The response contains a list categories with their IDs and names. Make note of an ID of one of those appointment categories(e.g., 53). We will use it in Step 3.

Step 3: Getting the appointment type

Now, to get the appointment types specified on the Institution, make the following CURL request using both the auth token header and the previous category id 53, plus the insurance id 136 we’ve fetched in the previous steps,

curl -X 'GET' 'https://app.samedi.de/api/portal/v1/appointment_types?page=1&appointment_category_id=53&insurance_id=136' -H "Authorization: Bearer YOUR_TOKEN"

The response provides a set of appointment types. Make a note of the ID of one of them. Example: 198

Step 4: Getting availabilities

To get availabilities (the times you could book an appointment for), we will now need to use the values we’ve found on the earlier steps, being:

• appointment category: 53

• appointment type: 198

• insurance id: 136

The request will be:

curl -X 'GET' 'https://app.samedi.de/api/portal/v1/appointment_types/198/availabilities?appointment_category_id=53&insurance_id=136' -H "Authorization: Bearer YOUR_TOKEN"

Pick a time and note its id from response for request in the next step. Example: 7r8Uq4AD9Rjk9XNN0FSC6UFR5kkqNICCTjpPCbX1uOUJKPfcuRijxYTW_kVCJ0LOWE9pnCfm4thH8sS4XHdPf8OUWWikWmXWLn3e2nngB6ZzQF5q4xp2i6L+8Y75FXW8r3FktJ_qldsXUvgm6cPXl7q1DFjlAm3k8ANNqGBHDQZb+YTSZAMh6xeY--FFj0c3l1F_pUuY9N--ITaASrPXMda95yi_TjAYsw==

Step 5: Booking the appointment using the selected availability

We will now use the /booking endpoint on a POST request to make the appointment.

We add a few parameters to the body of the request, besides the availability ID fetched in previous Step 4 . Here’s an example using curl to make the request:

curl -X POST https://app.samedi.de/api/portal/v1/booking \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -d '{"availability_id":"7r8Uq4AD9Rjk9XNN0FSC6UFR5kkqNICCTjpPCbX1uOUJKPfcuRijxYTW_kVCJ0LOWE9pnCfm4thH8sS4XHdPf8OUWWikWmXWLn3e2nngB6ZzQF5q4xp2i6L+8Y75FXW8r3FktJ_qldsXUvgm6cPXl7q1DFjlAm3k8ANNqGBHDQZb+YTSZAMh6xeY--FFj0c3l1F_pUuY9N--ITaASrPXMda95yi_TjAYsw==", "patient_data": {"first_name": "John", "last_name": "Doe", "mobile": "1234567890", "phone": "12345", "title": "Sir", "email": "jdoe@example.com", "gender": "m", "insurance": "TK", "born_on": "2024-05-23"}, "structured_comment": {}, "notify_with": {"first_name": "John", "last_name": "Doe", "title": "Sir", "email": "jdoe@example.com", "mobile": "+11 1111 1111", "gender": "m", "insurance": "TK", "born_on": "2024-05-23"}}'

And on the response, you’ll get the Appointment ID (example: xbCuVVTNU6rT6E5m8p6Y8h7opzfo)

Rescheduling an appointment

Step 1: Getting availabilities (user booking only)

Given the appointment ID (example: xbCuVVTNU6rT6E5m8p6Y8h7opzfo) and the corresponding patient ID (example: c877209f-fedd-41ed-99fe-10d379a008b9), we can request new availabilities under the same appointment type and category.

curl -X 'GET' \
  'https://app.samedi.de/api/portal/v1/appointments/xbCuVVTNU6rT6E5m8p6Y8h7opzfo/availabilities?patient_id=c877209f-fedd-41ed-99fe-10d379a008b9' \
  -H 'accept: application/json' \
  -H 'Authorization: YOUR_TOKEN'

In the response, you will get a list of availabilities and their times, in the same pattern as they are in the previous section.

Step 2: Rescheduling appointment

With the availability ID for a selected time and the patient ID (example: c877209f-fedd-41ed-99fe-10d379a008b9), we can now reschedule the appointment.

Availability ID example:

7r8Uq4AD9Rjk9XNN0FSC6UFR5kkqNICCTjpPCbX1uOUJKPfcuRijxYTW_kVCJ0LOWE9pnCfm4thH8sS4XHdPf8OUWWikWmXWLn3e2nngB6ZzQF5q4xp2i6L+8Y75FXW8r3FktJ_qldsXUvgm6cPXl7q1DFjlAm3k8ANNqGBHDQZb+YTSZAMh6xeY--FFj0c3l1F_pUuY9N--ITaASrPXMda95yi_TjAYsw==

curl -X 'POST' \
  'https://app.samedi.de/api/portal/v1/reschedule' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"availability_id":"7r8Uq4AD9Rjk9XNN0FSC6UFR5kkqNICCTjpPCbX1uOUJKPfcuRijxYTW_kVCJ0LOWE9pnCfm4thH8sS4XHdPf8OUWWikWmXWLn3e2nngB6ZzQF5q4xp2i6L+8Y75FXW8r3FktJ_qldsXUvgm6cPXl7q1DFjlAm3k8ANNqGBHDQZb+YTSZAMh6xeY--FFj0c3l1F_pUuY9N--ITaASrPXMda95yi_TjAYsw==","patient_id": "c877209f-fedd-41ed-99fe-10d379a008b9", "notify_with": {"first_name": "John", "last_name": "Doe", "title": "Sir", "email": "jdoe@example.com", "mobile": "+11 1111 1111", "gender": "m", "insurance": "TK", "born_on": "2024-05-23"}}'

A successful rescheduling moves only the appointment time. It won’t change the original appointment ID, which is returned in the response.

Cancelling an appointment

By using the previously created appointment ID (example: xbCuVVTNU6rT6E5m8p6Y8h7opzfo)

curl -X POST https://app.samedi.de/api/portal/v1/appointments/m8ehhdciA69CaaT5bDQyJxMjuujA/cancel -H "Content-Type: application/json" -H "Authorization: Bearer MY_TOKEN"
{"data":{"id":"m8ehhdciA69CaaT5bDQyJxMjuujA"}}

The success response contains ID of the cancelled appointment.

Using ASAP list

ASAP list is an appointment feature that patients can opt into. They are then notified via email when earlier availability becomes available for their booked appointments.

Configuring appointment type

A prerequisite for a subscribable ASAP list is to enable the feature in appointment type configuration by ticking the checkbox 'Allow patients to register for earlier appointment notifications'. In the payload of appointment types request (as shown in step 3 in the previous section), the parameter asap_notifications_enabled indicates the state of the feature.

Booking appointment with ASAP list subscription

An appointment can be booked with ASAP list subscription by using parameter asap_list_opt_in . Considering the aforementioned booking example, the request body will be extended as in the following CURL request example:

curl -X POST https://app.samedi.de/api/portal/v1/booking \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -d '{"availability_id":"7r8Uq4AD9Rjk9XNN0FSC6UFR5kkqNICCTjpPCbX1uOUJKPfcuRijxYTW_kVCJ0LOWE9pnCfm4thH8sS4XHdPf8OUWWikWmXWLn3e2nngB6ZzQF5q4xp2i6L+8Y75FXW8r3FktJ_qldsXUvgm6cPXl7q1DFjlAm3k8ANNqGBHDQZb+YTSZAMh6xeY--FFj0c3l1F_pUuY9N--ITaASrPXMda95yi_TjAYsw==", "patient_data": {"first_name": "John", "last_name": "Doe", "mobile": "1234567890", "phone": "12345", "title": "Sir", "email": "jdoe@example.com", "gender": "m", "insurance": "TK", "born_on": "2024-05-23"}, "structured_comment": {}, "notify_with": {"first_name": "John", "last_name": "Doe", "title": "Sir", "email": "jdoe@example.com", "mobile": "+11 1111 1111", "gender": "m", "insurance": "TK", "born_on": "2024-05-23"}, "asap_list_opt_in": {"email": "jdoe@example.com"}}'

As before, it responds with the new appointment ID in the response payload.

ASAP list un-/subscription after booking

It’s also possible to enter or leave the ASAP list after appointments have been booked. As an ASAP list is always appointment-specific, the appointment ID is always required in requests.

Subscription

Email must be provided in the request payload: An example of the curl request with an appointment ID (example: xbCuVVTNU6rT6E5m8p6Y8h7opzfo):

curl -X PUT 'https://app.samedi.de/api/portal/v1/appointments/xbCuVVTNU6rT6E5m8p6Y8h7opzfo/asap_list_subscription' \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -d '{"asap_list_opt_in": { "email": "jdoe@example.com" }}'

The appointment ID will be in the response payload for a successful subscription.

Unsubscription

Taking the same appointment ID (example: xbCuVVTNU6rT6E5m8p6Y8h7opzfo) for the CURL request,

curl -X DELETE 'https://app.samedi.de/api/portal/v1/appointments/xbCuVVTNU6rT6E5m8p6Y8h7opzfo/asap_list_subscription' -H "Content-Type: application/json"  -H "Authorization: Bearer YOUR_TOKEN"

The shape of the response will be the same as that for subscription.

Getting earlier availability

With an ASAP list subscription, one can request an earlier appointment availability.
By using the appointment ID (example: xbCuVVTNU6rT6E5m8p6Y8h7opzfo), the curl can be built as follows:

curl -X 'GET' \                                                                                                     
  'https://app.samedi.de/api/portal/v1/appointments/xbCuVVTNU6rT6E5m8p6Y8h7opzfo/asap_availability' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN'

The response contains the appointment detail and an earlier availability, which is in the same format as previously discussed.

Rescheduling appointment to an earlier availability

It works the same way as described in the previous section.