samedi API Reference

Appointment Data

Table of contents

  1. Appointment Categories
  2. Appointment Types
  3. Available Days
  4. Available Times
  5. User Information
  6. Institution Details (required patient data)
  7. Structured Comment Fields

The following workflow (categories lead to appointment types lead to dates lead to times lead to booking), just shows an example. Depending on your needs, it is for example possible to skip the request for categories and directly request the appointment types.

Appointment Categories

General
URL https://patient.samedi.de/api/booking/v3/event_categories
Parameters practice_id, insurance_id optional, born_on optional
Authentication API Key

This endpoint returns an array of appointment categories for a single institution. The institution is specified in the parameter practice_id. Optionally, the parameters insurance_id and born_on can be used to specify to pre-filter the delivered categories. Depending on the configuration of the institution this may effect the result of the request.

Sample Request:

GET /api/booking/v3/event_categories?practice_id=PRACTICE_ID&client_id=CLIENT_ID HTTP/1.1
Host: patient.samedi.de

Sample Response:

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

{
  "scope":"limited",
  "data": [{
    "name": "Smith, George",
    "id": 14,
    "description": "<p>Welcome to Radiology.</p>\n",
    "subtitle": "Radiologist",
    "photo_url": "https://patient.samedi.de/images/photo.png"
  }, {
    "name": "Green, James",
    "id": 17,
    "description": null,
    "subtitle": null,
    "photo_url": null
  }]
}

If an insurance_id is not specified, all online bookable appointment categories will be displayed with each consisting of a name and a unique ID. Appointment categories which are targeted to specific health insurance plans are returned within a special scope named limited. If none of the categories has any limitation then all of the results are within a scope named all. Finally, if an insurance_id is specified (to denote the patient’s health insurance) the results contain only appointment categories which have specified the same insurance conditions.

Example: The institution has 3 appointment categories:

No. category insurances
1 public consultations public
2 private consultations private
3 emergency consultation all insurances

When the request delivers the parameter insurance_id=private the API will return the categories 2 and 3, because only there can be booked appointments for private patients

Note: It is always possible for the Client to retrieve and display all possible appointment categories for a practice/institution by omitting the insurance_id. However it is recommended that the Client presents the users only with the appointment categories which include appointment types that can be actually booked by the user’s insurance.

The field description is an html code, subtitle is a string and photo_url is the URL path of an image.

Possible Errors:

Error Status Code Description
Institution not found 404 practice_id is missing or invalid
The terms Appointment and Event are used interchangeably and they both refer to the same concept.

Appointment Types

General
URL https://patient.samedi.de/api/booking/v3/event_types
Parameters event_category_id, insurance_id optional, born_on optional - in YYYY-MM-DD format)
Authentication API Key

This endpoint returns an array of appointment types, together with the location they are bound to, for a particular appointment category. The appointment category is specified by its unique ID in the parameter event_category_id. Optionally, a health company can be specified by its unique id in the insurance_id parameter. Specifying an insurance company may affect the returned results as explained below.

Optionally, a born_on parameter can be specified. If any of the appointment types has age restrictions (minimum or maximum age required), the born_on date will be used to filter and return the fitting results.

when the patient is younger than the appointment type permits, the appointment type will still be returned by this endpoint. The rationale is to allow patients to book the appointment type for a future point at which the age restriction is fulfilled. The booking step will ensure that these restrictions are met anyway.

Sample Request:

GET /api/booking/v3/event_types?event_category_id=8&client_id=CLIENT_ID HTTP/1.1
Host: patient.samedi.de

Sample Response:

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

