Configure Offerings

With the timum API, you define what you offer: Products (services), Resources (bookable objects), and Contact Profiles (public contact details).

Configuration Order

Create Products - The services you offer
Create Resources - The bookable objects (properties, rooms, staff)
Create Contact Profiles (optional) - Public contact details

Products (Services)

A Product defines a type of service you offer (e.g. "viewing", "consultation"). Products have time constraints (min/max duration) and can be linked to resources.

Create Product

Creates a new product for a provider.

POST /crms/:crmId/provider/:providerRef/products

curl -X POST "https://www.timum.de/crms/{crmId}/provider/prov-001@yourCrm/products" \
  -H "X-TIMUM-CLIENT-ID: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "prod-besichtigung@yourCrm",
    "name": "Besichtigung",
    "description": "30-minütige Objektbesichtigung mit unserem Experten",
    "minDuration": 30,
    "maxDuration": 45
  }'

Path Parameters

Parameter	Type	Description
`crmId`	string	Your CRM identifier
`providerRef`	string	Provider reference

Request Body

Field	Type	Required	Description
`reference`	string	Yes	Unique product reference
`name`	string	Yes	Display name of the product
`description`	string	No	Description for customers (e.g. notes about the appointment)
`minDuration`	number	No	Minimum duration in minutes
`maxDuration`	number	No	Maximum duration in minutes

Response

201 Created

{
  "api-info": {
    "version": "1"
  },
  "product": {
    "uuid": "92867f70-4836-11e5-bc04-021a52c25043",
    "reference": "prod-besichtigung@yourCrm",
    "name": "Besichtigung",
    "description": "30-minütige Objektbesichtigung mit unserem Experten",
    "minDuration": 30,
    "maxDuration": 45,
    "leadTimeMinutes": null,
    "followUpTimeMinutes": null
  }
}

Lead/Follow-Up Time:

leadTimeMinutes and followUpTimeMinutes define buffer times before and after the appointment. These can be configured via the timum interface.

Get Products

Lists all products of a provider.

GET /crms/:crmId/provider/:providerRef/products

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

Response

200 OK

[
  {
    "uuid": "92867f70-4836-11e5-bc04-021a52c25043",
    "reference": "prod-besichtigung@yourCrm",
    "name": "Besichtigung",
    "description": "30-minütige Objektbesichtigung",
    "minDuration": 30,
    "maxDuration": 45,
    "leadTimeMinutes": null,
    "followUpTimeMinutes": null
  },
  {
    "uuid": "0bb978c0-5740-11eb-8b95-024759471364",
    "reference": "prod-beratung@yourCrm",
    "name": "Beratungsgespräch",
    "description": "Individuelle Beratung",
    "minDuration": 15,
    "maxDuration": 30,
    "leadTimeMinutes": null,
    "followUpTimeMinutes": null
  }
]

Resources

A Resource represents a bookable object - typically a property, a room, a vehicle, or a staff member. Resources are linked to Products to specify which services are offered on that resource.

Create Resource

Creates a new resource or updates an existing one (if onDuplicateRaise=false).

POST /crms/:crmId/provider/:providerRef/resources

curl -X POST "https://www.timum.de/crms/{crmId}/provider/prov-001@yourCrm/resources?onDuplicateRaise=false" \
  -H "X-TIMUM-CLIENT-ID: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "res-musterstr1@yourCrm",
    "publicName": "Musterstraße 1 - 3-Zimmer-Wohnung",
    "internalName": "Objekt 4711 - Musterstraße",
    "description": "Schöne 3-Zimmer-Wohnung mit Balkon im 2. OG",
    "products": ["prod-besichtigung@yourCrm", "prod-beratung@yourCrm"],
    "contact": "user-123@yourCrm",
    "contactProfileReference": "profile-1@yourCrm",
    "website": "https://example.com/objekt/4711",
    "address": {
      "city": "Berlin",
      "countryCode": "DE",
      "street": "Musterstraße",
      "number": "1",
      "zip": "10115"
    }
  }'

Query Parameters

Parameter	Type	Default	Description
`onDuplicateRaise`	boolean	false	If true: the request fails with 400 if the reference already exists. If false: the existing resource is updated.

Request Body

