CRMCRM-Gruppen

CRM-Gruppen

Listen Sie Kontaktgruppen auf, erstellen und aktualisieren Sie sie und rufen Sie Gruppenkontakte für Kampagnen, Routing und Segmentierung ab.

curl -X GET "https://app.talkturo.com/api/crm/groups?teamId=9f3d2c41-6b5e-4d4f-9b7c-0f1a2b3c4d5e&search=Sales" \
  -H "Authorization: Bearer tk_example_9xmk7q2r"

{
  "success": true,
  "groups": [
    {
      "id": "c3b4a9a8-8d52-4fd0-9c52-6c1c6c9a1132",
      "team_id": "9f3d2c41-6b5e-4d4f-9b7c-0f1a2b3c4d5e",
      "name": "Sales",
      "is_default": false,
      "created_at": "2025-01-15T10:30:00.000Z",
      "updated_at": "2025-01-20T08:45:00.000Z",
      "created_by": "2a7e4f10-0f93-4a55-a4b0-51b5ec2d8f11",
      "contact_count": 42
    }
  ],
  "count": 1
}

curl -X POST "https://app.talkturo.com/api/crm/groups" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer tk_example_9xmk7q2r" \
  -d '{
    "teamId": "9f3d2c41-6b5e-4d4f-9b7c-0f1a2b3c4d5e",
    "name": "Enterprise Leads"
  }'

{
  "success": true,
  "group": {
    "id": "d2a7b3aa-8d7a-43f1-92bc-4a9c6f57a8e1",
    "team_id": "9f3d2c41-6b5e-4d4f-9b7c-0f1a2b3c4d5e",
    "name": "Enterprise Leads",
    "is_default": false,
    "created_at": "2025-01-21T09:15:00.000Z",
    "updated_at": "2025-01-21T09:15:00.000Z",
    "created_by": "2a7e4f10-0f93-4a55-a4b0-51b5ec2d8f11"
  }
}

curl -X GET "https://app.talkturo.com/api/crm/groups/c3b4a9a8-8d52-4fd0-9c52-6c1c6c9a1132" \
  -H "Authorization: Bearer tk_example_9xmk7q2r"

{
  "success": true,
  "group": {
    "id": "c3b4a9a8-8d52-4fd0-9c52-6c1c6c9a1132",
    "team_id": "9f3d2c41-6b5e-4d4f-9b7c-0f1a2b3c4d5e",
    "name": "Sales",
    "is_default": false,
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-20T08:45:00.000Z",
    "created_by": "2a7e4f10-0f93-4a55-a4b0-51b5ec2d8f11",
    "contacts": [
      {
        "id": "7c1a91b4-52fd-44e1-bbd4-8f75a2d4e7d9",
        "first_name": "Mara",
        "last_name": "Schneider",
        "email": "mara.schneider@acme.de",
        "phone": "+49-30-555-0188",
        "job_title": "Head of Operations",
        "lead_status": "qualified"
      }
    ],
    "contact_count": 200
  }
}

curl -X PUT "https://app.talkturo.com/api/crm/groups/c3b4a9a8-8d52-4fd0-9c52-6c1c6c9a1132" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer tk_example_9xmk7q2r" \
  -d '{
    "name": "Outbound Priority"
  }'

{
  "success": true,
  "group": {
    "id": "c3b4a9a8-8d52-4fd0-9c52-6c1c6c9a1132",
    "team_id": "9f3d2c41-6b5e-4d4f-9b7c-0f1a2b3c4d5e",
    "name": "Outbound Priority",
    "is_default": false,
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-22T07:20:00.000Z",
    "created_by": "2a7e4f10-0f93-4a55-a4b0-51b5ec2d8f11"
  }
}

curl -X DELETE "https://app.talkturo.com/api/crm/groups/c3b4a9a8-8d52-4fd0-9c52-6c1c6c9a1132" \
  -H "Authorization: Bearer tk_example_9xmk7q2r"

{
  "error": "Groups cannot be deleted. Rename it instead, or leave it unused."
}

Endpunkte für CRM-Gruppen

Verwenden Sie die CRM-Gruppen-Endpunkte, um Kontaktgruppen in Ihrem Workspace zu verwalten. Sie können Gruppen auflisten, neue Gruppen erstellen, eine einzelne Gruppe mit ihren Kontakten abrufen und bestehende Gruppen umbenennen.

Authentifizieren Sie diese Endpunkte entweder mit einem Session-Cookie oder mit einem API-Schlüssel über withApiAuth.

Basis-URL

https://app.talkturo.com

Authentifizierung

header
Authorizationstring

