CRMCRM-Kontakte

CRM-Kontakte

Verwalten Sie CRM-Kontakte mit API-Key oder Session-Authentifizierung, Filtern, Gruppen, Kampagnen, Massenimporten und Importstapeln.

curl -X GET "https://api.talkturo.com/api/crm/contacts?teamId=team_42&groupId=grp_sales&search=jane&leadStatus=qualified&doNotCall=false&hasPhone=true&limit=50&offset=0" \
  -H "x-api-key: dkai_example_9xmk7q2r"
{
  "success": true,
  "contacts": [
    {
      "id": "ctc_8f3a21",
      "firstName": "Jane",
      "lastName": "Chen",
      "email": "jane.chen@northstar.io",
      "phone": "+14155550189",
      "leadStatus": "qualified",
      "doNotCall": false,
      "groups": [
        {
          "id": "grp_sales",
          "name": "Vertrieb"
        }
      ]
    }
  ],
  "count": 1,
  "limit": 50,
  "offset": 0
}
{
  "success": true,
  "contact": {
    "id": "ctc_8f3a21",
    "firstName": "Jane",
    "lastName": "Chen",
    "phone": "+14155550189",
    "email": "jane.chen@northstar.io",
    "companyName": "Northstar Analytics",
    "leadStatus": "qualified"
  },
  "existing": false,
  "campaign_enrollment": {
    "campaign_contact_id": "cc_5d7e91",
    "status": "enrolled",
    "excludedReason": null
  }
}
curl -X GET "https://api.talkturo.com/api/crm/contacts/ctc_8f3a21" \
  -H "x-api-key: dkai_example_9xmk7q2r"
{
  "success": true,
  "contact": {
    "id": "ctc_8f3a21",
    "firstName": "Jane",
    "lastName": "Chen",
    "phone": "+14155550189",
    "email": "jane.chen@northstar.io",
    "groups": [
      {
        "id": "grp_sales",
        "name": "Vertrieb"
      }
    ],
    "activities": [],
    "opportunities": [],
    "campaign_history": []
  }
}
curl -X PUT "https://api.talkturo.com/api/crm/contacts/ctc_8f3a21" \
  -H "Content-Type: application/json" \
  -H "x-api-key: dkai_example_9xmk7q2r" \
  -d '{
    "phone": "+14155550190",
    "companyName": "Northstar Research",
    "leadStatus": "contacted",
    "lastContactedAt": "2025-02-14T15:30:00.000Z",
    "customFields": {
      "customerTier": "enterprise",
      "renewalMonth": "November"
    }
  }'
{
  "success": true,
  "contact": {
    "id": "ctc_8f3a21",
    "firstName": "Jane",
    "lastName": "Chen",
    "phone": "+14155550190",
    "companyName": "Northstar Research",
    "leadStatus": "contacted",
    "lastContactedAt": "2025-02-14T15:30:00.000Z"
  }
}
curl -X DELETE "https://api.talkturo.com/api/crm/contacts/ctc_8f3a21" \
  -H "x-api-key: dkai_example_9xmk7q2r"
{
  "success": true,
  "message": "Contact deleted successfully"
}
curl -X POST "https://api.talkturo.com/api/crm/contacts/import" \
  -H "x-api-key: dkai_example_9xmk7q2r" \
  -F "file=@contacts-february.csv;type=text/csv" \
  -F "teamId=team_42" \
  -F "groupId=grp_sales" \
  -F "duplicateMode=skip" \
  -F 'columnMapping={"first_name":"first_name","last_name":"last_name","phone":"phone","email":"email","companyName":"company_name"}'
{
  "success": true,
  "imported": 184,
  "updated": 0,
  "skipped": 12,
  "failed": 3,
  "total": 199,
  "errors": [
    {
      "row": 47,
      "message": "Invalid phone number"
    }
  ],
  "groupId": "grp_sales",
  "batchId": "batch_7c91e2"
}
curl -X GET "https://api.talkturo.com/api/crm/import-batches?teamId=team_42&groupId=grp_sales&limit=50" \
  -H "x-api-key: dkai_example_9xmk7q2r"
{
  "success": true,
  "batches": [
    {
      "id": "batch_7c91e2",
      "filename": "contacts-february.csv",
      "created_at": "2025-02-14T15:32:10.000Z",
      "created_count": 184,
      "updated_count": 0,
      "skipped_count": 12,
      "failed_count": 3
    }
  ]
}

CRM-Kontakte im Talkturo-CRM verwalten

