Kontakte

Wie der Name schon andeutet, sind Kontakte ein zentraler Bestandteil von seven - der eigentliche Grund für die Existenz von seven ist, dass Sie sichere Konversationen mit Ihren Kontakten führen können. 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
      • Name
        initials
        Type
        string
        Description

        Die Initialen des Kontakts.

      • Name
        color
        Type
        hex color
        Description

        Hex Farbcode.

  • validation
      • Name
        state
        Type
        string
        Description

        Das letzte Validierungsergebnis der Mobilrufnummer des Kontakts. Kann einen der Werte valid, invalid, absent oder unknown haben.

      • Name
        timestamp
        Type
        timestamp
        Description

        Der Zeitpunkt der letzten Validierung der Mobilrufnummer des Kontakts.

  • 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,
    "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

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