Contacts API

Contacts (Kontakte) ermöglichen es Ihnen, Ansprechpersonen für Ihre Kunden zu verwalten. Jeder Contact gehört zu einem Customer und kann als primärer Kontakt markiert werden. Contacts werden automatisch bei der Erstellung von Customers angelegt oder können separat verwaltet werden.

Hinweis: Contact-Erstellung

Neue Contacts werden primär über die Customers API erstellt, indem Sie beim Erstellen eines Customers das contact_name Feld verwenden. Dieser Endpoint dient der Verwaltung bestehender Contacts.

Contact-Objekt

json

{
  "data": {
    "id": 175,
    "company_id": 123,
    "customer_id": 410,
    "user_id": 456,
    "name": "Max Muster",
    "email": "max.muster@example.com",
    "phone": "+41 44 123 45 67",
    "greeting": "Herr",
    "is_primary": true,
    "archived": false,
    "created_at": "2024-12-04T17:11:06.000000Z",
    "updated_at": "2024-12-04T17:11:06.000000Z"
  }
}

Attribute

Feld	Typ	Beschreibung
`id`	integer	Eindeutige Contact-ID
`company_id`	integer	ID der zugehörigen Firma
`customer_id`	integer	ID des zugehörigen Customers
`user_id`	integer	ID des Benutzers, der den Contact erstellt hat
`name`	string	Name des Kontakts (erforderlich)
`email`	string\|null	E-Mail-Adresse
`phone`	string\|null	Telefonnummer
`greeting`	string\|null	Anrede (z.B. "Herr", "Frau", "Herr Dr.")
`is_primary`	boolean	Ob dies der Hauptkontakt für den Customer ist
`archived`	boolean	Ob der Contact archiviert ist
`created_at`	datetime	Erstellungsdatum
`updated_at`	datetime	Datum der letzten Aktualisierung

Endpoints

Alle Contacts auflisten

http

GET /companies/{company}/contacts

Ruft eine paginierte Liste aller Contacts der Firma ab.

Parameter

Parameter	Typ	Standard	Beschreibung
`page`	integer	1	Seitennummer
`per_page`	integer	15	Anzahl Contacts pro Seite (max. 100)
`filter[customer_id]`	integer	-	Filtern nach spezifischem Customer (exakte Übereinstimmung)
`filter[archived]`	boolean	-	Filtern nach Archivierungsstatus (exakte Übereinstimmung)
`include`	string	-	Zugehörige Daten laden: `customer` (kommagetrennt)

Response

json

{
  "data": [
    {
      "id": 175,
      "company_id": 123,
      "customer_id": 410,
      "user_id": 456,
      "name": "Max Muster",
      "email": "max.muster@example.com",
      "phone": "+41 44 123 45 67",
      "greeting": "Herr",
      "is_primary": true,
      "archived": false,
      "created_at": "2024-12-04T17:11:06.000000Z",
      "updated_at": "2024-12-04T17:11:06.000000Z"
    },
    {
      "id": 176,
      "company_id": 123,
      "customer_id": 410,
      "user_id": 456,
      "name": "Anna Beispiel",
      "email": "anna.beispiel@example.com",
      "phone": "+41 44 987 65 43",
      "greeting": "Frau",
      "is_primary": false,
      "archived": false,
      "created_at": "2024-12-05T09:30:00.000000Z",
      "updated_at": "2024-12-05T09:30:00.000000Z"
    }
  ],
  "links": {
    "first": "https://app.milkee.ch/api/v2/companies/123/contacts?page=1",
    "last": "https://app.milkee.ch/api/v2/companies/123/contacts?page=5",
    "prev": null,
    "next": "https://app.milkee.ch/api/v2/companies/123/contacts?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 5,
    "path": "https://app.milkee.ch/api/v2/companies/123/contacts",
    "per_page": 15,
    "to": 15,
    "total": 67
  }
}

Beispiele

bash

