> ## Documentation Index
> Fetch the complete documentation index at: https://docs.talkturo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# REST-API-Endpunkte für CRM-Kontakte

> Erstellen und listen Sie CRM-Kontakte in Talkturo mithilfe der REST-API auf. Kontakte speichern Telefonnummern, E-Mail-Adressen, Lead-Status, benutzerdefinierte Felder und den Anrufverlauf der Kampagne.

Kontakte sind die einzelnen Personen in Ihrem Talkturo-CRM. Jeder Kontakt gehört zu einem Team und optional zu einem Unternehmen. In Kampagnen nutzt Talkturo die gespeicherten Telefonnummern für ausgehende Anrufe. Nach jedem Gespräch extrahiert die KI Daten und aktualisiert die Kontaktfelder.

***

## Create a contact

`POST /api/crm/contacts`

Creates a new contact in your CRM.

### Request body

<ParamField body="teamId" type="string" required>
  The team ID that owns this contact.
</ParamField>

<ParamField body="companyId" type="string" required>
  The ID of the company this contact belongs to.
</ParamField>

<ParamField body="firstName" type="string" required>
  Contact's first name.
</ParamField>

<ParamField body="lastName" type="string" required>
  Contact's last name.
</ParamField>

<ParamField body="email" type="string">
  Contact's email address.
</ParamField>

<ParamField body="phone" type="string">
  Primary phone number in E.164 format (for example, `"+12025551234"`).
</ParamField>

<ParamField body="phoneSecondary" type="string">
  Secondary phone number in E.164 format.
</ParamField>

<ParamField body="jobTitle" type="string">
  Contact's job title or role.
</ParamField>

<ParamField body="leadStatus" type="string">
  The lead status for this contact. Defaults to `new`. Common values: `new`, `contacted`, `qualified`, `unqualified`, `converted`.
</ParamField>

<ParamField body="source" type="string">
  Where this contact came from (for example, `"trade-show"`, `"website"`, `"referral"`).
</ParamField>

<ParamField body="timezone" type="string">
  Contact's IANA timezone (for example, `"America/Chicago"`). Used for call scheduling.
</ParamField>

<ParamField body="preferredContactMethod" type="string">
  Contact's preferred method (for example, `"phone"`, `"email"`).
</ParamField>

<ParamField body="doNotCall" type="boolean">
  When `true`, this contact is excluded from all campaigns. Defaults to `false`.
</ParamField>

<ParamField body="notes" type="string">
  Free-text notes about this contact.
</ParamField>

<ParamField body="customFields" type="object">
  A key-value object for any additional fields. Talkturo's AI info extractor can populate these fields automatically during calls.
</ParamField>

<ParamField body="tags" type="array">
  An array of string tags for categorizing this contact.
</ParamField>

### Example request

```bash theme={null}
curl -X POST https://<your-domain>/api/crm/contacts \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "teamId": "team_01j...",
    "companyId": "comp_01j...",
    "firstName": "Sarah",
    "lastName": "Chen",
    "email": "sarah.chen@example.com",
    "phone": "+14155551234",
    "jobTitle": "VP of Engineering",
    "leadStatus": "new",
    "source": "trade-show",
    "timezone": "America/Los_Angeles",
    "doNotCall": false,
    "tags": ["enterprise", "warm-lead"],
    "customFields": {
      "company_size": "500-1000",
      "interest": "outbound-automation"
    }
  }'
```

### Antwort

```json theme={null}
{
  "success": true,
  "contact": {
    "id": "cont_01j...",
    "team_id": "team_01j...",
    "company_id": "comp_01j...",
    "first_name": "Sarah",
    "last_name": "Chen",
    "email": "sarah.chen@example.com",
    "phone": "+14155551234",
    "phone_secondary": null,
    "job_title": "VP of Engineering",
    "lead_status": "new",
    "source": "trade-show",
    "timezone": "America/Los_Angeles",
    "do_not_call": false,
    "notes": null,
    "custom_fields": {
      "company_size": "500-1000",
      "interest": "outbound-automation"
    },
    "tags": ["enterprise", "warm-lead"],
    "created_at": "2024-01-15T10:00:00Z",
    "updated_at": "2024-01-15T10:00:00Z"
  }
}
```

<ResponseField name="contact.id" type="string">
  Unique identifier for the contact. Use this ID to add the contact to campaigns.
</ResponseField>

<ResponseField name="contact.team_id" type="string">
  The team this contact belongs to.
