> ## 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 endpoints for CRM contacts

> Create and list CRM contacts in Talkturo using the REST API. Contacts store phone numbers, email, lead status, custom fields, and campaign call history.

Contacts are the individual people in your Talkturo CRM. Each contact belongs to a team and optionally to a company. When you add contacts to a campaign, Talkturo uses their stored phone numbers to place outbound calls. After each call, the AI automatically extracts data from the conversation and updates the contact's fields.

***

## 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"
    }
  }'
```

### Response

```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>"
```

### Response

```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 of contact objects. Each object has the same fields as the create response.
</ResponseField>

<ResponseField name="count" type="integer">
  Total number of contacts matching the filters (before pagination).
</ResponseField>

<ResponseField name="limit" type="integer">
  The `limit` value applied to this response.
</ResponseField>

<ResponseField name="offset" type="integer">
  The `offset` value applied to this response.
</ResponseField>

<Tip>
  To add contacts to a campaign after creating them, use the [add contacts to campaign](/en/api-reference/campaigns#add-contacts-to-a-campaign) endpoint with the contact IDs returned here.
</Tip>