# Alle Contacts abrufen
curl -H "Authorization: Bearer 1|abcdef123456789..." \
     "https://app.milkee.ch/api/v2/companies/123/contacts"

# Contacts eines bestimmten Customers
curl -H "Authorization: Bearer 1|abcdef123456789..." \
     "https://app.milkee.ch/api/v2/companies/123/contacts?filter[customer_id]=410"

# Nur aktive Contacts
curl -H "Authorization: Bearer 1|abcdef123456789..." \
     "https://app.milkee.ch/api/v2/companies/123/contacts?filter[archived]=false"

# Mit Customer-Daten
curl -H "Authorization: Bearer 1|abcdef123456789..." \
     "https://app.milkee.ch/api/v2/companies/123/contacts?include=customer"

Einzelnen Contact abrufen

http

GET /companies/{company}/contacts/{contact}

Ruft die Details eines spezifischen Contacts ab.

Parameter

Parameter	Typ	Beschreibung
`company`	integer	Firmen-ID
`contact`	integer	Contact-ID
`include`	string	Zugehörige Daten laden: `customer` (kommagetrennt)

Response

json

{
  "data": {
    "id": 175,
    "company_id": 123,
    "customer_id": 410,
    "user_id": 456,
    "name": "Max Muster",
    "email": "max.muster@example.com",
    "phone": "+41 44 123 45 67",
    "greeting": "Herr",
    "is_primary": true,
    "archived": false,
    "created_at": "2024-12-04T17:11:06.000000Z",
    "updated_at": "2024-12-04T17:11:06.000000Z",
    "customer": {
      "id": 410,
      "name": "Muster AG",
      "number": 1001,
      "email": "info@muster.ch"
    }
  }
}

Beispiele

bash

# Contact abrufen
curl -H "Authorization: Bearer 1|abcdef123456789..." \
     "https://app.milkee.ch/api/v2/companies/123/contacts/175"

# Mit Customer-Daten
curl -H "Authorization: Bearer 1|abcdef123456789..." \
     "https://app.milkee.ch/api/v2/companies/123/contacts/175?include=customer"

Contact aktualisieren

http

PUT /companies/{company}/contacts/{contact}

Aktualisiert einen bestehenden Contact.

Request Body

json

{
  "name": "Max Muster",
  "email": "max.muster@muster-ag.ch",
  "phone": "+41 44 123 45 67",
  "greeting": "Herr Dr.",
  "is_primary": true,
  "archived": false
}

Validierung

Feld	Regeln
`name`	`sometimes`, `required`, `string`, `max:255`
`email`	`nullable`, `email`, `max:255`
`phone`	`nullable`, `string`, `max:255`
`greeting`	`nullable`, `string`, `max:255`
`is_primary`	`sometimes`, `boolean`
`archived`	`sometimes`, `boolean`

Besonderheiten

Primärkontakt: Wenn is_primary=true gesetzt wird, werden automatisch alle anderen Contacts des gleichen Customers als nicht-primär markiert
Teilweises Update: Alle Felder sind optional, nur die übermittelten Felder werden aktualisiert

Response

json

{
  "data": {
    "id": 175,
    "company_id": 123,
    "customer_id": 410,
    "user_id": 456,
    "name": "Max Muster",
    "email": "max.muster@muster-ag.ch",
    "phone": "+41 44 123 45 67",
    "greeting": "Herr Dr.",
    "is_primary": true,
    "archived": false,
    "created_at": "2024-12-04T17:11:06.000000Z",
    "updated_at": "2025-01-14T15:45:00.000000Z"
  }
}

Beispiele

bash

# Contact aktualisieren
curl -X PUT \
     -H "Authorization: Bearer 1|abcdef123456789..." \
     -H "Content-Type: application/json" \
     -d '{
       "name": "Max Muster",
       "email": "max.muster@muster-ag.ch",
       "greeting": "Herr Dr."
     }' \
     "https://app.milkee.ch/api/v2/companies/123/contacts/175"

