Personen in CentralStationCRM

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

Bei den Personen sowie den sonstigen Objekten in CentralStationCRM stehen die folgenden Actions zur Verfügung: index, show, create, update und delete. Jede Person enthält die folgenden Felder:

Feldname Feldtyp Beschreibung
id INTEGER ID der Person (Read only)
account_id INTEGER ID des Accounts (Read only)
salutation VARCHAR(40) Anrede der Person, z.B. Frau
title VARCHAR(60) Titel der Person, z.B. Dr.
gender ENUM Geschlecht der Person (gender_unknown, male_user, female_user, male_auto, female_auto, family_user, family_auto; automatisch von uns ermittelt anhand dem Vornamen oder manuell setzbar)
country_code VARCHAR(10) Sprache der Person als iso_639_1 (z.B. de, en, fr oder nicht gesetzt. Wird genutzt, um Anreden zu generieren Dear Mr Miller, Sehr geehrter Herr Miller)
first_name VARCHAR(60) Vorname der Person
name VARCHAR(80) Nachname der Person (Pflichtfeld)
background TEXT Hintergrundinformationen zur Person
user_id INTEGER ID des Users, wenn die Person zu einem User gehört (Read only)
created_at TIMESTAMP Zeitpunkt der Erstellung (automatisch gesetzt, read only)
updated_at TIMESTAMP Zeitpunkt des letzten Updates (automatisch gesetzt, read only)

Methods

Über methods können folgende Daten abgefragt 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"}}}]

...
]

Personen verfügen außerdem über verschachtelte Routen. Ein Aufruf dieser Ressourcen erfolgt, wie in dem kommenden Beispiel beschrieben.


Beispiel für verschachtelte Routen

https://api.centralstationcrm.net/api/people/1548463/tags.json?apikey=htgjst7dgk9q2dst


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

[
{"tag":{"id":4671801,"account_id":21,"attachable_id":1485431,"attachable_type":"Person",
"name":"&Interessent","created_at":"2015-06-11T14:14:09.000Z",
"updated_at":"2015-06-11T14:14:09.000Z","api_input":false,
"attachable":{"id":1485431,"account_id":21,"user_id":2797,"own_user_id":null,
"title":"Herr","gender":0,"first_name":"Daniel","name":"Düsentrieb",
"background":"Dynamischer Herr ...",
"import_log_id":null,"demo":false,"created_by_user_id":2797,"updated_by_user_id":2797,
"created_at":"2015-06-11T14:12:35.000Z","updated_at":"2015-06-11T14:28:00.000Z"}}},

{"tag":{"id":4671800,"account_id":21,"attachable_id":1485431,"attachable_type":"Person",
"name":"Automobil","created_at":"2015-06-11T14:14:05.000Z",
"updated_at":"2015-06-11T14:14:05.000Z","api_input":false,
"attachable":{"id":1485431,"account_id":21,"user_id":2797,"own_user_id":null,
"title":"Herr","gender":0,"first_name":"Daniel","name":"Düsentrieb",
"background":"Dynamischer Herr ...",
"import_log_id":null,"demo":false,"created_by_user_id":2797,"updated_by_user_id":2797,
"created_at":"2015-06-11T14:12:35.000Z","updated_at":"2015-06-11T14:28:00.000Z"}}}
]

Action: Index

GET /people.json
Mit der Index Action kann eine Liste aller Personen in einem Account abgefragt werden. Als Default werden immer 25 Elemente ausgegeben. Die Zahl der Elemente pro Seite / Request kann über den Parameter perpage verändert werden (Maximum: 500 / Seite). Durch Angabe des Parameters page (z.B. page=2) kann die Seitenzahl angegeben werden.

Sortierung
Die Sortierung kann mit dem Parameter order beeinflusst werden. Möglich sind zum Beispiel "created_at-asc" (Erstellzeitpunkt), "activity-asc" (letzte Aktivität im Verlauf der Seite) oder "updated_at-desc" (letzte Bearbeitung). Wenn das order Statement übergeben wird, sollte sowohl das Sortierkriterium, als auch die Sortierrichtung (asc oder desc) übergeben werden, da wir je nach Kriterium unterschiedliche Standard-Sortierungen wählen (zB. aufsteigend bei der Sortierung nach Alphabet und absteigend bei der Sortierung nach dem Erstelldatum). Standard ist "name-asc", also asc (aufsteigend) nach name (Alphabet).