Verwenden Sie Bearer tk_example_9xmk7q2r, wenn Sie einen API-Schlüssel senden. Wenn Sie mit einer Browser-Sitzung arbeiten, wird stattdessen das Session-Cookie verwendet.

Gruppen auflisten

Rufen Sie alle Gruppen eines Teams ab und filtern Sie optional nach dem Gruppennamen.

Endpunkt

GET /api/crm/groups

Query-Parameter

query
teamIdstring
Required

Workspace-ID des Teams. Bei Session-Authentifizierung ist dieser Wert erforderlich. Bei API-Schlüsseln wird das Team aus dem Schlüsselkontext abgeleitet.

Antwortfelder

successboolean
Required

Gibt an, ob die Anfrage erfolgreich war.

groupsarray
Required

Liste der gefundenen Gruppen.

countnumber
Required

Anzahl der zurückgegebenen Gruppen.

idstring
Required

Eindeutige UUID der Gruppe.

team_idstring
Required

UUID des Teams, zu dem die Gruppe gehört.

namestring
Required

Anzeigename der Gruppe.

is_defaultboolean
Required

Kennzeichnet, ob es sich um die Standardgruppe des Teams handelt.

created_atstring
Required

Zeitpunkt der Erstellung im ISO-Format.

updated_atstring
Required

Zeitpunkt der letzten Aktualisierung im ISO-Format.

created_bystring
Required

UUID des Benutzers, der die Gruppe erstellt hat.

contact_countnumber
Required

Exakte Anzahl der Kontakte in dieser Gruppe.

Fehlercodes

  • 400 — teamId fehlt
  • 500 — Datenbankfehler oder unerwarteter Serverfehler

Gruppe erstellen

Erstellen Sie eine neue Gruppe in einem Team. Der Gruppenname muss innerhalb des Teams eindeutig sein.

Endpunkt

POST /api/crm/groups

Request-Body

body
teamIdstring
Required

Workspace-ID des Teams. Bei Session-Authentifizierung ist dieser Wert erforderlich. Bei API-Schlüsseln wird teamId ignoriert und das Team des Schlüssels verwendet.

body
namestring
Required

Name der Gruppe. Der Name muss innerhalb des Teams eindeutig sein.

Antwortfelder

successboolean
Required

Gibt an, ob die Gruppe erfolgreich erstellt wurde.

groupobject
Required

Die neu erstellte Gruppe.

Fehlercodes

  • 400 — teamId oder name fehlt oder der Gruppenname existiert bereits
  • 500 — Datenbankfehler oder unerwarteter Serverfehler

Gruppe mit Kontakten abrufen

Rufen Sie eine einzelne Gruppe zusammen mit bis zu 100 Kontakten ab. Die Kontakte werden zuerst nach dem neuesten added_at zurückgegeben.

Endpunkt

GET /api/crm/groups/{id}

Pfadparameter

path
idstring
Required

UUID der Gruppe.

Antwortfelder

successboolean
Required

Gibt an, ob die Anfrage erfolgreich war.

groupobject
Required

Die angeforderte Gruppe mit ihren Kontakten und der Gesamtanzahl der Kontakte.

contactsarray
Required

Bis zu 100 Kontakte aus der Gruppe, sortiert nach dem neuesten added_at.

contact_countnumber
Required

Gesamtanzahl der Kontakte in der Gruppe.

first_namestring
Required

Vorname des Kontakts.

last_namestring
Required

Nachname des Kontakts.

emailstring
Required

E-Mail-Adresse des Kontakts.

phonestring
Required

Telefonnummer des Kontakts.

job_titlestring
Required

Berufsbezeichnung des Kontakts.

lead_statusstring
Required

Aktueller Lead-Status des Kontakts.

Fehlercodes

  • 401 — kein accountId im Authentifizierungskontext
  • 404 — Gruppe nicht gefunden
  • 500 — Datenbankfehler oder unerwarteter Serverfehler

Gruppe aktualisieren

Benennen Sie eine bestehende Gruppe um. Über diesen Endpunkt können Sie nur den Namen ändern.

Endpunkt

PUT /api/crm/groups/{id}

Pfadparameter

path
idstring
Required

UUID der Gruppe, die Sie aktualisieren möchten.

Request-Body

body
namestring

Neuer Name der Gruppe. Wenn name gesendet wird, darf der Wert nicht leer sein.

is_default kann über diesen Endpunkt nicht bearbeitet werden.

Antwortfelder

successboolean
Required

Gibt an, ob die Aktualisierung erfolgreich war.

groupobject
Required

Die aktualisierte Gruppe.

