Skip to main content

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.

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

​
teamId
string
required
The team ID that owns this contact.
​
companyId
string
required
The ID of the company this contact belongs to.
​
firstName
string
required
Contact’s first name.
​
lastName
string
required
Contact’s last name.
​
email
string
Contact’s email address.
​
phone
string
Primary phone number in E.164 format (for example, "+12025551234").
​
phoneSecondary
string
Secondary phone number in E.164 format.
​
jobTitle
string
Contact’s job title or role.
​
leadStatus
string
The lead status for this contact. Defaults to new. Common values: new, contacted, qualified, unqualified, converted.
​
source
string
Where this contact came from (for example, "trade-show", "website", "referral").
​
timezone
string
Contact’s IANA timezone (for example, "America/Chicago"). Used for call scheduling.
​
preferredContactMethod
string
Contact’s preferred method (for example, "phone", "email").
​
doNotCall
boolean
When true, this contact is excluded from all campaigns. Defaults to false.
​
notes
string
Free-text notes about this contact.
​
customFields
object
A key-value object for any additional fields. Talkturo’s AI info extractor can populate these fields automatically during calls.
​
tags
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"
  }
}
​
contact.id
string
Unique identifier for the contact. Use this ID to add the contact to campaigns.
​
contact.team_id
string
The team this contact belongs to.
​
contact.company_id
string
The associated company ID.
​
contact.first_name
string
Contact’s first name.
​
contact.last_name
string
Contact’s last name.
​
contact.email
string
Contact’s email address.
​
contact.phone
string
Primary phone number.
​
contact.phone_secondary
string
Secondary phone number, if provided.
​
contact.job_title
string
Job title or role.
​
contact.lead_status
string
Current lead status.
​
contact.source
string
Origin of the contact.
​
contact.timezone
string
Contact’s timezone for scheduling.
​
contact.do_not_call
boolean
When true, this contact is excluded from campaigns.
​
contact.notes
string
Free-text notes.
​
contact.custom_fields
object
Key-value pairs of custom data, including any fields extracted by the AI from past calls.
​
contact.tags
array
Array of string tags.
​
contact.created_at
string
ISO 8601 timestamp of when the contact was created.
​
contact.updated_at
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

​
teamId
string
required
The team ID to list contacts for.
​
companyId
string
Filter contacts belonging to a specific company.
​
search
string
Full-text search across name, email, and phone number fields.
​
leadStatus
string
Filter by lead status value (for example, new, qualified).
​
doNotCall
string
Filter by do-not-call flag. Pass "true" or "false".
​
hasPhone
string
Filter to contacts that have ("true") or do not have ("false") a phone number on file.
​
limit
integer
Maximum records to return. Defaults to 50.
​
offset
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
}
​
contacts
array
Array of contact objects. Each object has the same fields as the create response.
​
count
integer
Total number of contacts matching the filters (before pagination).
​
limit
integer
The limit value applied to this response.
​
offset
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.