REST API Overview

The timum API enables developers to fully integrate appointment booking programmatically into your platform as a white-label solution.

Base URL

All API requests are sent to the following base URL:

API Base URL

https://www.timum.de

HTTPS required:

HTTP requests are automatically redirected to HTTPS. Always use HTTPS. Also make sure to use www. in the URL - requests without www. can lead to redirect issues.

Authentication

All API requests must be authenticated with your API key. The key is transmitted in the HTTP header X-TIMUM-CLIENT-ID:

Authentication via header

curl -X GET "https://www.timum.de/crms/{crmId}/resources" \
  -H "X-TIMUM-CLIENT-ID: your-api-key" \
  -H "Content-Type: application/json"

Obtaining an API key

You will receive your API key (also called "directUseSecret") from timum when your integration is set up. The key is bound to your CRM ID and grants access to all resources within your CRM context.

CRM ID:

The crmId is your unique identifier as a timum partner. It is assigned once during integration and remains constant. All API paths contain this ID as a path parameter.

Reference Format

timum uses a unified reference format to uniquely identify entities. References consist of two parts, separated by @:

Reference Format

{uniqueId}@{platformName}

Beispiele:
- 12345@yourCrmUser          (User-Referenz)
- abc-def-123@yourCrmAccount (Account-Referenz)
- property-42@yourCrmResource (Ressourcen-Referenz)

Components

Part	Description
`uniqueId`	The ID under which you manage this entity in your system
`platformName`	Your platform suffix, agreed upon during integration (e.g. "yourCrm", "is24")

Storing references:

Use IDs that you already have or can generate. Otherwise, store the references you use when creating entities. You will need them for all subsequent operations on these entities.

API Areas

The API is structured by use case:

1. Setup – Initial Setup

Users, Accounts, Providers, Staff - build the basic structure

2. Configuration – Configure Offerings

Resources, Products, Contact Profiles - define your offering

3. Appointment scheduling – Scheduling

Timeslots, Appointments, Participations, Customers

4. Booking – Booking Flow

Consumer-facing endpoints for appointment booking

Response Format

All API responses are in JSON format. Each response includes an api-info object with version information:

Successful response (example: User created)

{
  "api-info": {
    "version": "1"
  },
  "user": {
    "reference": "12345@yourCrm",
    "email": "max@example.com",
    "username": "maxmustermann",
    "firstName": "Max",
    "lastName": "Mustermann",
    "phone": null,
    "mobile": null
  }
}

Error Response

In case of errors, the response contains an errors array with error codes and messages:

Error Response

{
  "api-info": {
    "version": "1"
  },
  "errors": [
    {
      "errorCode": "201",
      "message": "Das überlappt mit einem anderen Termin."
    }
  ]
}

HTTP Status Codes

Code	Meaning	Typical Situation
`200`	OK	Request successful, existing entity returned
`201`	Created	New entity successfully created
`202`	Accepted	Update successfully accepted
`204`	No Content	Successful, but no data to return (e.g. customer not found)
`400`	Bad Request	Required field missing, invalid format, incorrect reference
`404`	Not Found	Referenced entity does not exist
`409`	Conflict	Duplicate detected (e.g. email or username already taken)
`412`	Precondition Failed	Appointment already booked, capacity exhausted

Common Error Codes

errorCode	Meaning
`201`	Time overlap with existing appointment

CORS

The API supports Cross-Origin Resource Sharing (CORS) for browser-based integrations. Preflight requests are answered automatically.

CORS headers

Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: POST, GET, OPTIONS, PUT, DELETE
Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Authorization, X-Auth-Token

Next Steps

Initial Setup - Start by creating Users and Accounts
Configure Offerings - Define resources and products
Scheduling - Create availabilities and appointments
Booking Flow - Integrate appointment booking

REST API Overview

Base URL

Authentication

Obtaining an API key

Reference Format

Components

API Areas

1. Setup – Initial Setup

2. Configuration – Configure Offerings

3. Appointment scheduling – Scheduling

4. Booking – Booking Flow

Response Format

Error Response

HTTP Status Codes

Common Error Codes

CORS

Next Steps

For end users