Verschachtelte Unterobjekte (optional)
Bei dem Aufruf der Index Funktion können die Unterobjekte über den includes Parameter im Format includes:'positions tags' direkt mit ausgeliefert werden. Mögliche Optionen sind: positions companies tags avatar tels emails homepages addrs custom_fields connections. Um alle genannten Optionen zu bekommen kann includes:'all' gesetzt werden.

Methods (optional)
Über den methods Parameter können einzelne Daten direkt in den JSON Hash eingebunden werden. Möglich ist methods=responsible_user_natural_name für den vollen Namen des verantwortlichen Nutzers.

Einschränkung nach beliebigem Feld (optional)
Die Liste der Personen kann nach jedem der Personenfelder eingeschränkt werden. URL-Beispiele für die filter Parameter sind:

Einschränkung auf einzelne Angebote/Projekte oder Tags (optional)
Durch Übergabe des Parameters deal_id oder project_id können alle Objekte in dem jeweiligen Angebot oder Projekt abgefragt werden.
Durch Übergabe des Parameters tag_id können alle Objekte mit dem gleichen Namen des jeweiligen Tags abgefragt werden. Bei Übergabe des tag_name werden alle Objekte zurückgegeben, die mit dem entsprechenden Tag versehen sind.

Einschränkung nach dem Inhalt von individuellen Feldern (optional)
Die Liste kann anhand eines individuellen Felds eingeschränkt werden. Um die Filterung nach einem individuellen Feld durchzuführen können folgende Formate übergeben werden:
Übergabe der CustomFieldType ID sowie dem Wert, den das Feld enthalten soll:
custom_fields: {'custom_field_type_id' => '1', 'value' => '12345'}
Bsp. URL: /api/people.json?custom_fields[custom_field_type_id]=3&custom_fields[value]=0815

Übergabe des CustomFieldType Name sowie dem Wert, den das Feld enthalten soll:
custom_fields: {'custom_field_type_name' => 'kundennummer', 'value' => '0815'}
Bsp. URL: /api/people.json?custom_fields[custom_field_type_name]=kundennummer&custom_fields[value]=0815

Übergabe der CustomFieldType ID sowie des Wertes in Hash Form (für die Einschränkung nach mehreren CustomFieldTypes):
custom_fields: {'3' => '0815', '5' => 'meinWert', 'CustomFieldTypeID' => 'Suchwert'}
Bsp. URL: /api/people.json?custom_fields[3]=0815&custom_fields[5]=meinWert

Einschränkung auf die beobachteten Einträge eines speziellen Nutzers (optional)
Die Liste kann mit dem Parameter observer_user_id (z.B. observer_user_id=42) so eingeschränkt werden, dass nur die Einträge ausgegeben werden, die von dem angegebenen Benutzer beobachtet werden. Wird der Parameter übergeben, aber keine User ID übergeben, dann wird der Benutzer des API Schlüssels genommen.

Beispiel für einen allgemeinen Aufruf ohne Einschränkung
curl -X GET https://accountname.centralstationcrm.net/api/people.json

[
{"person":{"id":455637,"account_id":21,"user_id":64,"title":"","gender":3,
"first_name":"Marion","name":"Beber","background":"","created_by_user_id":64,
"updated_by_user_id":2797,"created_at":"2013-06-27T06:58:14.000Z",
"updated_at":"2015-05-21T14:06:00.000Z","responsible_user_natural_name":"Axel von Leitner"}},

{"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-04-27T09:17:00.000Z","responsible_user_natural_name":"Axel von Leitner"}}

...
]

Action: Show

GET /people/{id}.json
Eine einzelne Person kann mit der show Action geladen werden. Voraussetzung hierfür ist eine für den Account gültige Personen ID.

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