# Als primären Contact markieren
curl -X PUT \
     -H "Authorization: Bearer 1|abcdef123456789..." \
     -H "Content-Type: application/json" \
     -d '{"is_primary": true}' \
     "https://app.milkee.ch/api/v2/companies/123/contacts/175"

# Contact archivieren
curl -X PUT \
     -H "Authorization: Bearer 1|abcdef123456789..." \
     -H "Content-Type: application/json" \
     -d '{"archived": true}' \
     "https://app.milkee.ch/api/v2/companies/123/contacts/175"

Contact löschen

http

DELETE /companies/{company}/contacts/{contact}

Löscht einen bestehenden Contact unwiderruflich.

Löschbedingungen

Ein Contact kann nur gelöscht werden, wenn:

Keine Rechnungen mit dem Contact verknüpft sind
Keine Offerten mit dem Contact verknüpft sind

Andernfalls wird ein 409-Fehler zurückgegeben.

Response

http

HTTP/1.1 204 No Content

Beispiel

bash

curl -X DELETE \
     -H "Authorization: Bearer 1|abcdef123456789..." \
     "https://app.milkee.ch/api/v2/companies/123/contacts/176"

Mehrere Contacts archivieren/dearchivieren

http

POST /companies/{company}/contacts/multiple

Archiviert oder dearchiviert mehrere Contacts gleichzeitig.

Request Body

json

{
  "ids": [175, 176, 177],
  "archive": true
}

Feld	Typ	Beschreibung
`ids`	array\|integer	Array von Contact-IDs oder einzelne ID
`archive`	boolean	`true` zum Archivieren, `false` zum Dearchivieren (Standard: `true`)

Response

http

HTTP/1.1 204 No Content

Beispiele

bash

# Mehrere Contacts archivieren
curl -X POST \
     -H "Authorization: Bearer 1|abcdef123456789..." \
     -H "Content-Type: application/json" \
     -d '{
       "ids": [175, 176, 177],
       "archive": true
     }' \
     "https://app.milkee.ch/api/v2/companies/123/contacts/multiple"

# Mehrere Contacts dearchivieren
curl -X POST \
     -H "Authorization: Bearer 1|abcdef123456789..." \
     -H "Content-Type: application/json" \
     -d '{
       "ids": [175, 176, 177],
       "archive": false
     }' \
     "https://app.milkee.ch/api/v2/companies/123/contacts/multiple"

# Einzelnen Contact archivieren
curl -X POST \
     -H "Authorization: Bearer 1|abcdef123456789..." \
     -H "Content-Type: application/json" \
     -d '{
       "ids": 175,
       "archive": true
     }' \
     "https://app.milkee.ch/api/v2/companies/123/contacts/multiple"

Mehrere Contacts löschen

http

DELETE /companies/{company}/contacts/multiple

Löscht mehrere Contacts gleichzeitig.

Sicheres Löschen

Contacts mit verknüpften Rechnungen oder Offerten werden automatisch übersprungen und nicht gelöscht. Der Vorgang schlägt nicht fehl, sondern löscht nur die Contacts ohne Verknüpfungen.

Request Body

json

{
  "ids": [175, 176, 177]
}

Feld	Typ	Beschreibung
`ids`	array\|integer	Array von Contact-IDs oder einzelne ID

Response

http

HTTP/1.1 204 No Content

Beispiel

bash

curl -X DELETE \
     -H "Authorization: Bearer 1|abcdef123456789..." \
     -H "Content-Type: application/json" \
     -d '{"ids": [176, 177, 178]}' \
     "https://app.milkee.ch/api/v2/companies/123/contacts/multiple"

Fehlerbehandlung

Häufige Fehler

409 Conflict - Contact hat Rechnungen/Offerten

json

{
  "message": "Dieser Kontakt hat Rechnungen oder Offerten und kann daher nicht gelöscht werden."
}

Ursache: Contact ist mit Rechnungen oder Offerten verknüpft und kann nicht gelöscht werden.

Lösung: Archivieren Sie den Contact stattdessen:

bash

