Scheduling

The timum API manages availabilities (Timeslots), appointments, participations, and customers – the heart of appointment scheduling.

Concept overview

- Timeslot (Availability): Time window during which bookings are possible - Appointment: Booked time slot with participants - Participation: Link between Customer and Appointment - Customer: Contact details of the person booking

Timeslots (Availabilities)

A Timeslot defines that a resource is available for a period of time. The period is divided into bookable slots by a grid.

Grid concept

Example: A conference room is available from 8:00 to 18:00 (Timeslot). Bookings are possible in 30-minute blocks (grid = 30). This results in 20 bookable slots of 30 minutes each.

Create Timeslots

Creates one or more Timeslots for a resource.

POST /crms/:crmId/provider/:providerRef/timeslots

curl -X POST "https://www.timum.de/crms/{crmId}/provider/prov-001@yourCrm/timeslots" \
  -H "X-TIMUM-CLIENT-ID: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "timeslots": [
      {
        "reference": "tsl-2024-01-15@yourCrm",
        "resourceReference": "res-musterstr1@yourCrm",
        "start": "2024-01-15T09:00",
        "end": "2024-01-15T17:00",
        "raster": 30,
        "defaultCapacity": 1,
        "defaultAcceptBookings": true,
        "address": {
          "city": "Berlin",
          "zip": "10115",
          "country": "DE",
          "street": "Musterstraße",
          "number": "1"
        },
        "state": "BOOKABLE"
      }
    ]
  }'

Request Body

Field	Type	Required	Description
`timeslots`	array	Yes	Array of Timeslot objects

Timeslot Object Fields

Field	Type	Required	Description
`reference`	string	No	Unique Timeslot reference (generated if not provided)
`resourceReference`	string	Yes	Reference of the associated resource
`start`	datetime	No	Start of the Timeslot (ISO 8601)
`end`	datetime	Yes	End of the Timeslot (ISO 8601)
`raster`	number	Yes	Duration of a booking slot in minutes. Divides the Timeslot into bookable units.
`defaultCapacity`	number	Yes	Maximum participants per created Appointment
`defaultAcceptBookings`	boolean	Yes	`true`: Publicly bookable. `false`: Appointment becomes private (further bookings only by the provider).
`address`	object \| string	No	Address for Appointments. Can be an object or a string (e.g. "Zoom: https://zoom.us/j/123")
`state`	string	Yes	`CREATED`: Hidden (planning phase). `BOOKABLE`: Publicly visible and bookable.

Address as a string (e.g. for video calls)

{
  "address": "Zoom-Meeting: https://zoom.us/j/123456789"
}

Get Timeslots

Retrieves all Timeslots of a resource within a time period.

GET /crms/:crmId/provider/:providerRef/resource/:resourceRef/timeslots

curl -X GET "https://www.timum.de/crms/{crmId}/provider/prov-001@yourCrm/resource/res-musterstr1@yourCrm/timeslots?from=2024-01-15T00:00&to=2024-01-22T00:00" \
  -H "X-TIMUM-CLIENT-ID: your-api-key"

Query Parameters

Parameter	Type	Required	Description
`from`	datetime	Yes	Start date (ISO 8601)
`to`	datetime	Yes	End date (ISO 8601)

Appointments included

The response also contains Appointment data if a Timeslot already has booked appointments.

Update Timeslot

Updates an existing Timeslot. Only the fields provided are changed.

PUT /crms/:crmId/provider/:providerRef/timeslots/:timeslotRef

curl -X PUT "https://www.timum.de/crms/{crmId}/provider/prov-001@yourCrm/timeslots/tsl-2024-01-15@yourCrm" \
  -H "X-TIMUM-CLIENT-ID: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "start": "2024-01-15T10:00",
    "end": "2024-01-15T16:00",
    "raster": 30,
    "defaultCapacity": 2,
    "defaultAcceptBookings": true,
    "state": "BOOKABLE"
  }'

Delete Timeslot

Deletes a Timeslot.

DELETE /crms/:crmId/provider/:providerRef/timeslots/:timeslotRef

curl -X DELETE "https://www.timum.de/crms/{crmId}/provider/prov-001@yourCrm/timeslots/tsl-2024-01-15@yourCrm" \
  -H "X-TIMUM-CLIENT-ID: your-api-key"

Prerequisite

Fails if the Timeslot has a non-cancelled Appointment. Delete or cancel the Appointment first.

Appointments