Mit den CRM-Kontakt-Endpunkten erstellen, suchen, aktualisieren, löschen und importieren Sie Kontakte. Die API unterstützt Gruppen, benutzerdefinierte Felder, Tags, Kampagnenzuordnungen und Filter für Telefonstatus und Lead-Status.

Alle Endpunkte unterstützen API-Key-Authentifizierung und Session-Cookie-Authentifizierung über withApiAuth.

API-Key-Anfragen verwenden automatisch das dem Schlüssel zugeordnete Konto. teamId ist bei diesen Anfragen optional. Session-Anfragen müssen teamId im Query-String oder im Request-Body enthalten.

Endpunktübersicht

MethodePfadZweck
GET/api/crm/contactsKontakte auflisten und filtern
POST/api/crm/contactsKontakt erstellen oder anhand der Telefonnummer zusammenführen
GET/api/crm/contacts/{id}Einzelnen Kontakt mit Aktivitäten und Zuordnungen abrufen
PUT/api/crm/contacts/{id}Kontakt aktualisieren
DELETE/api/crm/contacts/{id}Kontakt löschen
POST/api/crm/contacts/importKontakte aus einer CSV-Datei importieren
GET/api/crm/import-batchesImport-Stapel auflisten

Kontakte auflisten

Rufen Sie GET /api/crm/contacts auf, um Kontakte zu suchen, nach Gruppen und Lead-Status zu filtern und die Ergebnisse mit limit und offset zu paginieren.

Query-Parameter

query
teamIdstring

Team-ID. Für API-Key-Anfragen optional, weil das Team aus dem API-Schlüssel abgeleitet wird. Für Session-Anfragen erforderlich.

query
groupIdstring

Schränkt die Ergebnisse auf Kontakte in dieser Gruppe ein.

query
leadStatusstring

Exakter Filter für den Lead-Status.

query
doNotCallboolean

Filtert nach dem Status für Anrufschutz.

Allowed values:truefalse
query
hasPhoneboolean

Bei true werden nur Kontakte mit Telefonnummer zurückgegeben. Bei false werden nur Kontakte ohne Telefonnummer zurückgegeben.

Allowed values:truefalse
query
limitinteger

Maximale Anzahl der Kontakte. Standardwert ist 50.

query
offsetinteger

Anzahl der zu überspringenden Kontakte. Standardwert ist 0.

Antwortfelder

successboolean
Required

Kennzeichnet eine erfolgreiche Anfrage.

contactsarray
Required

Gefundene Kontakte. Jeder Kontakt enthält ein groups-Array mit den Feldern id und name.

countinteger
Required

Anzahl der Kontakte in der aktuellen Antwort.

limitinteger
Required

Für die Anfrage verwendetes Ergebnislimit.

offsetinteger
Required

Für die Anfrage verwendeter Offset.

groupsarray
Required

Gruppen des Kontakts. Jedes Element enthält id und name.

Kontakt erstellen

Rufen Sie POST /api/crm/contacts auf, um einen Kontakt mit camelCase-Feldern zu erstellen. firstName, lastName und eine Telefonnummer im E.164-Format sind erforderlich.

curl -X POST "https://api.talkturo.com/api/crm/contacts" \
  -H "Content-Type: application/json" \
  -H "x-api-key: dkai_example_9xmk7q2r" \
  -d '{
    "firstName": "Jane",
    "lastName": "Chen",
    "phone": "+14155550189",
    "email": "jane.chen@northstar.io",
    "companyName": "Northstar Analytics",
    "leadStatus": "qualified",
    "source": "api",
    "preferredContactMethod": "phone",
    "customFields": {
      "customerTier": "enterprise",
      "renewalMonth": "October"
    },
    "tags": ["priority", "conference-lead"],
    "campaignId": "camp_17",
    "campaignPriority": 10
  }'

Die API dedupliziert Kontakte anhand der Telefonnummer. Findet sie einen bestehenden Kontakt mit derselben Telefonnummer, führt sie die übergebenen Felder mit dem vorhandenen Datensatz zusammen und gibt existing: true zurück.

Wenn Sie campaignId übergeben, enthält die Antwort zusätzlich campaign_enrollment. Der Status ist enrolled, already_enrolled oder excluded. Bei excluded beschreibt excludedReason den Grund mit no_phone oder do_not_call.

Request-Body

body
teamIdstring

Team-ID. Für API-Key-Anfragen optional, für Session-Anfragen erforderlich.

body
groupIdstring

Gruppe, der der Kontakt zugeordnet wird. Ohne Angabe verwendet die API die Standardgruppe des Teams.

body
firstNamestring
Required

Vorname des Kontakts. Darf nicht leer sein.

