Kontakte

Kontakte sind ein zentraler Bestandteil von seven. Auf dieser Seite werden wir uns mit den verschiedenen Kontakt-Endpunkten beschäftigen, mit denen Sie Kontakte programmatisch verwalten können. Wir werden uns ansehen, wie Sie Kontakte abfragen, erstellen, aktualisieren und löschen können.

Das Kontaktmodell

Das Kontaktmodell enthält alle Informationen über Ihre Kontakte, wie z.B. den Namen, den Avatar und die Telefonnummer. Sofern Sie eigene Kontakteigenschaften erstellt haben, wird jeweils der eindeutige Name als zusätzliche Eigenschaft im properties-Objekt ausgegeben.

Eigenschaften

Name
id
Type
integer
Description
Eindeutige ID des Kontakts.
Name
avatar
Type
string
Description
Die Avatar URL des Kontakts.
intials
validation
properties
- Name
  firstname
  Type
  string
  Description
  Vorname des Kontakts.
- Name
  lastname
  Type
  string
  Description
  Nachname des Kontakts.
- Name
  home_number
  Type
  phonenumber
  Description
  Festnetznummer des Kontakts.
- Name
  mobile_number
  Type
  phonenumber
  Description
  Mobilrufnummer des Kontakts.
- Name
  address
  Type
  string
  Description
  Adresse des Kontakts.
- Name
  email
  Type
  string
  Description
  E-Mail des Kontakts.
- Name
  postal_code
  Type
  integer
  Description
  Postleitzahl des Kontakts.
- Name
  city
  Type
  string
  Description
  Stadt des Kontakts.
- Name
  birthday
  Type
  date
  Description
  Geburtsdatum des Kontakts.
- Name
  notes
  Type
  string
  Description
  Notizen zum Kontakt.
Name
groups
Type
array
Description
Ein Array bestehend aus den IDs der Gruppen, in denen der Kontakt Mitglied ist. Wenn beim Ändern oder Erstellen eines Kontakts diese Eigenschaft angegeben wird, muss Sie alle Gruppen-IDs enthalten, in der der Kontakt Mitglied sein soll.
Name
created
Type
timestamp
Description
Zeitpunkt der Erstellung des Kontakts.

{
  "id": 12876881,
  "avatar": "https://static.seven.io/uploads/contact_images/4A000c0d4e9431F483090dE8D13F3806.jpg",
  "validation": {
    "state": "absent",
    "timestamp": "2024-01-09 16:08:29"
  },
  "initials": {
    "initials": "PM",
    "color": "9EB384"
  },
  "properties": {
    "firstname": "Peter",
    "lastname": "Mustermann",
    "mobile_number": 4917612345678,
    "home_number": null,
    "email": null,
    "address": null,
    "postal_code": null,
    "city": null,
    "birthday": "1977-07-07",
    "notes": null,
  },
  "groups": [
    18008
  ],
  "created": "2024-01-09 13:14:48"
}

GET/api/contacts

Kontaktliste abfragen

Mit diesem Endpunkt können Sie eine seitenweise Liste aller Ihrer Kontakte abrufen. Standardmäßig werden maximal 30 Kontakte pro Seite angezeigt.

Name
order_by
Type
string
Optional
Optional
Description
Die Spalte, nach der die Kontakte sortierte werden sollen.
Name
order_direction
Type
string
Optional
Optional
Description
Die Richtung der Sortierung. Kann entweder asc oder desc sein.
Name
search
Type
string
Optional
Optional
Description
Mit diesem Parameter können Sie in Ihren Kontakten in allen Spalten suchen.
Name
offset
Type
integer
Optional
Optional
Description
Die Seite, die angezeigt werden soll.
Name
limit
Type
integer
Optional
Optional
Description
Die Anzahl an Kontakten, die pro Seite ausgegeben werden soll. Kann ein Wert zwischen 30 und 500 sein.
Name
group_id
Type
integer
Optional
Optional
Description
Zeigen Sie nur Kontakte an, die Mitglied einer bestimmten Gruppe sind.

Anfrage

GET

/api/contacts

curl -G https://gateway.seven.io/api/contacts \
  -H "X-Api-Key: IHR_API_SCHLÜSSEL" \

Antwort

{
  "pagingMetadata": {
    "offset": 0,
    "count": 30,
    "total": 20013,
    "limit": 30,
    "has_more": true
  },
  "data": [
    {
      "id": 12876881,
      "avatar": "https://static.seven.io/uploads/contact_images/4A000c0d4e9431F483090dE8D13F3806.jpg",
      "validation": {
        "state": "absent",
        "timestamp": "2024-01-09 16:08:29"
      },
      "initials": {
        "initials": "PM",
        "color": "9EB384"
      },
      "properties": {
        "firstname": "Peter",
        "lastname": "Mustermann",
        "mobile_number": 4917612345678,
        "home_number": null,
        "email": null,
        "address": null,
        "postal_code": null,
        "city": null,
        "birthday": "1977-07-07",
        "notes": null,
      },
      "groups": [
        18008
      ],
      "created": "2024-01-09 13:14:48"
    },
    {
      "id": 12454415,
      // ...
    }
  ]
}