Appointments are booked appointments. They can be created individually, as a sequence, or as a series spanning multiple days.

Get Appointments

Retrieves Appointments of a provider. Includes active and cancelled appointments.

GET /crms/:crmId/provider/:providerRef/appointments

curl -X GET "https://www.timum.de/crms/{crmId}/provider/prov-001@yourCrm/appointments?productRef=prod-besichtigung@yourCrm&resourceRef=res-musterstr1@yourCrm&includeArchived=false" \
  -H "X-TIMUM-CLIENT-ID: your-api-key"

Query Parameters

Parameter	Type	Description
`productRef`	string	Filter by product (optional)
`resourceRef`	string	Filter by resource (optional)
`includeArchived`	boolean	Include archived Appointments (default: false)

Response

200 OK

[
  {
    "reference": "apt-001@yourCrm",
    "acceptBookings": true,
    "address": {
      "city": "Berlin",
      "countryCode": "DE",
      "street": "Musterstraße",
      "number": "1",
      "zip": "10115"
    },
    "archived": false,
    "capacity": 1,
    "contactReference": "user-123@yourCrm",
    "description": "Besichtigung",
    "start": "2024-01-15T10:00:00Z",
    "end": "2024-01-15T10:30:00Z",
    "notes": null,
    "participations": [
      {
        "reference": "part-001@yourCrm",
        "email": "kunde@example.com",
        "mobile": "+49 170 9876543",
        "name": "Max Kunde",
        "note": "",
        "state": "BOOKED",
        "messages": null
      }
    ],
    "price": null,
    "productReference": "prod-besichtigung@yourCrm",
    "resourceReference": "res-musterstr1@yourCrm",
    "seriesId": null,
    "state": "ACTIVE"
  }
]

Create Appointments

Creates Appointments. Supports individual appointments, sequences, and series.

POST /crms/:crmId/provider/:providerRef/appointments - Single appointment

curl -X POST "https://www.timum.de/crms/{crmId}/provider/prov-001@yourCrm/appointments" \
  -H "X-TIMUM-CLIENT-ID: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "apt-001@yourCrm",
    "start": "2024-01-15T10:00",
    "end": "2024-01-15T11:00",
    "capacity": 1,
    "acceptBookings": true,
    "resourceReference": "res-musterstr1@yourCrm",
    "productReference": "prod-besichtigung@yourCrm",
    "productName": "Besichtigung",
    "contactReference": "user-123@yourCrm",
    "address": {
      "city": "Berlin",
      "zip": "10115",
      "country": "DE",
      "street": "Musterstraße",
      "number": "1"
    },
    "participations": [
      {
        "reference": "part-001@yourCrm",
        "name": "Max Kunde",
        "email": "kunde@example.com",
        "mobile": "+49 170 9876543",
        "note": "Interessiert an 3-Zimmer-Wohnung",
        "state": "BOOKED"
      }
    ],
    "price": {
      "value": 0.00,
      "currency": "EUR"
    }
  }'

Request Body (Single Appointment)

Field	Type	Required	Description
`reference`	string	Yes*	*Required for single appointment, ignored for series
`start`	datetime	Yes	Start (ISO 8601)
`end`	datetime	Yes	End (ISO 8601)
`capacity`	number	No	Max. participants (default: 0)
`acceptBookings`	boolean	No	Publicly bookable (default: false)
`resourceReference`	string	Yes	Resource reference
`productReference`	string	Yes	Product reference
`productName`	string	No	Overrides the product name
`contactReference`	string	No	Responsible Staff
`address`	object \| string	No	Address (default: resource address)
`participations`	array	No	Participants of the Appointment
`price`	object	No	Price (value, currency: EUR/CHF)

Participation Object

Field	Type	Required	Description
`reference`	string	Yes*	*Required for single appointment
`name`	string	Yes	Name of the participant
`email`	string	Yes	Email of the participant
`mobile`	string	No	Mobile number
`note`	string	No	Note about the participant
`state`	string	Yes	RESERVED, REQUESTED, BOOKED, CANCELED, DELETED

RESERVED status

Participations with status RESERVED are automatically deleted after 3 minutes!

Create series

POST /crms/:crmId/provider/:providerRef/appointments - Series

