Initial Setup

Diese Endpunkte dienen der einmaligen Einrichtung Ihrer Organisationsstruktur in timum. Erstellen Sie Users, Accounts und Providers, bevor Sie Ressourcen und Termine verwalten können.

Einrichtungsreihenfolge

Die Entitäten hängen voneinander ab. Erstellen Sie sie in dieser Reihenfolge:

User - Person mit Login-Daten
Account - Mandant/Unternehmen (benötigt User als Owner)
Provider - Kalenderprofil (benötigt User als Owner)
Staff - Mitarbeiter zum Provider hinzufügen (optional)

Users

Ein User repräsentiert eine Person mit Login-Credentials, Zugriffsrechten und Kontaktdaten. Users können Eigentümer von Accounts und Providern sein sowie als Staff oder Kontaktperson fungieren.

Create User

Erstellt einen neuen User oder gibt einen existierenden zurück, falls die Referenz bereits bekannt ist.

POST /crms/:crmId/userbash

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"
  }'

Pfad-Parameter

Parameter	Typ	Beschreibung
`crmId`	string	Ihre CRM-Kennung (wird bei der Integration vergeben)

Request Body

Feld	Typ	Pflicht	Beschreibung
`reference`	string	Ja	Eindeutige Referenz im Format `uniqueId@platformName`. Verwenden Sie die ID, unter der Sie diesen User in Ihrem System führen.
`email`	string	Ja	E-Mail-Adresse. Muss in timum eindeutig sein. Bei Duplikat: Wenn eine andere Referenz gesendet wird, wird eine generierte Email erstellt (z.B. `max+001@example.com`).
`username`	string	Ja	Login-Benutzername. Muss eindeutig sein. Folgende Zeichen sind nicht erlaubt: `/?:&#\`
`lastName`	string	Ja	Nachname des Users
`firstName`	string	Nein	Vorname des Users
`phone`	string	Nein	Festnetznummer
`mobile`	string	Nein	Mobilnummer

Algorithmus / Verhalten

Referenz existiert bereits: Gibt den existierenden User zurück (200 OK). Die Felder phone, mobile, lastName, firstName werden aktualisiert.
Email existiert mit anderer Referenz: Ein neuer User mit generierter Email wird erstellt (z.B. max+001@example.com).
Email existiert ohne Referenz: Der existierende User wird verwendet. Seine Email-Verifizierung wird invalidiert, eine neue Verifizierungs-Mail wird gesendet, und die Referenz wird angehängt.
Neuer User: User wird erstellt (201 Created). Die Sprache wird vom CRM-Actor-User übernommen (überschreibbar via Cookie PLAY_LANG).

Response

201 Created - Neuer Userjson

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

200 OK - Existierender Userjson

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

Fehler

Status	Ursache
`400`	Pflichtfeld fehlt, ist null oder leer
`409`	Email oder Username bereits vergeben. Fehlermeldung: "User with given email already exists." oder "User with given username already exists."

Get User

Ruft einen User anhand seiner Referenz ab.

GET /crms/:crmId/user/:referencebash

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

Pfad-Parameter

Parameter	Typ	Beschreibung
`crmId`	string	Ihre CRM-Kennung
`reference`	string	Die User-Referenz (URL-encoded falls Sonderzeichen)

Response

200 OKjson

{
  "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"
  }
}

Fehler

Status	Ursache
`404`	Kein User mit dieser Referenz gefunden

Accounts

Ein Account repräsentiert einen Mandanten in timum mit gebuchtem Service-Plan und Rechnungsdaten. Jeder Account gehört einem User (Owner).

Create Account

Erstellt einen neuen Account oder gibt einen existierenden zurück, falls die Referenz bereits bekannt ist.

POST /crms/:crmId/accountbash

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

Feld	Typ	Pflicht	Beschreibung
`ownerReference`	string	Ja	Referenz des Users, der Eigentümer dieses Accounts wird. Der User muss bereits existieren.
`accountReference`	string	Ja	Eindeutige Referenz für diesen Account im Format `uniqueId@platformName`.
`branch`	string	Ja	Branche des Unternehmens. Erlaubte Werte: `real-estate` - Immobilien `facilities` - Facility Management `handyman` - Handwerk `sports-and-leisure` - Sport & Freizeit `misc` - Sonstiges
`invoiceAddress`	object	Nein	Rechnungsadresse. Wenn angegeben, sind alle Unterfelder Pflicht: `city`, `countryCode`, `street`,`number`, `zip`
`invoiceContactName`	string	Nein	Name des Rechnungsempfängers
`invoiceCompanyName`	string	Nein	Firmenname
`invoiceTaxId`	string	Nein	Umsatzsteuer-ID
`email`	string	Nein	E-Mail-Adresse für Rechnungen

Algorithmus / Verhalten

accountReference unbekannt: Neuer Account wird erstellt (201 Created).
accountReference bereits bekannt: Existierender Account wird zurückgegeben (200 OK). Die Felder des existierenden Accounts werden nicht überschrieben.

Response

201 Createdjson

{
  "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"
  }
}

Fehler

Status	Ursache	Meldung
`400`	Pflichtfeld fehlt oder leer	-
`404`	Owner-User nicht gefunden	"no user found for ownerReference"
`404`	Ungültige Branche	"Unable to find specified branch. Was {givenBranch}..."
`404`	Ungültiges Referenz-Format	"Unable to parse account reference. Was {givenReference}..."

Get Account

Ruft einen Account anhand seiner Referenz ab.

GET /crms/:crmId/account/:referencebash

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

Response

200 OKjson

{
  "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"
  }
}

Fehler

Status	Ursache
`404`	Kein Account mit dieser Referenz gefunden

Providers

Ein Provider repräsentiert ein Kalenderprofil, das Ressourcen und Services (Products) enthält. Providers haben Staff-Mitglieder (Users), die Zugriff auf den Provider haben.

Create Provider

Erstellt einen neuen Provider.

POST /crms/:crmId/providerbash

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

Feld	Typ	Pflicht	Beschreibung
`reference`	string	Ja	Eindeutige Provider-Referenz
`ownerReference`	string	Ja	Referenz des Users, der Eigentümer wird
`accountReference`	string	Ja	Referenz des zugehörigen Accounts
`name`	string	Ja	Anzeigename des Providers
`email`	string	Nein	Kontakt-E-Mail
`mobile`	string	Nein	Mobilnummer
`phone`	string	Nein	Telefonnummer
`impressum`	string	Nein	Impressum-Text
`branch`	string	Nein	Branche (siehe Account)
`subbranch`	string	Nein	Unterbranche (z.B. "IS24PROFI")

Response

201 Createdjson

{
  "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

Ruft einen Provider anhand seiner Referenz ab.

GET /crms/:crmId/provider/:referencebash

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

Response

Gibt die Provider-Daten zurück (wie bei Create Provider).

Fehler

Status	Ursache
`404`	Kein Provider mit dieser Referenz gefunden

Staff

Staff sind Users, die einem Provider zugeordnet sind und Zugriff auf dessen Kalender haben.

List Staff

Listet alle Staff-Mitglieder eines Providers auf.

GET /crms/:crmId/provider/:providerRef/staffbash

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

Pfad-Parameter

Parameter	Typ	Beschreibung
`crmId`	string	Ihre CRM-Kennung
`providerRef`	string	Provider-Referenz

Response

200 OKjson

[
  {
    "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"
  }
]

Array-Response

Im Gegensatz zu anderen Endpunkten gibt dieser Endpunkt direkt ein Array zurück, nicht ein Objekt mit api-info Wrapper.

Nächste Schritte

Nach der Einrichtung Ihrer Organisationsstruktur können Sie:

Offerings konfigurieren - Ressourcen, Produkte und Kontaktprofile erstellen
Scheduling einrichten - Verfügbarkeiten und Termine erstellen

Initial Setup

Users

Create User

Pfad-Parameter

Request Body

Algorithmus / Verhalten

Response

Fehler

Get User

Pfad-Parameter

Response

Fehler

Accounts

Create Account

Request Body

Algorithmus / Verhalten

Response

Fehler

Get Account

Response

Fehler

Providers

Create Provider

Request Body

Response

Get Provider

Response

Fehler

Staff

List Staff

Pfad-Parameter

Response

Nächste Schritte

Verwandte Themen