Initial Setup

These timum API endpoints handle the one-time setup of your organizational structure: create Users, Accounts, and Providers.

1. User - Person with login credentials
2. Account - Client/company (requires a User as owner)
3. Provider - Calendar profile (requires a User as owner)
4. Staff - Add employees to the Provider (optional)

Users

A User represents a person with login credentials, access rights, and contact details. Users can be owners of Accounts and Providers, and can also act as Staff or as a contact person.

Create User

Creates a new User, or returns an existing one if the reference is already known.

curl -X POST "https://www.timum.de/crms/{crmId}/user" \
  -H "X-TIMUM-CLIENT-ID: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "12345@yourCrm",
    "email": "max@example.com",
    "username": "maxmustermann",
    "firstName": "Max",
    "lastName": "Mustermann",
    "phone": "+49 30 12345678",
    "mobile": "+49 170 1234567"
  }'

Path Parameters

Request Body

Algorithm / Behavior

• Reference already exists: Returns the existing User (200 OK). The fields phone, mobile, lastName, firstName are updated.
• Email exists with a different reference: A new User is created with a generated email (e.g. max+001@example.com).
• Email exists without a reference: The existing User is used. Its email verification is invalidated, a new verification email is sent, and the reference is attached.
• New User: The User is created (201 Created). The language is taken from the CRM actor user (can be overridden via the PLAY_LANG cookie).

Response

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

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

Errors

Get User

Retrieves a User by its reference.

curl -X GET "https://www.timum.de/crms/{crmId}/user/12345@yourCrm" \
  -H "X-TIMUM-CLIENT-ID: your-api-key"

Path Parameters

Response

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

Errors

Accounts

An Account represents a client in timum with a booked service plan and billing data. Each Account belongs to a User (owner).

Create Account

Creates a new Account, or returns an existing one if the reference is already known.

curl -X POST "https://www.timum.de/crms/{crmId}/account" \
  -H "X-TIMUM-CLIENT-ID: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "ownerReference": "12345@yourCrm",
    "accountReference": "acc-001@yourCrm",
    "branch": "real-estate",
    "invoiceAddress": {
      "city": "Berlin",
      "countryCode": "DE",
      "street": "Musterstraße",
      "number": "28",
      "zip": "10115"
    },
    "invoiceContactName": "Max Mustermann",
    "invoiceCompanyName": "Mustermann Immobilien GmbH",
    "invoiceTaxId": "DE123456789",
    "email": "buchhaltung@example.com"
  }'

Request Body

Algorithm / Behavior

• accountReference unknown: A new Account is created (201 Created).
• accountReference already known: The existing Account is returned (200 OK). The fields of the existing Account are not overwritten.

Response

{
  "api-info": {
    "version": "1"
  },
  "account": {
    "ownerReference": "12345@yourCrm",
    "branch": "real-estate",
    "accountReference": "acc-001@yourCrm",
    "invoiceAddress": {
      "city": "Berlin",
      "countryCode": "DE",
      "street": "Musterstraße",
      "number": "28",
      "zip": "10115"
    },
    "invoiceContactName": "Max Mustermann",
    "invoiceCompanyName": "Mustermann Immobilien GmbH",
    "invoiceTaxId": "DE123456789",
    "email": "buchhaltung@example.com"
  }
}

Errors

Get Account

Retrieves an Account by its reference.

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

Response

{
  "api-info": {
    "version": "1"
  },
  "account": {
    "ownerReference": "12345@yourCrm",
    "branch": "real-estate",
    "accountReference": "acc-001@yourCrm",
    "invoiceAddress": {
      "city": "Berlin",
      "countryCode": "DE",
      "street": "Musterstraße",
      "number": "28",
      "zip": "10115"
    },
    "invoiceContactName": "Max Mustermann",
    "invoiceCompanyName": "Mustermann Immobilien GmbH",
    "invoiceTaxId": "DE123456789",
    "email": "buchhaltung@example.com"
  }
}

Errors

Providers

A Provider represents a calendar profile that contains resources and services (Products). Providers have Staff members (Users) who have access to the Provider.

Create Provider

Creates a new Provider.

curl -X POST "https://www.timum.de/crms/{crmId}/provider" \
  -H "X-TIMUM-CLIENT-ID: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "prov-001@yourCrm",
    "ownerReference": "12345@yourCrm",
    "accountReference": "acc-001@yourCrm",
    "name": "Mustermann Immobilien",
    "email": "kontakt@mustermann-immo.de",
    "mobile": "+49 170 1234567",
    "phone": "+49 30 12345678",
    "impressum": "Mustermann Immobilien GmbH, Musterstraße 28, 10115 Berlin",
    "branch": "real-estate",
    "subbranch": "IS24PROFI"
  }'

Request Body

Response

{
  "api-info": {
    "version": "1"
  },
  "provider": {
    "uuid": "0a3006b0-43c7-11e4-96eb-06df9a948f2f",
    "reference": "prov-001@yourCrm",
    "name": "Mustermann Immobilien",
    "email": "kontakt@mustermann-immo.de",
    "mobile": "+49 170 1234567",
    "phone": "+49 30 12345678",
    "impressum": "Mustermann Immobilien GmbH, Musterstraße 28, 10115 Berlin",
    "branch": "real-estate",
    "subbranch": "IS24PROFI"
  }
}

Get Provider

Retrieves a Provider by its reference.

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

Response

Returns the Provider data (as with Create Provider).

Errors

Staff

Staff are Users who are assigned to a Provider and have access to its calendar.

List Staff

Lists all Staff members of a Provider.

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

Path Parameters

Response

[
  {
    "reference": "user-123@yourCrm",
    "email": "thomas@example.com",
    "username": "thomas.anderson",
    "firstName": "Thomas",
    "lastName": "Anderson",
    "phone": "030 1101011",
    "mobile": "+49 170 1234567"
  },
  {
    "reference": "user-456@yourCrm",
    "email": "forrest@example.com",
    "username": "forrest.gump",
    "firstName": "Forrest",
    "lastName": "Gump",
    "phone": "030 123456789",
    "mobile": "+49 170 9876543"
  }
]

Next Steps

After setting up your organizational structure, you can:

• Configure Offerings - create resources, products, and contact profiles
• Set up Scheduling - create availabilities and appointments

Related Topics

• API Overview
• What is a resource?
• What is an appointment type?