Fehlercodes

  • 400 — leerer Name oder doppelter Gruppenname
  • 401 — kein accountId im Authentifizierungskontext
  • 404 — Gruppe nicht gefunden
  • 500 — Datenbankfehler oder unerwarteter Serverfehler

Gruppen können nicht gelöscht werden

Der Lösch-Endpunkt ist vorhanden, unterstützt das Löschen von Gruppen aber nicht.

Endpunkt

DELETE /api/crm/groups/{id}

Dieser Endpunkt gibt immer 405 Method Not Allowed zurück. Löschen Sie Gruppen nicht über die API. Benennen Sie die Gruppe stattdessen um oder lassen Sie sie ungenutzt.

Pfadparameter

path
idstring
Required

UUID der Gruppe.

Fehlercodes

  • 405 — Methode nicht erlaubt; Gruppen können nicht gelöscht werden

Gruppen-Kontakt-Mitgliedschaft

Verwalten Sie, welche Kontakte zu einer CRM-Gruppe gehören. Fügen Sie Kontakte hinzu, entfernen Sie sie und listen Sie Kontakte innerhalb einer Gruppe über diese Mitgliedschafts-Endpunkte auf.

Kontakte in einer Gruppe auflisten

Rufen Sie seitenweise Kontakte für eine bestimmte Gruppe ab. Ergebnisse sind nach Mitgliedschafts-Erstellungszeit sortiert, neueste zuerst.

Endpunkt

GET /api/crm/groups/{id}/contacts

Pfadparameter

path
idstring
Required

UUID der Gruppe.

Abfrageparameter

query
limitinteger

Maximale Anzahl der zurückgegebenen Kontakte. Standardwert 100.

query
offsetinteger

Anzahl der zu überspringenden Kontakte für Paginierung. Standardwert 0.

Antwortfelder

successboolean
Required

Gibt an, ob die Anfrage erfolgreich war.

contactsarray
Required

Array von Kontaktdatensätzen in der Gruppe.

countinteger
Required

Gesamtzahl der Kontakte in der Gruppe.

limitinteger
Required

Verwendetes Paginierungslimit für diese Anfrage.

offsetinteger
Required

Verwendeter Paginierungsoffset für diese Anfrage.

Fehlercodes

  • 401 — Fehlende Authentifizierung oder Kontokontext
  • 404 — Gruppe nicht gefunden oder gehört nicht zum Konto

Einen Kontakt zu einer Gruppe hinzufügen

Fügen Sie einen Kontakt zu einer CRM-Gruppe hinzu. Der Kontakt und die Gruppe müssen beide zum selben Konto gehören. Dieser Vorgang ist idempotent: Das Hinzufügen eines bereits in der Gruppe befindlichen Kontakts gibt Erfolg zurück, ohne ein Duplikat zu erstellen.

Endpunkt

POST /api/crm/groups/{id}/contacts

Pfadparameter

path
idstring
Required

UUID der Gruppe.

Body-Parameter

body
contactIdstring
Required

UUID des hinzuzufügenden Kontakts. Der Kontakt muss zum selben Konto wie die Gruppe gehören.

API-Schlüssel benötigen den Scope contacts:write für diesen Endpunkt.

Antwortfelder

successboolean
Required

Gibt true zurück, wenn der Kontakt hinzugefügt wurde oder bereits Mitglied war.

Fehlercodes

  • 400 — contactId fehlt
  • 401 — Fehlende Authentifizierung oder Kontokontext
  • 404 — Gruppe oder Kontakt nicht gefunden

Einen Kontakt aus einer Gruppe entfernen

Entfernen Sie einen Kontakt anhand seiner Kontakt-ID aus einer CRM-Gruppe. Das Entfernen eines Kontakts, der nicht in der Gruppe ist, gibt trotzdem Erfolg zurück.

Endpunkt

DELETE /api/crm/groups/{id}/contacts?contactId={contactId}

Pfadparameter

path
idstring
Required

UUID der Gruppe.

Abfrageparameter

query
contactIdstring
Required

UUID des zu entfernenden Kontakts.

API-Schlüssel benötigen den Scope contacts:write für diesen Endpunkt.

Antwortfelder

successboolean
Required

Gibt true zurück, wenn der Kontakt entfernt wurde oder nicht Mitglied war.

Fehlercodes

  • 400 — contactId fehlt
  • 401 — Fehlende Authentifizierung oder Kontokontext
  • 404 — Gruppe nicht gefunden oder gehört nicht zum Konto

Verwandte Ressourcen

CRM-Kontakte

CRM-Kampagnen

Was this page helpful?