{
	"data": [{
		"id": 17,
		"name": "Sprechstunde",
		"comment_form": [],
		"attendant_user_required": true,
		"description": "<p>Bitte wählen Sie zur Terminvereinbarung für eine Sprechstunde diese Terminart.</p>\n",
		"is_video_consultation": false,
		"total_price": "8.74",
		"patient_can_book_without_account": false,
		"key_values": [{
			"language": "english"
		}],
		"asap_list_enabled": false,
		"location": {
			"name": "St. Marien Klinikum im Friedrichshain",
			"street": "Rigaer Str. 44",
			"zip": "10247",
			"city": "Berlin",
			"country": "DE",
			"latitude": 52.5150915,
			"longitude": 13.4686259,
			"phone": "+49 30 2123 0707 2",
			"fax": "+49 30 2123 0707-9",
			"opening_hours": "Mo-Di: 9:00-12:00\nMi-Fr: 14:30 -18:00"
		}
	}, {
		"id": 18,
		"name": "Video-Sprechstunde",
		"comment_form": [{
			"name": "Beschwerden",
			"required": false,
			"type": "textfield",
			"config": null
		}, {
			"name": "Beschwerden seit",
			"required": true,
			"type": "date",
			"config": null
		}],
		"attendant_user_required": true,
		"description": "<p>Bitte wählen Sie zur Terminvereinbarung für eine Video-Sprechstunde diese Terminart.</p>\n",
		"is_video_consultation": true,
		"total_price": null,
		"patient_can_book_without_account": false,
		"key_values": [],
		"asap_list_enabled": false,
		"location": {
			"name": "St. Marien Klinikum im Friedrichshain",
			"street": "Rigaer Str. 44",
			"zip": "10247",
			"city": "Berlin",
			"country": "DE",
			"latitude": 52.5150915,
			"longitude": 13.4686259,
			"phone": "+49 30 2123 0707 2",
			"fax": "+49 30 2123 0707-9",
			"opening_hours": "Mo-Di: 9:00-12:00\nMi-Fr: 14:30 -18:00"
		}
	}],
	"scope": "limited",
	"event_category_id": "8",
	"tagged": null
}

If an insurance_id is not specified all online bookable appointment types, for the specified appointment category, are returned. Each appointment type consists of a name, a unique ID and some comment fields. Appointment types with special insurance limitations are enclosed in a limited scope. If none of the appointment types have any insurance limitations all the results are returned within a scope named all.

If an insurance_id value is specified (representing the user’s insurance), the response will only contain the appointment types which are possible to book through the specified insurance.

The boolean field attendant_user_required represents whether an actual samedi patient-user is required to perform the booking or not. When false, the patient data can be transmitted as parameters during the booking step. When true, the user is required to sign in with her samedi patient account.

The field description is an html code

Response Parameters:

Field Type Description
id number id of the event type
name string external name of the event type
comment_form arrary array of comment fields Further Information
attendant_user_required boolean is a samedi user required to book event type?
description string descritption of the event type for for the patient
is_video_consultation boolean is the event type a video_consultation? About video consultation appointments
total_price float price of the event type in €
patient_can_book_without_account boolean event type can be booked without patient user account?
key_values array an array of keys and its values configured in the event type
asap_list_enabled boolean is the possibility to opt-in to the asap list enabled for the event type? About earlier appoinmtent list
location object more details in Location

Location:

Field Type Description
name string name of the location
street null or string street of the location
zip null or string zip code of the location
city null or string city of the location
country string alpha-2 country code
latitude null or float latitude of the location
longitude null or float longitude of the location
phone null or string contact phone number of the location
fax null or string fax number of the location
opening_hours null or string opening hours of the location

An appointment may contain a list of comment fields under they key comment_form. Each comment field is defined by the following options:

Field Options:

Option Possible Values Description
name free text the displayed name of the field
config null or an object according to the field type type-specific configuration
type see field types below sets the field type
required true, false whether the field is mandatory

Field Types:

Type Description Configuration Options
checkbox check box none
combo drop-down list available options as strings, one per line
date date picker To restrict the valid dates set restrictions: future, past, or none
duration time selection field none
textarea multi-line text box none
textfield single-line text field none
time time picker none
qrcode single-line text field none

Unknown (misspelled) field types are treated as regular single-line text fields.

Possible Errors:

Error Status Code Description
Appointment type or category not found 404 event_category_id is missing or invalid

Available Days:

General
URL https://patient.samedi.de/api/booking/v3/dates
Parameters event_category_id, event_type_id, date optional, from optional, to optional, insurance_id optional, born_on optional
Authentication API Key

This endpoint returns an array of available days for the requested appointment category (parameter event_category_id) and appointment type (parameter event_type_id). Each array element contains a date and its availability (true or false). A day is considered available if there is at least an available and bookable timeslot within that day.

If the optional date parameter is provided, only available days of the date’s month will be returned. For a more fine grained searching it is possible to provide a specific date range by setting the dates in the parameters from and to (the maximum range is capped at 12 months). Nonetheless, whole months will be returned even if the range is specifying a subset of a month’s dates. The ending range always equals the 1st of the next month specified in the to param.

The insurance can be also optionally specified in the insurance_id parameter.

For appointment types with maximal and/or minimum age the parameter born_on must be specified to ensure that the request provides the correct dates for the patient. The response will only deliver available: true when born currently fits the age restrictions

Sample Request:

