CentralStationCRM API Dokumentation

API Navigation

Allgemeines: Grundlagen Authentifizierung Fehlerbehandlung Datenstruktur

Hauptmodelle: Personen Firmen Angebote Projekte Aufgaben

Sonstiges: Anschriften Kontaktdaten Wichtige Daten Individuelle Felder Positionen Notizen Dateianhänge Tags

Die Kür: Webhooks Nutzer Aktivitäten Filter Gruppen Individuelle Feld Typen

Die CentralStationCRM API ist zustandsbehaftet nach dem REST Model. Die Kommunikation findet ausschließlich verschlüsselt über das HTTPs Protokoll statt, wobei die gewünschte Operation über das HTTP Verb bestimmt wird. Die eigentlichen Daten werden dann als im JSON Format übertragen.
Bei Fragen melde dich kurz per E-Mail an developer [at] 42he.com.

Hinweis: Die Beispiele verwenden das Unix Tool curl, welches sich sehr gut zum Testen eignet. Natürlich kannst du jede beliebige HTTP Bibliothek in der Programmiersprache deiner Wahl nutzen.

Für Ruby on Rails Entwickler stellen wir ein umfassendes API Demo Projekt zur Verfügung. Hier müssen Sie nur Ihre Accountnamen und den API Schlüssel hinterlegen und Sie können mit den Daten in Ihrem Account interagieren. Das Projekt ist öffentlich bei Github.

Für PHP gibt es einen API wrapper bei Github.

Grundlagen für die Nutzung der API

Die gewünschte Aktion wird über den Aufruf der jeweiligen Ressource mit dem gewünschten Verb (GET, PUT, POST oder DELETE) ausgeführt. Parameter wie beispielsweise der Account werden über die HTTP URI übergeben. Diese ist nach einem festen Schema aufgebaut:

https://accountname.centralstationcrm.net/api/:objects/:id/:action.json

Jedes Objekt lässt sich eindeutig über seine URI identifizieren. Diese ist persistent und ändert sich bis zum Löschen des Elementes nicht mehr. Hierbei ist zu beachten, das die IDs nicht sequentiell sind. Eine Objekt kann z.B. die ID 5 haben, das nächste die ID 324. Um eine Liste aller Personen in einem CentralStationCRM Account zu erhalten, kann man eine GET Anfrage wie folgt senden. Als Rückgabe erhält man JSON.

curl -X GET https://accountname.centralstationcrm.net/api/people.json

Zudem gibt es für verschachtelte Objekte (1-n Relationen) verschachtelte Routen. Um also zum Beispiel für die Person mit der ID 4759 einzelne Stammdaten (Contact Details), Tags oder Adressdaten (addrs) zu erhalten ist folgender Aufruf nötig:

curl -X GET https://accountname.centralstationcrm.net/api/people/:person_id/contact_details.json

Die verschachtelten Routen sind allgemein nach dem folgenden Schema aufgebaut:

https://accountname.centralstationcrm.net/api/:object_klass_name/:id/:subobject:/:id/:action.json

Einbinden von verschachtelten Objekten

Alternativ können viele der Unterobjekte auch bei dem Abruf der Index Seiten mit abgefragt werden. Das funktioniert über den parameter includes. Die möglichen includes werden jeweils für die Modelle beschrieben, hier nur ein Beispiel für die Personen:

curl -X GET https://accountname.centralstationcrm.net/api/people.json?includes=companies tags avatar tels emails