Field	Type	Required	Description
`reference`	string	Yes	Unique resource reference
`publicName`	string	Yes	Name shown to customers
`internalName`	string	Yes	Internal name for the provider
`description`	string	No	Description of the resource
`products`	string[]	No	Array of product references. The products must already exist. Defines which services are offered on this resource.
`contact`	string	No*	User reference as the contact person. *Required if contactProfileReference is given.
`contactProfileReference`	string	No	Reference of a Contact Profile. Must belong to the contact user.
`website`	string	No	URL to the resource's website
`address`	object	No	Address of the resource. countryCode is optional (default: "DE"). All other fields (city, zip, street, number) are required if address is given.

Response

201 Created

{
  "reference": "res-musterstr1@yourCrm",
  "uuid": "264de7b0-0e4a-11ea-988f-fa1e49f3d761",
  "provider": "prov-001@yourCrm",
  "publicName": "Musterstraße 1 - 3-Zimmer-Wohnung",
  "internalName": "Objekt 4711 - Musterstraße",
  "description": "Schöne 3-Zimmer-Wohnung mit Balkon im 2. OG",
  "contact": "user-123@yourCrm",
  "archived": false,
  "products": ["prod-besichtigung@yourCrm", "prod-beratung@yourCrm"],
  "address": {
    "city": "Berlin",
    "countryCode": "DE",
    "street": "Musterstraße",
    "number": "1",
    "zip": "10115"
  }
}

Update Resource

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

POST /crms/:crmId/provider/:providerRef/resources/:resourceRef

curl -X POST "https://www.timum.de/crms/{crmId}/provider/prov-001@yourCrm/resources/res-musterstr1@yourCrm" \
  -H "X-TIMUM-CLIENT-ID: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "publicName": "Musterstraße 1 - Traumwohnung mit Balkon",
    "products": ["prod-besichtigung@yourCrm"],
    "archived": false
  }'

Additional Field for Update

Field	Type	Description
`archived`	boolean	Sets the resource to archived (true) or active (false). Archived resources can no longer be booked by customers.

Response

Returns the updated resource (as with Create). Status: 202 Accepted.

Get Resources

Lists all resources of a provider.

GET /crms/:crmId/provider/:providerRef/resources

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

Response

200 OK

[
  {
    "reference": "res-musterstr1@yourCrm",
    "uuid": "264de7b0-0e4a-11ea-988f-fa1e49f3d761",
    "provider": "prov-001@yourCrm",
    "publicName": "Musterstraße 1 - 3-Zimmer-Wohnung",
    "internalName": "Objekt 4711 - Musterstraße",
    "description": "Schöne 3-Zimmer-Wohnung",
    "contact": "user-123@yourCrm",
    "archived": false,
    "products": ["prod-besichtigung@yourCrm"],
    "address": {
      "city": "Berlin",
      "countryCode": "DE",
      "street": "Musterstraße",
      "number": "1",
      "zip": "10115"
    }
  }
]

Delete Resource

Deletes a resource. Fails if there are future appointments (unless ignoreFutureAppointments=true).

DELETE /crms/:crmId/provider/:providerRef/resources/:resourceRef

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

Query Parameters

Parameter	Type	Description
`ignoreFutureAppointments`	boolean	If true: the resource is deleted even if there are future appointments. All participants are notified of the cancellation and the appointments are archived.

Irreversible:

Deleting a resource is irreversible. Use archived: true on the update endpoint if you only want to deactivate the resource.

Contact Profiles

Contact Profiles define how a user is presented publicly. They contain contact channels (phone, email, video links, etc.) that customers see.

General vs. Provider-Specific Profile

General Profile: A user's default profile, used when no specific profile is assigned
Provider Profile: A specific profile for a particular provider

Get General Profile

Retrieves a user's general contact profile.

GET /crms/:crmId/user/:userRef/generalContactProfile

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

Response

200 OK

{
  "name": "Max Mustermann - Immobilienexperte",
  "contactChannels": [
    {
      "label": "Mobil",
      "type": "mobile",
      "value": "+49 170 1234567"
    },
    {
      "label": "Email",
      "type": "email",
      "value": "max@example.com"
    },
    {
      "label": "Telefon",
      "type": "phone",
      "value": "+49 30 12345678"
    }
  ]
}