POST/api/contacts

Kontakt erstellen

Mit diesem Endpunkt können Sie einen neuen Kontakt hinzufügen. Wenn alles geklappt hat, erhalten Sie das erstellte Kontaktobjekt als Antwort zurück. Sofern Sie eigene Kontakteigenschaften erstellt haben und diese beim Kontakt festlegen möchten, geben Sie bitte den eindeutigen Namen der Eigenschaft als zusätzlichen Parameter an.

cURL

POST

/api/contacts

curl https://gateway.seven.io/api/contacts \
  -H "X-Api-Key: IHR_API_SCHLÜSSEL" \
  -d "firstname=Frank" \
  -d "lastname=McAllister" \
  -d "mobile_number=1-800-759-3000" \
  -d "avatar=https://picsum.photos/200"

Response

{
  "id": 12876882,
  "avatar": "https://static.seven.io/uploads/contact_images/4A000c0d4e9431F483090dE8D13F3806.jpg",
  "validation": {
    "state": null,
    "timestamp": null
  },
  "initials": {
    "initials": "FM",
    "color": "EEE0C9"
  },
  "properties": {
    "firstname": "Frank",
    "lastname": "McAllister",
    "mobile_number": "18007593000",
    "home_number": null,
    "email": null,
    "address": null,
    "postal_code": null,
    "city": null,
    "birthday": null,
    "notes": null,
  },
  "groups": [
  ],
  "created": "2024-01-09 13:12:48"
}

GET/api/contacts/:id

Kontakt abrufen

Mit diesem Endpunkt können Sie einen Kontakt durch Angabe seiner ID abrufen. In der Liste oben auf dieser Seite können Sie nachlesen, welche Eigenschaften in Kontaktobjekten enthalten sind.

cURL

GET

/api/contacts/12876881

curl https://gateway.seven.io/api/contacts/12876881 \
  -H "X-Api-Key: IHR_API_SCHLÜSSEL"

Response

{
  "id": 12876881,
  "avatar": "https://static.seven.io/uploads/contact_images/4A000c0d4e9431F483090dE8D13F3806.jpg",
  "validation": {
    "state": "absent",
    "timestamp": "2024-01-09 16:08:29"
  },
  "initials": {
    "initials": "PM",
    "color": "9EB384"
  },
  "properties": {
    "firstname": "Peter",
    "lastname": "Mustermann",
    "mobile_number": 4917612345678,
    "home_number": null,
    "email": null,
    "address": null,
    "postal_code": null,
    "city": null,
    "birthday": "1977-07-07",
    "notes": null,
  },
  "groups": [
    18008
  ],
  "created": "2024-01-09 13:14:48"
}

PATCH/api/contacts/:id

Kontakt aktualisieren

Mit diesem Endpunkt können Sie einzelne oder mehrere Eigenschaften eines Kontakts ändern. Die Namen der Eigenschaften können Sie der Liste des Kontaktmodells entnehmen. Als Antwort erhalten Sie das aktualisierte Kontaktobjekt zurück.

cURL

PATCH

/api/contacts/12876881

curl -X PATCH https://gateway.seven.io/api/contacts/12876881 \
  -H "X-Api-Key: IHR_API_SCHLÜSSEL" \
  -d firstname="Marc" \
  -d lastname="Gump"

Response

{
  "id": 12876881,
  "avatar": "https://static.seven.io/uploads/contact_images/4A000c0d4e9431F483090dE8D13F3806.jpg",
  "validation": {
    "state": "absent",
    "timestamp": "2024-01-09 16:08:29"
  },
  "initials": {
    "initials": "CF",
    "color": "9EB384"
  },
  "properties": {
    "firstname": "Marc",
    "lastname": "Gump",
    "mobile_number": 4917612345678,
    "home_number": null,
    "email": null,
    "address": null,
    "postal_code": null,
    "city": null,
    "birthday": "1977-07-07",
    "notes": null,
  },
  "groups": [
    18008
  ],
  "created": "2024-01-09 13:14:48"
}

DELETE/api/contacts/:id

Kontakt löschen

Dieser Endpunkt ermöglicht es Ihnen, Kontakte aus Ihrer Kontaktliste zu löschen.

cURL

DELETE

/api/contacts/12454414

curl -X DELETE https://gateway.seven.io/api/contacts/12454414 \
  -H "X-Api-Key: IHR_API_SCHLÜSSEL"