{"person":{"id":455637,"account_id":21,"user_id":64,"title":"","gender":3,
"first_name":"Marion","name":"Beber","background":"","created_by_user_id":64,
"updated_by_user_id":2797,"created_at":"2013-06-27T06:58:14.000Z",
"updated_at":"2015-05-21T14:06:00.000Z","responsible_user_natural_name":"Axel von Leitner"}}
Beispiel mit Tags
curl -X GET https://accountname.centralstationcrm.net/api/people/:person_id.json?includes=tags

{"person":{"id":455637,"account_id":21,"user_id":64,"title":"","gender":3,
    "first_name":"Marion","name":"Beber","background":"","created_by_user_id":64,
    "updated_by_user_id":2797,"created_at":"2013-06-27T06:58:14.000Z",
    "updated_at":"2015-05-21T14:06:00.000Z","responsible_user_natural_name":"Axel von Leitner",
    "tags":[
      {"id":1186622,"account_id":21,"attachable_id":455637,"attachable_type":"Person",
        "name":"&Interessent","created_at":"2013-07-08T14:01:17.000Z",
        "updated_at":"2013-07-08T14:01:17.000Z","api_input":false},
      {"id":4288723,"account_id":21,"attachable_id":455637,"attachable_type":"Person",
        "name":"Automobilmesse","created_at":"2015-04-24T17:16:34.000Z",
        "updated_at":"2015-04-24T17:17:28.000Z","api_input":false},
      {"id":1186628,"account_id":21,"attachable_id":455637,"attachable_type":"Person",
        "name":"CentralPlanner","created_at":"2013-07-08T14:03:31.000Z",
        "updated_at":"2013-07-08T14:03:31.000Z","api_input":false}
      ]
}}

Action: Create

POST /people.json
Eine neue Person kann mit der Action create angelegt werden. Im positiven Fall liefert das System die neue Person zurück. Zum Anlegen einer neuen Person ist die Übergabe des Nachnamens Pflicht. Wenn der Eintrag nicht erstellt werden konnte, weil der Account nicht mehr über ausreichenden Speicherplatz für Kontakte verfügt geben wir einen 507 Insufficient Storage zurück.

Beispiel
curl -v -H "Accept: application/json" -H "Content-type: application/json" 
-X POST -d '{"person":{"first_name":"Marian","name":"Miller"}}'  
https://accountname.centralstationcrm.net/api/people.json 

{"person":{"id":1545412,"account_id":21,"user_id":null,"title":null,"gender":2,
"first_name":"Marian","name":"Miller","background":null,"created_by_user_id":1781,
"updated_by_user_id":null,
"created_at":"2015-07-20T13:26:42.190Z","updated_at":"2015-07-20T13:26:42.190Z"}}

Der Einfachheit halber können viele Daten direkt beim erstellen der Person mit geschickt werden. Hier ein Beispiel mit dem direkt Telefonnummern, Firmen, E-Mail Adressen, Homepages, Instant Messenger, Twitter Accounts, sonstige Social Media Anbieter, Assistenten, wichtige Daten oder individuelle Felder angelegt werden können.

Beispiel
curl -v -H "Accept: application/json" -H "Content-type: application/json"
-X POST -d '{"person"=>{"title"=>"Herr", "first_name"=>"Vorname", "name"=>"Nachname 1a", 
  "positions_attributes"=>{"0"=>{"id"=>"", "company_id"=>"", "company_name"=>"firma name", 
    "name"=>"firma position", "department"=>"Bereich", "primary_function"=>"true", 
    "former"=>"false", "account_id"=>19}}, 
  "tags_attributes"=>{"0"=>{"id"=>"", "name"=>"fantastic tag"}}, 
  "tels_attributes"=>{"0"=>{"id"=>"", "name"=>"1234", "atype"=>"office"}}, 
  "emails_attributes"=>{"0"=>{"id"=>"", "name"=>"jolly@42he.com", "atype"=>"office"}}, 
  "homepages_attributes"=>{"0"=>{"id"=>"", "name"=>"42he.com", "atype"=>"office"}}, 
  "addrs_attributes"=>{"0"=>{"id"=>"", "street"=>"Marktstraße 10", "zip"=>"50968", 
  "city"=>"Köln", "country"=>"Deutschland", "atype"=>"work_hq", "move_addr_id"=>""}}, 
  "ims_attributes"=>{"0"=>{"id"=>"", "name"=>"centralstationcrm", "atype"=>"skype"}}, 
  "tweets_attributes"=>{"0"=>{"id"=>"", "name"=>"cscrm", "atype"=>"twitter"}}, 
  "sms_attributes"=>{"0"=>{"id"=>"", "name"=>"xing-link", "atype"=>"xing"}}, 
  "assis_attributes"=>
    {"0"=>{"id"=>"", "name"=>"Jolly Mäh", "tel"=>"1298034", "email"=>"jolly.assistent@42he.com"}}, 
  "historic_events_attributes"=>
    {"0"=>{"id"=>"", "unparsed_date"=>"14.04.1980", "atype"=>"birthday", "desc"=>""}}, 
  "custom_fields_attributes"=>
    {"0"=>{"custom_fields_type_id"=>1, "attachable_id"=>"", 
    "attachable_type"=>"Person", "name"=>"individuelles Feld"}}}}'