curl -X POST "https://www.timum.de/crms/{crmId}/provider/prov-001@yourCrm/appointments" \
  -H "X-TIMUM-CLIENT-ID: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "2024-01-15T09:00",
    "to": "2024-01-15T17:00",
    "capacity": 1,
    "acceptBookings": true,
    "resourceReference": "res-musterstr1@yourCrm",
    "productReference": "prod-besichtigung@yourCrm",
    "series_data": {
      "from": "2024-01-15T09:00",
      "to": "2024-01-19T17:00",
      "raster": 30,
      "weekdays": ["1", "2", "3", "4", "5"]
    }
  }'

series_data Object

Field	Type	Required	Description
`from`	datetime	Yes	Start of the series (ISO 8601)
`to`	datetime	Yes	End of the series (ISO 8601)
`raster`	number	Yes	Slot duration in minutes
`weekdays`	string[]	No*	*Required for more than 1 day. Array of weekdays: "1"=Mon to "7"=Sun

Delete Appointments (without notification)

Deletes Appointments without notifying participants. For administrative corrections.

DELETE /crms/:crmId/provider/:providerRef/appointments/withoutNotification

curl -X DELETE "https://www.timum.de/crms/{crmId}/provider/prov-001@yourCrm/appointments/withoutNotification" \
  -H "X-TIMUM-CLIENT-ID: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "appointmentReference": "apt-001@yourCrm"
  }'

Request Body

Field	Type	Description
`appointmentReference`	string	Reference of the Appointment to delete
`seriesId`	string	OR: ID of a series (deletes all Appointments of the series)

No notification

Participants are not informed about the deletion! Use this only for administrative corrections.

Cancel Appointments

Cancels Appointments and notifies all participants by email.

DELETE /crms/:crmId/provider/:providerRef/appointments

curl -X DELETE "https://www.timum.de/crms/{crmId}/provider/prov-001@yourCrm/appointments?message=Der%20Termin%20muss%20leider%20abgesagt%20werden" \
  -H "X-TIMUM-CLIENT-ID: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "appointmentReference": "apt-001@yourCrm"
  }'

Query Parameters

Parameter	Type	Description
`message`	string	Message to participants (in the cancellation email)

Behavior

Sets the Appointment state to CANCELLED
Sets all Participation states to CANCELLED
Sends cancellation emails to all participants
The Appointment is no longer bookable

Participations

Participations connect Customers with Appointments. Each Participation has a status that reflects the booking process.

Participation States

State	Description
`RESERVED`	Temporarily reserved. Automatically deleted after 3 minutes.
`REQUESTED`	Request submitted, awaiting confirmation by the provider.
`BOOKED`	Confirmed and booked.
`CANCELED`	Cancelled by the Customer or provider.
`DELETED`	Deleted administratively (without notification).

Create Participation

Adds a Customer to an Appointment.

POST /crms/:crmId/provider/:providerRef/participations

curl -X POST "https://www.timum.de/crms/{crmId}/provider/prov-001@yourCrm/participations?ignoreCapacity=false&onDuplicateRaise=false&sendMails=true" \
  -H "X-TIMUM-CLIENT-ID: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "part-002@yourCrm",
    "appointmentReference": "apt-001@yourCrm",
    "customerReference": "cust-001@yourCrm",
    "state": "BOOKED",
    "message": "Bestätigung Ihrer Terminbuchung"
  }'

Query Parameters

Parameter	Type	Default	Description
`ignoreCapacity`	boolean	false	Add Participation even when capacity is full
`onDuplicateRaise`	boolean	false	For an existing reference: true=error, false=update
`sendMails`	boolean	true	Send notification emails

Request Body

Field	Type	Required	Description
`reference`	string	Yes	Unique Participation reference
`appointmentReference`	string	Yes	Appointment reference
`customerReference`	string	Yes	Customer reference
`state`	string	Yes	RESERVED, REQUESTED, BOOKED, CANCELED, DELETED
`message`	string	No	Message in the email to the Customer

Update Participation

Changes the status of a Participation.

POST /crms/:crmId/provider/:providerRef/participations/:participationRef

curl -X POST "https://www.timum.de/crms/{crmId}/provider/prov-001@yourCrm/participations/part-002@yourCrm?sendMails=true" \
  -H "X-TIMUM-CLIENT-ID: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "CANCELED",
    "message": "Leider müssen wir Ihren Termin stornieren."
  }'

State Transitions with Email Notifications

Transition	Email?
RESERVED → BOOKED	✓ Yes
REQUESTED → BOOKED	✓ Yes
REQUESTED → CANCELED	✓ Yes
BOOKED → CANCELED	✓ Yes
RESERVED → CANCELED	✗ No
DELETED → CANCELED	✗ No
BOOKED → DELETED	✗ No (!)