Update General Profile

Updates a user's general contact profile.

PUT /crms/:crmId/user/:userRef/generalContactProfile

curl -X PUT "https://www.timum.de/crms/{crmId}/user/user-123@yourCrm/generalContactProfile" \
  -H "X-TIMUM-CLIENT-ID: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Max Mustermann - Ihr Immobilienexperte",
    "contactChannels": [
      {
        "label": "Mobil",
        "type": "mobile",
        "value": "+49 170 1234567"
      },
      {
        "label": "Email",
        "type": "email",
        "value": "max@example.com"
      },
      {
        "label": "Telefon",
        "type": "phone",
        "value": "+49 30 12345678"
      },
      {
        "label": "Video-Call",
        "type": "video",
        "value": "https://meet.example.com/max"
      }
    ]
  }'

Request Body

Field	Type	Required	Description
`name`	string	Yes	Public name. May differ from the login name (e.g. company name).
`contactChannels`	array	Yes	Array of contact channels

Contact Channel Fields

Field	Type	Required	Description
`label`	string	No	Display label for the channel
`type`	string	Yes	Channel type. Allowed values: `mobile` - mobile number (visible to customers); `phone` - landline (visible to customers); `email` - email (visible to customers, for transactional emails); `video` - video call link; `messenger` - messenger; `link` - general link; `location` - address/location
`value`	string	Yes	Value of the channel (number, email, URL, address)

Algorithm for contactChannels

New type in the array: A new channel is created
Existing type in the array: The channel is updated
Type missing from the array: The channel is removed

One Channel Per Type:

Currently only one channel per type can exist. Multiple phone numbers require different types (e.g. phone and mobile).

Get Profile (Provider-Specific)

Retrieves a provider-specific contact profile.

GET /crms/:crmId/provider/:providerRef/contactProfile/:profileRef

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

Errors

Status	Cause
`404`	No profile found with this reference

Create or Update Profile (Provider-Specific)

Creates or updates a provider-specific contact profile.

POST /crms/:crmId/provider/:providerRef/contactProfile

curl -X POST "https://www.timum.de/crms/{crmId}/provider/prov-001@yourCrm/contactProfile" \
  -H "X-TIMUM-CLIENT-ID: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "profile-1@yourCrm",
    "userReference": "user-123@yourCrm",
    "providerReference": "prov-001@yourCrm",
    "name": "Mustermann Immobilien - Vertrieb",
    "contactChannels": [
      {
        "label": "Hotline",
        "type": "phone",
        "value": "+49 30 12345678"
      },
      {
        "label": "Vertrieb",
        "type": "email",
        "value": "vertrieb@mustermann-immo.de"
      },
      {
        "label": "Büro",
        "type": "location",
        "value": "Musterstraße 28, 10115 Berlin"
      }
    ]
  }'

Request Body

Field	Type	Required	Description
`reference`	string	Yes	Unique profile reference
`userReference`	string	Yes	Reference of the user this profile belongs to
`providerReference`	string	Yes	Reference of the provider this profile applies to
`name`	string	Yes	Public display name
`contactChannels`	array	Yes	Array of contact channels (see Update General Profile)

Usage in Resources/Appointments

To use a profile, set the following when creating a resource or an appointment:

contact: user reference
contactProfileReference: profile reference

The profile must belong to the contact user and must be valid for the provider in which the resource/appointment is created.

Fallback:

If no contactProfileReference is given, the contact user's General Profile is used. If no contact is given, the provider's information is shown.

Next Steps

With Offerings configured, you can now:

Set up Scheduling - Timeslots, Appointments, Participations, Customers
Integrate the Booking Flow - Consumer-facing booking endpoints

Configure Offerings

Products (Services)

Create Product

Path Parameters

Request Body

Response

Get Products

Response

Resources

Create Resource

Query Parameters

Request Body

Response

Update Resource

Additional Field for Update

Response

Get Resources

Response

Delete Resource

Query Parameters

Contact Profiles

Get General Profile

Response

Update General Profile

Request Body

Contact Channel Fields

Algorithm for contactChannels

Get Profile (Provider-Specific)

Errors

Create or Update Profile (Provider-Specific)

Request Body

Usage in Resources/Appointments

Next Steps

Related Topics