Kontakte in CentralPlanner

API Navigation

Allgemeines: Grundlagen Authentifizierung Fehlerbehandlung Datenstruktur

Hauptmodelle: Kontakte Reservierungen

Sonstiges: Schlagwörter

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

Feldname Feldtyp Beschreibung
id INTEGER ID des Kontaktes (Read only)
account_id INTEGER ID des Accounts (Read only)
title VARCHAR(50) Titel / Anrede der Person
first VARCHAR(100) Vorname der Person
last VARCHAR(100) Nachname der Person (Pflichtfeld)
note TEXT Hintergrundinformationen / Notizen zum Kontakt
phone VARCHAR(80) Telefonnummer
phone2 VARCHAR(80) Zweite Telefonnummer (mobil)
mail VARCHAR(80) E-Mail Adresse
company VARCHAR(100) Firmenname
street VARCHAR(100) Straße und Hausnummer
zip VARCHAR(10) Postleitzahl
city VARCHAR(80) Stadt / Ort
newsletter VARCHAR(20) Newsletter Status - 'not_subscribed', 'subscribed', 'waiting_for_opt_in', 'bounced' & 'unsubscribed'
created_at TIMESTAMP Zeitpunkt der Erstellung (automatisch gesetzt, read only)
updated_at TIMESTAMP Zeitpunkt des letzten Updates (automatisch gesetzt, read only)

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


Beispiel für verschachtelte Routen
curl https://centralplanner.net/api/contacts/xx/bookings 
-H 'Authorization: Token token="my-api-token"'

[{
    "id": 222,
    "account_id": 8,
    "area_id": 14,
    "contact_id": 187,
    "date": "2011-06-17",
    "hour": 16,
    "minute": 30,
    "number_guests": 6,
    "note": "Frau Bachmann möchte gerne einen Tisch am Fenster",
    "created_by_user_id": null,
    "duration": 90,
    "mail_confirmation": false,
    "created_at": "2011-06-15T09:41:58.000+02:00",
    "updated_at": "2011-06-15T10:37:23.000+02:00",
    "status": "accepted",
    "webform": false,
    "contact": {
        "id": 187,
        "account_id": 8,
        "completed_bookings_count": 12,
        "title": "Frau",
        "first": "Stefanie",
        "last": "Dachmann",
        "note": "Kommt regelmäßig zum A la Carte Essen.",
        "phone": "006074-3000098",
        "phone_clean": "0060743000098",
        "phone2": "",
        "phone2_clean": "",
        "mail": "stefanie.bachmann@example.com",
        "company": null,
        "street": "",
        "zip": null,
        "city": "Vorstätten",
        "newsletter": false,
        "newsletter_double_opt_in_hash": null,
        "created_at": "2011-06-15T09:39:56.000+02:00",
        "updated_at": "2013-05-15T16:56:24.000+02:00",
        "import_id": null,
        "deleted_at": null
    }
}]

Action: Index

GET /api/contacts.json
Mit der Index Action kann eine Liste aller Kontakte in einem Account abgefragt werden. Als Default werden immer 50 Elemente ausgegeben. Die Zahl der Elemente pro Seite / Request kann über den Parameter perpage verändert werden. Durch Angabe des Parameters page (z.B. page=2) kann die Seitenzahl angegeben werden. Die Sortierung kann mit dem Parameter order beeinflusst werden. Möglich sind zum Beispiel "created-at-asc" für absteigend nach Erstellungsdatum. Wenn das order Statement übergeben wird, ist die Sortierreihenfolge (asc, desc) eine Pflichtangabe. Sortiert werden kann nach created_at (Erstellungsdatum), updated_at (Bearbeitungsdatum) oder name (Alphabetisch). Standard ist asc (aufsteigend) nach name (Alphabet).

Die Kontakte können so eingeschränkt werden, dass nur diejenigen mit einer E-Mail Adresse ausgegeben werden. Wenn der Parameter only_with_mail auf true gesetzt wird, dann werden ausschließlich diese Kontakte ausgegeben. Bei der Übergabe des Parameters only_with_newsletter werden nur die Kontakte übergeben, die eine E-Mail Adresse haben und dem Empfang eines Newsletters zugestimmt haben.

Weiterhin können die Schlagworte der Kontakte direkt mit übergeben werden, indem der Parameter include_tags auf true gesetzt wird. In dem Fall werden die Schlagwörter des Kontaktes am Ende des JSON Objektes übergeben. Wenn keine Schlagworte vorhanden sind, dann wird ein leerer Array übergeben.

