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

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:

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:

Appointment Types

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.

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:

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:

Field Types:

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

Possible Errors:

Available Days:

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:

Available Times

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:

User Information

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:

Institution Details (required patient data)

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:

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.