body
lastNamestring
Required

Nachname des Kontakts. Darf nicht leer sein.

body
phonestring
Required

Primäre Telefonnummer im E.164-Format, zum Beispiel +14155550189.

body
emailstring

E-Mail-Adresse des Kontakts.

body
phoneSecondarystring

Sekundäre Telefonnummer.

body
jobTitlestring

Position oder Funktion des Kontakts.

body
companyNamestring

Name des Unternehmens. Verwenden Sie companyName, nicht company_id.

body
leadStatusstring

Lead-Status des Kontakts.

body
sourcestring

Quelle des Kontakts. Standardwert ist api.

body
timezonestring

Zeitzone des Kontakts.

body
preferredContactMethodstring

Bevorzugter Kontaktweg.

body
doNotCallboolean

Gibt an, ob der Kontakt nicht angerufen werden darf.

body
notesstring

Freitextnotizen zum Kontakt.

body
customFieldsobject

Objekt mit benutzerdefinierten Feldern. Verwenden Sie camelCase für die Feldnamen, zum Beispiel customerTier.

body
tagsarray

Liste von Tags für den Kontakt.

body
campaignIdstring

Kampagne, für die eine Anmeldung des Kontakts versucht werden soll.

body
campaignPriorityinteger

Priorität des Kontakts innerhalb der Kampagne.

Antwortfelder

successboolean
Required

Kennzeichnet eine erfolgreiche Erstellung oder Zusammenführung.

contactobject
Required

Erstellter oder aktualisierter Kontaktdatensatz.

existingboolean
Required

true, wenn die Telefonnummer zu einem bestehenden Kontakt gehört und die API diesen Datensatz zusammengeführt hat.

campaign_enrollmentobject

Ergebnis der Kampagnen-Anmeldung, sofern campaignId übergeben wurde.

statusstring

Status der Kampagnen-Anmeldung: enrolled, already_enrolled oder excluded.

excludedReasonstring

Ausschlussgrund: no_phone, do_not_call oder null.

Hinweise zu benutzerdefinierten Feldern

Verwenden Sie für customFields ein Objekt mit camelCase-Schlüsseln. Die Feldnamen werden nicht in snake_case umgewandelt.

{
  "customFields": {
    "customerTier": "enterprise",
    "renewalMonth": "October",
    "accountManager": "Mira Patel"
  }
}

Einzelnen Kontakt abrufen

Rufen Sie GET /api/crm/contacts/{id} auf, um einen einzelnen Kontakt mit seinen Gruppen, Aktivitäten, Opportunities und seiner Kampagnenhistorie abzurufen.

Pfadparameter

path
idstring
Required

Eindeutige ID des Kontakts.

Antwortfelder

successboolean
Required

Kennzeichnet eine erfolgreiche Anfrage.

contactobject
Required

Angeforderter Kontakt mit groups, activities, opportunities und campaign_history.

groupsarray
Required

Gruppen des Kontakts mit id und name.

activitiesarray
Required

Aktivitäten des Kontakts.

opportunitiesarray
Required

Dem Kontakt zugeordnete Opportunities.

campaign_historyarray
Required

Kampagnenhistorie des Kontakts.

Kontakt aktualisieren

Rufen Sie PUT /api/crm/contacts/{id} auf, um einen bestehenden Kontakt zu aktualisieren. Alle Felder sind optional. Verwenden Sie dieselben camelCase-Felder wie beim Erstellen und ergänzen Sie bei Bedarf lastContactedAt.

Pfadparameter

path
idstring
Required

Eindeutige ID des Kontakts, den Sie aktualisieren möchten.

Request-Body

body
teamIdstring

Team-ID. Für API-Key-Anfragen optional, für Session-Anfragen erforderlich.

body
groupIdstring

Neue Gruppenzuordnung des Kontakts.

body
firstNamestring

Aktualisierter Vorname.

body
lastNamestring

Aktualisierter Nachname.

body
phonestring

Aktualisierte primäre Telefonnummer im E.164-Format.

body
emailstring

Aktualisierte E-Mail-Adresse.

body
phoneSecondarystring

Aktualisierte sekundäre Telefonnummer.

body
jobTitlestring

Aktualisierte Position oder Funktion.

body
companyNamestring

Aktualisierter Unternehmensname.

body
leadStatusstring

Aktualisierter Lead-Status.

body
sourcestring

Aktualisierte Kontaktquelle.

body
timezonestring

Aktualisierte Zeitzone.

body
preferredContactMethodstring

Aktualisierter bevorzugter Kontaktweg.

body
doNotCallboolean