</ResponseField>

<ResponseField name="contact.company_id" type="string">
  The associated company ID.
</ResponseField>

<ResponseField name="contact.first_name" type="string">
  Contact's first name.
</ResponseField>

<ResponseField name="contact.last_name" type="string">
  Contact's last name.
</ResponseField>

<ResponseField name="contact.email" type="string">
  Contact's email address.
</ResponseField>

<ResponseField name="contact.phone" type="string">
  Primary phone number.
</ResponseField>

<ResponseField name="contact.phone_secondary" type="string">
  Secondary phone number, if provided.
</ResponseField>

<ResponseField name="contact.job_title" type="string">
  Job title or role.
</ResponseField>

<ResponseField name="contact.lead_status" type="string">
  Current lead status.
</ResponseField>

<ResponseField name="contact.source" type="string">
  Origin of the contact.
</ResponseField>

<ResponseField name="contact.timezone" type="string">
  Contact's timezone for scheduling.
</ResponseField>

<ResponseField name="contact.do_not_call" type="boolean">
  When `true`, this contact is excluded from campaigns.
</ResponseField>

<ResponseField name="contact.notes" type="string">
  Free-text notes.
</ResponseField>

<ResponseField name="contact.custom_fields" type="object">
  Key-value pairs of custom data, including any fields extracted by the AI from past calls.
</ResponseField>

<ResponseField name="contact.tags" type="array">
  Array of string tags.
</ResponseField>

<ResponseField name="contact.created_at" type="string">
  ISO 8601 timestamp of when the contact was created.
</ResponseField>

<ResponseField name="contact.updated_at" type="string">
  ISO 8601 timestamp of the most recent update.
</ResponseField>

***

## List contacts

`GET /api/crm/contacts`

Returns a paginated list of contacts. You can filter by company, search by name, email, or phone, and filter by lead status or calling eligibility.

### Query parameters

<ParamField query="teamId" type="string" required>
  The team ID to list contacts for.
</ParamField>

<ParamField query="companyId" type="string">
  Filter contacts belonging to a specific company.
</ParamField>

<ParamField query="search" type="string">
  Full-text search across name, email, and phone number fields.
</ParamField>

<ParamField query="leadStatus" type="string">
  Filter by lead status value (for example, `new`, `qualified`).
</ParamField>

<ParamField query="doNotCall" type="string">
  Filter by do-not-call flag. Pass `"true"` or `"false"`.
</ParamField>

<ParamField query="hasPhone" type="string">
  Filter to contacts that have (`"true"`) or do not have (`"false"`) a phone number on file.
</ParamField>

<ParamField query="limit" type="integer">
  Maximum records to return. Defaults to `50`.
</ParamField>

<ParamField query="offset" type="integer">
  Records to skip for pagination. Defaults to `0`.
</ParamField>

### Example request

```bash theme={null}
curl "https://<your-domain>/api/crm/contacts?teamId=team_01j...&leadStatus=new&hasPhone=true&limit=25" \
  -H "Authorization: Bearer <token>"
```

### Antwort

```json theme={null}
{
  "success": true,
  "contacts": [
    {
      "id": "cont_01j...",
      "first_name": "Sarah",
      "last_name": "Chen",
      "email": "sarah.chen@example.com",
      "phone": "+14155551234",
      "lead_status": "new",
      "do_not_call": false,
      "tags": ["enterprise", "warm-lead"],
      ...
    }
  ],
  "count": 142,
  "limit": 25,
  "offset": 0
}
```

<ResponseField name="contacts" type="array">
  Array von Kontaktobjekten. Jedes Objekt verfügt über dieselben Felder wie die Erstellungsantwort.
</ResponseField>

<ResponseField name="count" type="integer">
  Gesamtzahl der Kontakte, die den Filtern entsprechen (vor der Paginierung).
</ResponseField>

<ResponseField name="limit" type="integer">
  Der auf diese Antwort angewendete „Grenzwert“.
</ResponseField>

<ResponseField name="offset" type="integer">
  Der auf diese Antwort angewendete „Offset“-Wert.
</ResponseField>

<Tip>
  Um Kontakte nach deren Erstellung zu einer Kampagne hinzuzufügen, verwenden Sie den Endpunkt [Kontakte zur Kampagne hinzufügen](/de/api-reference/campaigns#add-contacts-to-a-campaign) mit den hier zurückgegebenen Kontakt-IDs.
</Tip>