Firmen 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

Firmen verhalten sich von den Actions (index, show, create, update, delete) her wie die Personen. Die Dokumentation zu den Actions der Personen ist ausführlicher und enthält einige Beispiele. Es stehen folgende Felder zur Verfügung:

Feldname Feldtyp Beschreibung
id INTEGER ID der Firma (Read only)
account_id INTEGER ID des Accounts (Read only)
name VARCHAR(120) Name der Firma (Pflichtfeld)
background TEXT Hintergrundinformationen zur Firma
created_at TIMESTAMP Zeitpunkt der Erstellung (automatisch gesetzt, read only)
updated_at TIMESTAMP Zeitpunkt des letzten Updates (automatisch gesetzt, read only)

Firmen verfügen außerdem über die gleichen verschachtelten Routen, wie die Personen. Der Aufruf wird bei den Personen beispielhaft beschrieben.

Der Einfachheit halber können viele Daten direkt beim erstellen der Firma mit geschickt werden. Dazu gehören Telefonnummern, E-Mail Adressen, Homepages, Instant Messenger, Twitter Accounts, sonstige Social Media Anbieter und individuelle Felder. Das funktioniert dann analog zum Anlegen einer Person.

Action: Index

GET /companies.json
Mit der Index Action kann eine Liste aller Firmen 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 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 Firmen kann nach jedem der Felder eingeschränkt werden. URL-Beispiele für die filter Parameter sind:

Einschränkung nach Tags (optional)
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.

Firmen Sonderfunktionen

Action: Search

GET /companies/search.json?name=42he
Um nach einer oder mehreren Firmen zu suchen muss der Parameter name ü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/companies/search.json?name=42he

[
{"company":{"id":844858,"account_id":21,"name":"42he GmbH","created_by_user_id":null,
"created_at":"2015-02-05T15:50:38.000Z",
"updated_at":"2015-04-15T06:58:22.000Z","background":""}},

{"company":{"id":171236,"account_id":21,"name":"42he Unternehmergesellschaft (haftungsbeschränkt)",
"created_by_user_id":null,"created_at":"2012-09-21T13:26:19.000Z",
"updated_at":"2014-03-01T10:21:30.000Z","background":null}}

...
]

Action: Stats

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

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

{
total_entries: 100
}

Action: Merge

POST /companies/:id/merge.json?looser_ids=x,y,z
Über die merge Funktion können mehrere Firmen zusammengeführt werden. Die als looser_ids übergebenen Firmen IDs werden dabei mit der als id übergebenen Firma 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/companies/:id/merge.json?looser_ids=5,10,100

Status: 200 OK