Aktualisierter Anrufschutzstatus.

body
notesstring

Aktualisierte Notizen.

body
customFieldsobject

Aktualisierte benutzerdefinierte Felder mit camelCase-Schlüsseln.

body
tagsarray

Aktualisierte Liste von Tags.

body
campaignIdstring

Kampagne, der der Kontakt zugeordnet werden soll.

body
campaignPriorityinteger

Aktualisierte Kampagnenpriorität.

body
lastContactedAtstring

Zeitpunkt des letzten Kontakts im ISO-8601-Format.

Antwortfelder

successboolean
Required

Kennzeichnet eine erfolgreiche Aktualisierung.

contactobject
Required

Aktualisierter Kontaktdatensatz.

Kontakt löschen

Rufen Sie DELETE /api/crm/contacts/{id} auf, um einen Kontakt dauerhaft zu löschen. Kontakte in einer aktiven Kampagne können nicht gelöscht werden.

Prüfen Sie vor dem Löschen, ob der Kontakt einer aktiven Kampagne zugeordnet ist. Der Endpunkt lehnt die Löschung in diesem Fall ab.

Pfadparameter

path
idstring
Required

Eindeutige ID des Kontakts, den Sie löschen möchten.

Antwortfelder

successboolean
Required

Kennzeichnet eine erfolgreiche Löschung.

messagestring
Required

Bestätigung der Löschung.

Kontakte aus einer CSV-Datei importieren

Rufen Sie POST /api/crm/contacts/import mit multipart/form-data auf, um Kontakte aus einer CSV-Datei zu importieren. Der Endpunkt akzeptiert keinen JSON-Body.

Für CSV-Importe ist nur die Spalte first_name erforderlich. last_name ist optional. Verwenden Sie newGroupName anstelle von groupId, wenn der Import eine neue Gruppe anlegen soll.

Multipart-Felder

body
filefile
Required

CSV-Datei mit den zu importierenden Kontakten.

body
teamIdstring
Required

Team-ID, in das die Kontakte importiert werden.

body
groupIdstring

Bestehende Gruppe für die importierten Kontakte. Optional, wenn newGroupName angegeben wird.

body
newGroupNamestring

Name einer neuen Gruppe, die für den Import erstellt werden soll.

body
duplicateModestring

Verhalten bei Duplikaten. Mögliche Werte sind skip, update und replace. Standardwert ist skip.

Allowed values:skipupdatereplace
body
columnMappingstring
Required

JSON-String, der CSV-Spalten den Kontaktfeldern zuordnet. Beispiel: {"first_name":"first_name","phone":"phone"}.

Antwortfelder

successboolean
Required

Kennzeichnet einen erfolgreich verarbeiteten Import.

importedinteger
Required

Anzahl der neu importierten Kontakte.

updatedinteger
Required

Anzahl der aktualisierten Kontakte.

skippedinteger
Required

Anzahl übersprungener Duplikate.

failedinteger
Required

Anzahl fehlgeschlagener Datensätze.

totalinteger
Required

Gesamtzahl der verarbeiteten Datensätze.

errorsarray
Required

Fehlerliste mit den betroffenen Zeilen und Fehlermeldungen.

groupIdstring
Required

ID der für den Import verwendeten Gruppe.

batchIdstring
Required

ID des erstellten Import-Stapels.

Import-Stapel auflisten

Rufen Sie GET /api/crm/import-batches auf, um vergangene CSV-Importe für eine Gruppe abzurufen.

Query-Parameter

query
teamIdstring

Team-ID. Erforderlich, wenn sie nicht aus der Authentifizierung abgeleitet werden kann.

query
groupIdstring
Required

Gruppe, deren Import-Stapel abgerufen werden sollen.

query
limitinteger

Maximale Anzahl der Import-Stapel. Standardwert ist 50; zulässig sind Werte von 1 bis 200.

Antwortfelder

successboolean
Required

Kennzeichnet eine erfolgreiche Anfrage.

batchesarray
Required

Liste der Import-Stapel mit Datei-, Zeit- und Ergebnisinformationen.

idstring
Required

ID des Import-Stapels.

filenamestring
Required

Name der importierten CSV-Datei.

created_atstring
Required

Zeitpunkt der Erstellung des Import-Stapels.

created_countinteger
Required

Anzahl der neu erstellten Kontakte.

updated_countinteger
Required

Anzahl der aktualisierten Kontakte.

skipped_countinteger
Required

Anzahl übersprungener Kontakte.

failed_countinteger
Required

Anzahl fehlgeschlagener Kontakte.

Verwandte Inhalte