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
| Methode | Pfad | Zweck |
|---|---|---|
GET | /api/crm/contacts | Kontakte auflisten und filtern |
POST | /api/crm/contacts | Kontakt 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/import | Kontakte aus einer CSV-Datei importieren |
GET | /api/crm/import-batches | Import-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
Team-ID. Für API-Key-Anfragen optional, weil das Team aus dem API-Schlüssel abgeleitet wird. Für Session-Anfragen erforderlich.
Schränkt die Ergebnisse auf Kontakte in dieser Gruppe ein.
Case-insensitive Suche über firstName, lastName, email und phone.
Exakter Filter für den Lead-Status.
Bei true werden nur Kontakte mit Telefonnummer zurückgegeben. Bei false werden nur Kontakte ohne Telefonnummer zurückgegeben.
truefalseMaximale Anzahl der Kontakte. Standardwert ist 50.
Anzahl der zu überspringenden Kontakte. Standardwert ist 0.
Antwortfelder
Kennzeichnet eine erfolgreiche Anfrage.
Gefundene Kontakte. Jeder Kontakt enthält ein groups-Array mit den Feldern id und name.
Anzahl der Kontakte in der aktuellen Antwort.
Für die Anfrage verwendetes Ergebnislimit.
Für die Anfrage verwendeter Offset.
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
}'
curl -X POST "https://api.talkturo.com/api/crm/contacts" \
-H "Content-Type: application/json" \
-H "Cookie: sb-session=example_session_cookie" \
-d '{
"teamId": "team_42",
"firstName": "Jane",
"lastName": "Chen",
"phone": "+14155550189",
"email": "jane.chen@northstar.io",
"companyName": "Northstar Analytics",
"leadStatus": "qualified"
}'
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
Team-ID. Für API-Key-Anfragen optional, für Session-Anfragen erforderlich.
Gruppe, der der Kontakt zugeordnet wird. Ohne Angabe verwendet die API die Standardgruppe des Teams.
Vorname des Kontakts. Darf nicht leer sein.
Nachname des Kontakts. Darf nicht leer sein.
Primäre Telefonnummer im E.164-Format, zum Beispiel +14155550189.
E-Mail-Adresse des Kontakts.
Sekundäre Telefonnummer.
Position oder Funktion des Kontakts.
Name des Unternehmens. Verwenden Sie companyName, nicht company_id.
Lead-Status des Kontakts.
Quelle des Kontakts. Standardwert ist api.
Zeitzone des Kontakts.
Bevorzugter Kontaktweg.
Gibt an, ob der Kontakt nicht angerufen werden darf.
Freitextnotizen zum Kontakt.
Objekt mit benutzerdefinierten Feldern. Verwenden Sie camelCase für die Feldnamen, zum Beispiel customerTier.
Kampagne, für die eine Anmeldung des Kontakts versucht werden soll.
Priorität des Kontakts innerhalb der Kampagne.
Antwortfelder
Kennzeichnet eine erfolgreiche Erstellung oder Zusammenführung.
Erstellter oder aktualisierter Kontaktdatensatz.
true, wenn die Telefonnummer zu einem bestehenden Kontakt gehört und die API diesen Datensatz zusammengeführt hat.
Ergebnis der Kampagnen-Anmeldung, sofern campaignId übergeben wurde.
Status der Kampagnen-Anmeldung: enrolled, already_enrolled oder excluded.
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
Eindeutige ID des Kontakts.
Antwortfelder
Kennzeichnet eine erfolgreiche Anfrage.
Angeforderter Kontakt mit groups, activities, opportunities und campaign_history.
Gruppen des Kontakts mit id und name.
Aktivitäten des Kontakts.
Dem Kontakt zugeordnete Opportunities.
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
Eindeutige ID des Kontakts, den Sie aktualisieren möchten.
Request-Body
Team-ID. Für API-Key-Anfragen optional, für Session-Anfragen erforderlich.
Neue Gruppenzuordnung des Kontakts.
Aktualisierter Vorname.
Aktualisierter Nachname.
Aktualisierte primäre Telefonnummer im E.164-Format.
Aktualisierte E-Mail-Adresse.
Aktualisierte sekundäre Telefonnummer.
Aktualisierte Position oder Funktion.
Aktualisierter Unternehmensname.
Aktualisierter Lead-Status.
Aktualisierte Kontaktquelle.
Aktualisierte Zeitzone.
Aktualisierter bevorzugter Kontaktweg.
Aktualisierter Anrufschutzstatus.
Aktualisierte Notizen.
Aktualisierte benutzerdefinierte Felder mit camelCase-Schlüsseln.
Kampagne, der der Kontakt zugeordnet werden soll.
Aktualisierte Kampagnenpriorität.
Zeitpunkt des letzten Kontakts im ISO-8601-Format.
Antwortfelder
Kennzeichnet eine erfolgreiche Aktualisierung.
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
Eindeutige ID des Kontakts, den Sie löschen möchten.
Antwortfelder
Kennzeichnet eine erfolgreiche Löschung.
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
CSV-Datei mit den zu importierenden Kontakten.
Team-ID, in das die Kontakte importiert werden.
Bestehende Gruppe für die importierten Kontakte. Optional, wenn newGroupName angegeben wird.
Name einer neuen Gruppe, die für den Import erstellt werden soll.
Verhalten bei Duplikaten. Mögliche Werte sind skip, update und replace. Standardwert ist skip.
skipupdatereplaceJSON-String, der CSV-Spalten den Kontaktfeldern zuordnet. Beispiel: {"first_name":"first_name","phone":"phone"}.
Antwortfelder
Kennzeichnet einen erfolgreich verarbeiteten Import.
Anzahl der neu importierten Kontakte.
Anzahl der aktualisierten Kontakte.
Anzahl übersprungener Duplikate.
Anzahl fehlgeschlagener Datensätze.
Gesamtzahl der verarbeiteten Datensätze.
Fehlerliste mit den betroffenen Zeilen und Fehlermeldungen.
ID der für den Import verwendeten Gruppe.
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
Team-ID. Erforderlich, wenn sie nicht aus der Authentifizierung abgeleitet werden kann.
Gruppe, deren Import-Stapel abgerufen werden sollen.
Maximale Anzahl der Import-Stapel. Standardwert ist 50; zulässig sind Werte von 1 bis 200.
Antwortfelder
Kennzeichnet eine erfolgreiche Anfrage.
Liste der Import-Stapel mit Datei-, Zeit- und Ergebnisinformationen.
ID des Import-Stapels.
Name der importierten CSV-Datei.
Zeitpunkt der Erstellung des Import-Stapels.
Anzahl der neu erstellten Kontakte.
Anzahl der aktualisierten Kontakte.
Anzahl übersprungener Kontakte.
Anzahl fehlgeschlagener Kontakte.