GET /api/booking/v3/dates?event_category_id=14&event_type_id=9&date=2011-05-01&client_id=CLIENT_ID&born_on=1944-10-23 HTTP/1.1
Host: patient.samedi.de

Sample Response:

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

{
  "data":[{
    "available":false,
    "date":"2011-05-29"
  },{
    "available":false,
    "date":"2011-05-20"
  },{
    "available":false,
    "date":"2011-05-07"
  },{
    "available":false,
    "date":"2011-05-21"
  },{
    "available":false,
    "date":"2011-05-12"
  },{
    "available":true,
    "date":"2011-05-26"
  },{
    "available":false,
    "date":"2011-05-13"
  },{
    "available":false,
    "date":"2011-05-04"
  },{
    "available":true,
    "date":"2011-05-27"
  },{
    "available":false,
    "date":"2011-05-18"
  },{
    "available":false,
    "date":"2011-05-05"
  },{
    "available":false,
    "date":"2011-05-19"
  },{
    "available":false,
    "date":"2011-05-10"
  },{
    "available":true,
    "date":"2011-05-24"
  },{
    "available":false,
    "date":"2011-05-11"
  },{
    "available":false,
    "date":"2011-05-02"
  },{
    "available":true,
    "date":"2011-05-25"
  },{
    "available":false,
    "date":"2011-05-16"
  },{
    "available":false,
    "date":"2011-05-03"
  },{
    "available":true,
    "date":"2011-05-30"
  },{
    "available":false,
    "date":"2011-05-17"
  },{
    "available":false,
    "date":"2011-05-08"
  },{
    "available":false,
    "date":"2011-05-31"
  },{
    "available":false,
    "date":"2011-05-22"
  },{
    "available":false,
    "date":"2011-05-09"
  },{
    "available":false,
    "date":"2011-05-23"
  },{
    "available":false,
    "date":"2011-05-14"
  },{
    "available":false,
    "date":"2011-05-01"
  },{
    "available":false,
    "date":"2011-05-28"
  },{
    "available":false,
    "date":"2011-05-15"
  },{
    "available":false,
    "date":"2011-05-06"
  }]
}

Possible Errors:

Error Status Code Description
Appointment type or category not found 404 event_category_id or event_type_id missing or invalid
Forbidden with current insurance settings 403 insurance_id not matching the selected appointment type

Available Times

General
URL https://patient.samedi.de/api/booking/v3/times
Parameters event_category_id, event_type_id, date optional, insurance_id optional, from optional, to optional
Authentication API Key

This endpoint returns an array of all available times, for the specified date or date range, appointment category (parameter event_category_id) and appointment type (parameter event_type_id). Each array element contains a timeslot for booking an appointment. The response might contain other elements, which must be ignored. The patient’s insurance can be optionally specified in the insurance_id parameter.

Searching for times in a specific date can be accomplished by setting the date parameter or, for a date range (multiple days in sequence), both from and to parameters. Ranges are capped at 12 months maximum. If none of these options are set then the current day is assumed and the available times for this are returned.

Sample Request:

GET /api/booking/v3/times?event_category_id=14&event_type_id=9&date=2011-06-01&client_id=CLIENT_ID HTTP/1.1
Host: patient.samedi.de

Sample Response:

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

{
  "data": [{
    "time":"2011-06-01T09:10:00+02:00"
  },{
    "time":"2011-06-01T10:00:00+02:00"
  },{
    "time":"2011-06-01T11:00:00+02:00"
  },{
    "time":"2011-06-01T12:00:00+02:00"
  },{
    "time":"2011-06-01T13:00:00+02:00"
  }]
}

Possible Errors:

Error Status Code Description
Appointment type or category not found 404 event_category_id or event_type_id missing or invalid
Forbidden with current insurance settings 403 insurance_id not matching the selected appointment type

User Information

General
URL https://patient.samedi.de/api/booking/v3/user
Parameters none
Authentication OAuth
Scope profile:read

This endpoint returns the full name and insurance ID of the Resource Owner (user) whose Access Token, authorized with the scope ‘profile:read’, is provided in the Authorization HTTP header. The Client can use this name to address the user in a personalized manner. The insurance ID can be used to filter the appropriate appointment categories and types in subsequent steps.

Sample Request:

GET /api/booking/v3/user HTTP/1.1
Host: patient.samedi.de
Authorization: Bearer SlAV32hkKG

Sample Response:

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

