REST API endpoints for CRM contacts

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

string

required

The team ID that owns this contact.

string

required

The ID of the company this contact belongs to.

string

required

Contact’s first name.

string

required

Contact’s last name.

string

Contact’s email address.

string

Primary phone number in E.164 format (for example, "+12025551234").

string

Secondary phone number in E.164 format.

string

Contact’s job title or role.

string

The lead status for this contact. Defaults to new. Common values: new, contacted, qualified, unqualified, converted.

string

Where this contact came from (for example, "trade-show", "website", "referral").

string

Contact’s IANA timezone (for example, "America/Chicago"). Used for call scheduling.

string

Contact’s preferred method (for example, "phone", "email").

boolean

When true, this contact is excluded from all campaigns. Defaults to false.

string

Free-text notes about this contact.

object

A key-value object for any additional fields. Talkturo’s AI info extractor can populate these fields automatically during calls.

array

An array of string tags for categorizing this contact.

Example request

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

{
  "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"
  }
}

string

Unique identifier for the contact. Use this ID to add the contact to campaigns.

string

The team this contact belongs to.

string

The associated company ID.

string

Contact’s first name.

string

Contact’s last name.

string

Contact’s email address.

string

Primary phone number.

string

Secondary phone number, if provided.

string

Job title or role.

string

Current lead status.

string

Origin of the contact.

string

Contact’s timezone for scheduling.

boolean

When true, this contact is excluded from campaigns.

string

Free-text notes.

object

Key-value pairs of custom data, including any fields extracted by the AI from past calls.

array

Array of string tags.

string

ISO 8601 timestamp of when the contact was created.

string

ISO 8601 timestamp of the most recent update.

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

string

required

The team ID to list contacts for.

string

Filter contacts belonging to a specific company.

string

Full-text search across name, email, and phone number fields.

string

Filter by lead status value (for example, new, qualified).

string

Filter by do-not-call flag. Pass "true" or "false".

string

Filter to contacts that have ("true") or do not have ("false") a phone number on file.

integer

Maximum records to return. Defaults to 50.

integer

Records to skip for pagination. Defaults to 0.

Example request

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

Response

{
  "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
}

array

Array of contact objects. Each object has the same fields as the create response.

integer

Total number of contacts matching the filters (before pagination).

integer

The limit value applied to this response.

integer

The offset value applied to this response.

To add contacts to a campaign after creating them, use the add contacts to campaign endpoint with the contact IDs returned here.

Overview

Endpoints

Webhooks

REST API endpoints for CRM contacts

Create a contact

Request body

Example request

Response

List contacts

Query parameters

Example request

Response

​Create a contact

​Request body

​Example request

​Response

​List contacts

​Query parameters

​Example request

​Response

Create a contact

Request body

Example request

Response

List contacts

Query parameters

Example request

Response