Unsupported transitions

Transitions to RESERVED or REQUESTED are not possible. Create a new Participation instead.

Customers

Customers are people who book appointments. They belong to a provider and can participate in multiple Appointments.

Get Customer

Retrieves a Customer by its reference.

GET /crms/:crmId/provider/:providerRef/customers/:customerRef

curl -X GET "https://www.timum.de/crms/{crmId}/provider/prov-001@yourCrm/customers/cust-001@yourCrm" \
  -H "X-TIMUM-CLIENT-ID: your-api-key"

Response

200 OK

{
  "api-info": {
    "version": "1"
  },
  "customer": {
    "customerReference": "cust-001@yourCrm",
    "email": "kunde@example.com",
    "note": "Interessiert an 3-Zimmer-Wohnungen",
    "userName": "Max Kunde",
    "mobile": "+49 170 9876543",
    "language": "de",
    "providerReference": "prov-001@yourCrm"
  }
}

Status Codes

Code	Meaning
`200`	Customer found
`204`	No Customer found with this reference

Create Customer

Creates a new Customer for a provider.

POST /crms/:crmId/provider/:providerRef/customers

curl -X POST "https://www.timum.de/crms/{crmId}/provider/prov-001@yourCrm/customers" \
  -H "X-TIMUM-CLIENT-ID: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "customerReference": "cust-001@yourCrm",
    "providerReference": "prov-001@yourCrm",
    "userName": "Max Kunde",
    "email": "kunde@example.com",
    "mobile": "+49 170 9876543",
    "note": "Interessiert an 3-Zimmer-Wohnungen",
    "language": "de"
  }'

Request Body

Field	Type	Required	Description
`customerReference`	string	Yes	Unique Customer reference
`providerReference`	string	Yes	Provider reference
`userName`	string	Yes	Name of the customer
`email`	string	No	Email address
`mobile`	string	No	Mobile number (with country code)
`note`	string	No	Internal note (max. 1023 characters)
`language`	string	No	Language code (de, en, etc.)

Status Codes

Code	Meaning
`201`	New Customer created
`200`	Customer already exists

Update Customer

Updates an existing Customer.

PUT /crms/:crmId/provider/:providerRef/customers/:customerRef

curl -X PUT "https://www.timum.de/crms/{crmId}/provider/prov-001@yourCrm/customers/cust-001@yourCrm" \
  -H "X-TIMUM-CLIENT-ID: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "customerReference": "cust-001-new@yourCrm",
    "email": "neue-email@example.com",
    "userName": "Max Neukunde",
    "mobile": "+49 170 1111111",
    "note": "Aktualisierte Notiz"
  }'

Changing the reference

You can also change the customerReference. userName and customerReference cannot be set to null/empty.

Delete Customer

Deletes a Customer.

DELETE /crms/:crmId/provider/:providerRef/customers/:customerRef

curl -X DELETE "https://www.timum.de/crms/{crmId}/provider/prov-001@yourCrm/customers/cust-001@yourCrm?ignoreFutureAppointments" \
  -H "X-TIMUM-CLIENT-ID: your-api-key"

Query Parameters

Parameter	Description
`ignoreFutureAppointments`	When set: removes the Customer from all future Appointments. The Customer is notified by email (if configured).

Future Appointments

Without ignoreFutureAppointments, the request fails if the Customer is participating in future Appointments.

GDPR

Deleting a Customer removes all personal data in accordance with GDPR. The booking history is retained in anonymized form.

Next Steps

Booking Flow - Consumer-facing endpoints for bookings

Scheduling

Timeslots (Availabilities)

Create Timeslots

Request Body

Timeslot Object Fields

Get Timeslots

Query Parameters

Update Timeslot

Delete Timeslot

Appointments

Get Appointments

Query Parameters

Response

Create Appointments

Request Body (Single Appointment)

Participation Object

Create series

series_data Object

Delete Appointments (without notification)

Request Body

Cancel Appointments

Query Parameters

Behavior

Participations

Participation States

Create Participation

Query Parameters

Request Body

Update Participation

State Transitions with Email Notifications

Customers

Get Customer

Response

Status Codes

Create Customer

Request Body

Status Codes

Update Customer

Delete Customer

Query Parameters

Next Steps

Related Topics