{
  "user": {
    "id": "dac9fffa-d1bb-39a8-9ce6-2e11e0cb66d7"
    "full_name": "Rogers, Anne",
    "last_name": "Rogers",
    "first_name": "Anne",
    "email": "anne@rogers.de",
    "insurance_number": null,
    "insurance_company_id": 5
  }
}

Possible Errors:

Error Status Code Description
forbidden 403 invalid scope of access token
unauthorized 401 invalid oauth token

Institution Details (required patient data)

General
URL https://patient.patient.samedi.de/api/booking/v3/practices/:practice_id
Parameters practice_id
Authentication API Key

This endpoint returns the institution’s name and the required patient fields.

The required_patient_fields contains the name of the parameters which are expected to be provided in the attendant field later on, during booking. When sending the patient data while booking the appointment, it is not checked if all mandatory fields are specified, this must be handled by the application

Sample Request:

GET /api/booking/v3/practices/PRACTICE_ID?client_id=CLIENT_ID HTTP/1.1
Host: patient.samedi.de

Sample Response:

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

{
   "name": "Praxis Mustermann",
   "required_patient_fields": ["first_name", "last_name", "email"],
   "use_own_booking_integration_url": null
}

If a non-empty value is present for the use_own_booking_integration_url field, this institution requires that all appointment bookings go through this provided URL and therefore the user must be redirected to that URL or otherwise be prohibited from booking via other 3rd party integrations.

Possible Errors:

Error Status Code Description
Institution not found 404 practice_id missing or invalid

Structured Comment Fields

  1. General
  2. date
  3. duration
  4. checkbox
  5. combo
  6. Troubleshooting

General

An appointment can have multiple comment fields (comment sets) which are configured in the samedi account. When requesting the appointment types the API will return for every appointment type the comment_form that is is specified for it for online booking (See Appointment Booking).

The Client application/service is expected to send these to the API during the booking operation. The comment data must be sent as hash with parameter name structured_comment. For every element the key should be the name of the comment field and the value should be the one entered by the user.

If for example an appointment type specifies two required comment fields, say “diabetes” of type checkbox and “birthday” of type date, the expected booking request should provide the user-entered values to these. A sample request with the structured_comment hash (URL-encoded) would look like:

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

event_category_id=14
&event_type_id=9
&starts_at=2011-06-01T12:00+02:00
&structured_comment[diabetes]=true
&structured_comment[birthday]=1979-03-12

Date Field

Format

yyyy-mm-dd

Special Properties

The date has a property restriction which can have the values future, past or none. This property states if the delivered date has to be in the future or past or has no restrictions at all.

Example

{
  "name":"Date",
  "required":false,
  "type":"date",
  "config": {
    "restriction":"none",
    "emptyText":""
  }
}

Duration Field

Format

hh:mm

Example

{
  "name":"Duration",
  "required":false,
  "type":"duration",
  "config":null
}

Checkbox Field

Special Properties

The checkbox is considered as checked when value is one of ja, yes, si, oui, true, 1, on. All other values would mean, that the checkbox is not checked.

Example

{
  "name":"Checkbox",
  "required":false,
  "type":"checkbox",
  "config":null
}

Combo Field

Special Properties

A combo field can allow for either single or multiple value selection. This is determined by the property mutli within the field’s config object. A single selection field would have a value of "multi":"off" while a multi-select field would have a v value of "multi":"on".

You can find the valid values of the field also on the config object in the parameter values. The values are seperated by \n

When the appointment is booked the selected values have to be transferred separated by \u200c,: e.g. Value 1\u200c, Value 3 would select Value 1 and Value 3 in a corresponding comment field.

Examples

Single select combo
{
  "name":"Single Select",
  "required":false,
  "type":"combo",
  "config":{
    "values":"1\n2\n3\n4",
    "emptyText":"",
    "multi":"off"
  }
}
Multi select combo
{
  "name":"Multi Select",
  "required":false,
  "type":"combo",
  "config":{
    "values":"1\n2\n3\n4",
    "emptyText":"",
    "multi":"on"
  }
}

Troubleshooting

If comment fields are omitted, incorrectly formatted or incomplete, the API returns an HTTP status code of 400 along with a description of the validation error. A list of the possible errors follows.

Field Type Error Description
any type FIELD can’t be empty A required field was not provided
checkbox FIELD must be accepted A required check box has not been clicked
date FIELD must be in the past The date must be in the past (before the current date)
date FIELD must be in the future The date must be in the future
date FIELD is not a date The date is not properly formatted
combo FIELD must have one of the given values The value must be one of the selectable options
duration FIELD is invalid The duration is not in the hh:mm format