Beispiel
curl https://centralplanner.net/api/contacts
-H 'Authorization: Token token="my-api-token"'

[{
    "id": 187,
    "account_id": 8,
    "completed_bookings_count": 12,
    "title": "Frau",
    "first": "Stefanie",
    "last": "Dachmann",
    "note": "Kommt regelmäßig zum A la Carte Essen.",
    "phone": "006074-3000098",
    "phone2": "",
    "mail": "stefanie.bachmann@example.com",
    "company": null,
    "street": "",
    "zip": null,
    "city": "Vorstätten",
    "newsletter": false,
    "created_at": "2011-06-15T09:39:56.000+02:00",
    "updated_at": "2013-05-15T16:56:24.000+02:00"
}, ...]

Action: Show

GET /api/contacts/{id}
Ein einzelner Kontakt kann mit der show Action geladen werden. Voraussetzung hierfür ist eine für den Account gültige Kontakt ID.

Beispiel
curl https://centralplanner.net/api/contacts/187
-H 'Authorization: Token token="my-api-token"'

{
    "id": 187,
    "account_id": 8,
    "completed_bookings_count": 12,
    "title": "Frau",
    "first": "Stefanie",
    "last": "Dachmann",
    "note": "Kommt regelmäßig zum A la Carte Essen.",
    "phone": "006074-3000098",
    "phone2": "",
    "mail": "stefanie.bachmann@example.com",
    "company": null,
    "street": "",
    "zip": null,
    "city": "Vorstätten",
    "newsletter": false,
    "created_at": "2011-06-15T09:39:56.000+02:00",
    "updated_at": "2013-05-15T16:56:24.000+02:00"
}

Action: Create

POST /api/contacts.json
Eine neue Kontakt kann mit der Action create angelegt werden. Im positiven Fall liefert das System die neue Kontakt zurück. Zum Anlegen einer neuen Kontakt ist die Übergabe des Nachnamens Pflicht.

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. Dann wird kein Eintrag in den Verlauf geschrieben. Beispiel
curl -v -H "Content-type: application/json" 
-H 'Authorization: Token token="my-api-token"' 
-X POST https://centralplanner.net/api/contacts 
-d '{"contact":{"last":"Mein Nachname"} }'

{
    "id": 173009,
    "account_id": 8,
    "completed_bookings_count": 0,
    "title": null,
    "first": null,
    "last": "Mein Nachname",
    "note": null,
    "phone": null,
    "phone2": null,
    "mail": null,
    "company": null,
    "street": null,
    "zip": null,
    "city": null,
    "newsletter": false,
    "created_at": "2014-07-11T12:17:32.022+02:00",
    "updated_at": "2014-07-11T12:17:32.022+02:00"
}

Action: Update

PUT /api/contacts/{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 "Content-type: application/json" 
-H 'Authorization: Token token="mein-api-key"' 
-X PUT https://centralplanner.net/api/contacts/173009 
-d '{"contact":{"last":"Mein neuer Nachname"} }'

Status: 200 OK

Action: Delete

DELETE /api/contacts/{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 -v -H "Content-type: application/json" 
-H 'Authorization: Token token="my-api-key"' 
-X DELETE https://centralplanner.net/api/contacts/173009 

Status: 200 OK

Sonderfunktionen der Kontakte

Action: Search

GET /api/contacts/search.json?last=Dachmann
Um nach einer oder mehreren Kontakten zu suchen, können die Parameter first, last, phone, mail und/oder company übergeben werden. Wenn einer 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 "https://centralplanner.net/api/contacts/search?last=Dachmann" 
-H 'Authorization: Token token="my-api-key"'

[{
    "id": 187,
    "account_id": 8,
    "completed_bookings_count": 12,
    "title": "Frau",
    "first": "Stefanie",
    "last": "Dachmann",
    "note": "Kommt regelmäßig zum A la Carte Essen.",
    "phone": "006074-3000098",
    "phone2": "",
    "mail": "stefanie.bachmann@example.com",
    "company": null,
    "street": "",
    "zip": null,
    "city": "Vorstätten",
    "newsletter": false,
    "created_at": "2011-06-15T09:39:56.000+02:00",
    "updated_at": "2013-05-15T16:56:24.000+02:00"
}, ...]