[
{"person":{"id":455636,"account_id":21,"user_id":64,"title":"","gender":2,
"first_name":"Karl-Heinz","name":"Becker","background":"","created_by_user_id":64,
"updated_by_user_id":null,"created_at":"2013-06-27T06:58:07.000Z",
"updated_at":"2015-07-20T15:17:58.000Z","responsible_user_natural_name":"Axel von Leitner",
"companies":[],
"tels":[],
"emails":[{"id":4079954,"attachable_type":"Person","attachable_id":455636,
  "atype":"office","primary":null,"name":"test@test.de","name_clean":null,
  "created_at":"2015-07-20T15:17:58.000Z","updated_at":"2015-07-20T15:17:58.000Z","api_input":true}]}},

{"person":{"id":989625,"account_id":21,"user_id":2797,"title":"Herr","gender":0,
"first_name":"Carl","name":"Benz","background":"Benz ...","created_by_user_id":2797,
"updated_by_user_id":2797,"created_at":"2014-08-21T14:13:37.000Z",
"updated_at":"2015-06-03T14:21:35.000Z","responsible_user_natural_name":"Sven Sester",
"companies":[{"id":661234,"account_id":21,"user_id":2797,"name":"Benz-Cars AG",
"is_own":false,"demo":false,"created_by_user_id":null,"created_at":"2014-08-21T14:13:37.000Z",
"updated_at":"2015-03-03T11:49:08.000Z","import_log_id":null,"background":null}],
"avatar":{"uuid":"939d12b6-293d-11e4-9d83-0015174fb400","size":46024,"height":309,
  "width":220,"account_id":21,"user_id":2797,"attachable_id":989625,"position":null,
  "content_type":"image/png","filename":"220px-Carl_Benz.png","thumbnail":null,
  "parent_id":null,"attachable_type":"Person","created_at":"2014-08-21T14:15:17.000Z",
  "updated_at":"2014-08-21T14:15:17.000Z","api_input":false},
"tels":[{"id":2498039,"attachable_type":"Person","attachable_id":989625,"atype":"office",
  "primary":null,"name":"1234354567668589","name_clean":"1234354567668589",
  "created_at":"2014-08-21T14:13:37.000Z","updated_at":"2014-08-21T14:13:37.000Z","api_input":false}],
"emails":[{"id":2498038,"attachable_type":"Person","attachable_id":989625,
  "atype":"office","primary":null,"name":"carl-benz@benz-cars-ag.com","name_clean":null,
  "created_at":"2014-08-21T14:13:37.000Z","updated_at":"2014-08-21T14:13:37.000Z","api_input":false}]}},

...
]

Methods für mehr Komfort

Neben den Includes können einzelne Informationen der verschachtelten Objekte komfortabel über methods abgefragt werden. Zu vielen Objekten (z.B. Personen, Firmen, Notizen, Aufgaben) gibt es beispielsweise ein user_id Feld, welches auf den verantwortlichen oder handelnden User verweist. Um die Namen der Nutzer nicht immer separat laden zu müssen, kann dieser über die methods=responsible_user_natural_name inkludiert werden. Mit methods=all werden alle verfügbaren Methoden eingebunden.

curl -X GET https://accountname.centralstationcrm.net/api/people.json?methods=all

[
{"person":{"id":455636,"account_id":21,"user_id":64,"salutation":"",title":"",
"gender":"male_user","country_code":"",
"first_name":"Karl-Heinz","name":"Becker","background":"","created_by_user_id":64,
"updated_by_user_id":null,"created_at":"2013-06-27T08:58:07.000+02:00",
"updated_at":"2015-07-23T07:39:15.000+02:00",
"responsible_user_natural_name":"Axel von Leitner",
"salutation_official":"Sehr geehrter Herr Becker",
"salutation_formal":"Hallo Herr Becker",
"salutation_informal":"Hey Karl-Heinz",
"user":{"id":64,"first":"Axel","name":"von Leitner","login":"axel.von.leitner@42he.com"}}}]

...
]

Paginierung

Die INDEX Funktionen der Module Personen, Firmen, Angebote, Projekte usw. sind paginiert, d.h. die API liefert nicht alle Ergebnisse auf einmal zurück, sondern nur eine Teilmenge. Über den Parameter perpage und page kann entsprechend die Anzahl der Elemente pro Seite und die Seitenzahl angegeben werden. Die Anzahl aller Einträge kann über die COUNT Funktion seperat genutzt werden (s.U.)

curl -X GET https://accountname.centralstationcrm.net/api/people.json?perpage=1&page=1

[
{"person":{"id":455636,"account_id":21,"user_id":64,"title":"","gender":2,
"first_name":"Karl-Heinz","name":"Becker","background":"","created_by_user_id":64,
"updated_by_user_id":null,"created_at":"2013-06-27T06:58:07.000Z",
"updated_at":"2015-07-20T15:17:58.000Z","responsible_user_natural_name":"Axel von Leitner"}}
]

Zusätlich kann über die Funktion COUNT die Gesamtanzahl unabhängig hiervon bestimmt werden:

curl -X GET https://accountname.centralstationcrm.net/api/people/count.json

{"total_entries": 98}