curl -X PUT \
     -H "Authorization: Bearer 1|abcdef123456789..." \
     -H "Content-Type: application/json" \
     -d '{"archived": true}' \
     "https://app.milkee.ch/api/v2/companies/123/contacts/175"

422 Validation Error

json

{
  "message": "The given data was invalid.",
  "errors": {
    "name": [
      "Name für Kontakt fehlt."
    ],
    "email": [
      "E-Mail-Adresse ist nicht gültig."
    ]
  }
}

Häufige Validierungsfehler:

name.required: Name ist erforderlich
name.max: Name zu lang (maximal 255 Zeichen)
email.email: Ungültige E-Mail-Adresse
email.max: E-Mail zu lang (maximal 255 Zeichen)
phone.max: Telefonnummer zu lang (maximal 255 Zeichen)
greeting.max: Anrede zu lang (maximal 255 Zeichen)
is_primary.boolean: is_primary muss true oder false sein
archived.boolean: archived muss true oder false sein

Best Practices

Primärkontakt-Verwaltung

Stellen Sie sicher, dass jeder Customer immer einen primären Contact hat. Wenn kein primärer Contact existiert, sollte der erste verfügbare Contact als primär markiert werden.

Archivierung statt Löschung

Verwenden Sie Archivierung statt Löschung für bessere Datenintegrität. Wenn ein Contact Rechnungen oder Offerten hat und nicht gelöscht werden kann (409-Fehler), archivieren Sie ihn stattdessen.

Bulk-Operationen effizient nutzen

Nutzen Sie die /multiple Endpoints für Massen-Operationen, um mehrere Contacts gleichzeitig zu archivieren, dearchivieren oder zu löschen, anstatt einzelne Requests zu senden.

E-Mail-Validierung

Validieren Sie E-Mail-Adressen vor dem Absenden, um Validierungsfehler zu vermeiden. Beachten Sie, dass das E-Mail-Feld optional ist.

Nächste Schritte

Customers API - Customers verwalten (Contacts werden beim Erstellen von Customers angelegt)
Invoices API - Rechnungen mit Contacts verknüpfen
Proposals API - Offerten mit Contacts verknüpfen
Code-Beispiele ansehen
Webhooks einrichten

Contacts API ​

Contact-Objekt ​

Attribute ​

Endpoints ​

Alle Contacts auflisten ​

Parameter ​

Response ​

Beispiele ​

Einzelnen Contact abrufen ​

Parameter ​

Response ​

Beispiele ​

Contact aktualisieren ​

Request Body ​

Validierung ​

Besonderheiten ​

Response ​

Beispiele ​

Contact löschen ​

Response ​

Beispiel ​

Mehrere Contacts archivieren/dearchivieren ​

Request Body ​

Response ​

Beispiele ​

Mehrere Contacts löschen ​

Request Body ​

Response ​

Beispiel ​

Fehlerbehandlung ​

Häufige Fehler ​

409 Conflict - Contact hat Rechnungen/Offerten ​

422 Validation Error ​

Best Practices ​

Primärkontakt-Verwaltung ​

Archivierung statt Löschung ​

Bulk-Operationen effizient nutzen ​

E-Mail-Validierung ​

Nächste Schritte ​

Contacts API

Contact-Objekt

Attribute

Endpoints

Alle Contacts auflisten

Parameter

Response

Beispiele

Einzelnen Contact abrufen

Parameter

Response

Beispiele

Contact aktualisieren

Request Body

Validierung

Besonderheiten

Response

Beispiele

Contact löschen

Response

Beispiel

Mehrere Contacts archivieren/dearchivieren

Request Body

Response

Beispiele

Mehrere Contacts löschen

Request Body

Response

Beispiel

Fehlerbehandlung

Häufige Fehler

409 Conflict - Contact hat Rechnungen/Offerten

422 Validation Error

Best Practices

Primärkontakt-Verwaltung

Archivierung statt Löschung

Bulk-Operationen effizient nutzen

E-Mail-Validierung

Nächste Schritte