https://centralstationcrm.net/api/people
Hinweis: Das System legt automatisch einen Eintrag für den Verlauf bei create, update und destroy an. Bei Massenimporten sollte dieses nicht gemacht werden. Dieses kann durch mitsenden des Parameters "no_log" erreicht werden.

Action: Update

PUT /people/{id}.json
Analog zur Create Action funktioniert das Update. Hierzu ist das Verb PUT erforderlich und die Route muss die ID des zu bearbeitenden Elementes erhalten. Die Rückgabe ist hier nicht das Element selber, sondern der Header :ok mit dem HTTP Code 200.

Beispiel
curl -v -H "Accept: application/json" -H "Content-type: application/json" 
-X PUT -d ' {"person":{"name":"Miller Nr 2"}}'
https://accountname.centralstationcrm.net/api/people/:person_id.json 

Status: 200 OK

Action: Delete

DELETE /people/{id}.json
Zum Löschen eines Elementes muss man dieses über seine Route mit dem Verb DELETE ansprechen. Auch ist hier die Rückgabe der HTTP Code 200 mit dem Header :ok.

Beispiel
curl -X DELETE https://accountname.centralstationcrm.net/api/people/{id}.json

Status: 200 OK

Personen Sonderfunktionen

Action: Search

GET /people/search.json?name=Mäh
Um nach einer oder mehreren Personen zu suchen können die Parameter name, first_name, phone oder email übergeben werden. Wenn ein oder mehrere Treffer gefunden wurden erfolgt die Rückgabe in gleicher Form, wie bei der Index Funktion. Wenn keine Treffer gefunden wurden geben wir einen leeren Array zurück.

Beispiel
curl -X GET https://accountname.centralstationcrm.net/api/people/search.json?name=Mäh

[
{"person":{"id":235321,"account_id":21,"user_id":1781,"title":"","gender":null,
"first_name":"Jolly","name":"Mäh","background":"","created_by_user_id":null,
"updated_by_user_id":2797,"created_at":"2012-07-12T11:13:19.000Z",
"updated_at":"2015-01-13T11:08:08.000Z"}}
]

Action: Stats

GET /people/stats.json
Über die stats können reine Count oder Summenberechnungen für alle oder gefilterte Personen abgefragt werden. Die Personen können wie die index action gefiltert werden, also nach Tags oder beliebigen Feldern. total_entries enthält die absolute Zahl der Personen.

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

{
total_entries: 40
}

Action: Merge

POST /people/:id/merge.json?looser_ids=x,y,z
Über die merge Funktion können mehrere Personen zusammengeführt werden. Die als looser_ids übergebenen Personen IDs werden dabei mit der als id übergebenen Person zusammengeführt. Die Logik gleicht dabei einer Zusammenführung über die CentralStationCRM Oberfläche.

Beispiel
curl -v -H "Accept: application/json" -H "Content-type: application/json" 
-X POST -d '{"id": 1, "looser_ids": ['5', '10', '100']}'  
https://accountname.centralstationcrm.net/api/people/:id/merge.json?looser_ids=5,10,100

Status: 200 OK