Contacts

Manage contact folders and contacts. Contacts are organized into folders and used as the target list for batch call campaigns. For UUID / phone / datetime formats used below, see Data formats.

List Folders

Parameters

Query parameters:

Parameter	Type	Description
`sort_by`	string	Sort by: `name`, `created_at`, `contact_count`. Default `created_at`
`order`	string	`asc` or `desc`. Default `desc`

cURL

curl "https://api.truedy.ai/api/public/v1/contacts/folders?sort_by=created_at&order=desc" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

data (array of folder objects with id, name, description, contact_count, created_at, updated_at), meta.

Create Folder

Parameters

Request body:

Field	Type	Required	Description
`name`	string	Yes	Folder display name
`description`	string	No	Optional description

cURL

curl -X POST "https://api.truedy.ai/api/public/v1/contacts/folders" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "West Coast Leads",
    "description": "Imported from CRM segment A"
  }'

Delete Folder

Deletes the folder and all contacts inside it. This is irreversible.

curl -X DELETE "https://api.truedy.ai/api/public/v1/contacts/folders/6f4af8be-0a96-49b0-ac2a-a359f46cc966" \
  -H "Authorization: Bearer YOUR_API_KEY"

List Contacts

Parameters

Query parameters:

Parameter	Type	Description
`folder_id`	UUID	Filter to a specific folder
`search`	string	Search by name, phone, or email
`last_call_outcome`	string	Filter by outcome: `contacted`, `voicemail`, `no_answer`, `escalated`, `interested`, `not_interested`
`page`	integer	Page number (1-based). Default `1`
`limit`	integer	1–100. Default `50`

This endpoint uses page-based pagination (not offset). Response pagination includes: page, limit, total, pages.

cURL

curl "https://api.truedy.ai/api/public/v1/contacts?folder_id=6f4af8be-0a96-49b0-ac2a-a359f46cc966&page=1&limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

Add Contact

Add a single contact to a folder.

Parameters

Request body:

Field	Type	Required	Description
`folder_id`	UUID	Yes	Target folder
`phone_number`	string (E.164)	Yes	Contact phone number, e.g. `+14155550123`
`first_name`	string	No	First name
`last_name`	string	No	Last name
`email`	string	No	Email address
`company_name`	string	No	Company or organization
`industry`	string	No	Industry category
`location`	string	No	City, region, or free-text location
`pin_code`	string	No	Postal or ZIP code
`keywords`	string	No	Comma-separated tags for search and filtering
`metadata`	object	No	Any custom key-value data (e.g. `{"crm_id": "abc123", "segment": "enterprise"}`)

Example

{
  "folder_id": "6f4af8be-0a96-49b0-ac2a-a359f46cc966",
  "phone_number": "+14155550123",
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "jane@example.com",
  "company_name": "Acme Inc",
  "industry": "Technology",
  "location": "San Francisco, CA",
  "keywords": "enterprise,q1-target",
  "metadata": { "crm_id": "abc123", "segment": "enterprise" }
}

cURL

curl -X POST "https://api.truedy.ai/api/public/v1/contacts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "folder_id": "6f4af8be-0a96-49b0-ac2a-a359f46cc966",
    "phone_number": "+14155550123",
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane@example.com"
  }'

Update Contact

Update any fields on an existing contact. Only fields included in the request are changed.

Parameters

Request body: Any subset of the Add Contact fields: folder_id, phone_number, first_name, last_name, email, company_name, industry, location, pin_code, keywords, metadata

cURL

curl -X PATCH "https://api.truedy.ai/api/public/v1/contacts/95c0a203-c1d8-4e72-8604-6de979ab1653" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "company_name": "Acme International",
    "metadata": { "segment": "enterprise", "upgraded": true }
  }'

Delete Contact

curl -X DELETE "https://api.truedy.ai/api/public/v1/contacts/95c0a203-c1d8-4e72-8604-6de979ab1653" \
  -H "Authorization: Bearer YOUR_API_KEY"

Import Contacts

Bulk-import contacts into a folder from an array or a base64-encoded CSV file.

Parameters

Request body:

Field	Type	Required	Description
`folder_id`	UUID	Yes	Target folder
`contacts`	object[]	No*	Array of contact objects (same fields as Add Contact)
`csv_base64`	string	No*	Base64-encoded CSV. Expected columns: `phone_number`, `first_name`, `last_name`, `email`
`mapping_config`	object	No	Column mapping overrides for CSV import

* Either contacts or csv_base64 is required. Response: data: { successful, failed, errors[] }, meta.

cURL

curl -X POST "https://api.truedy.ai/api/public/v1/contacts/import" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "folder_id": "6f4af8be-0a96-49b0-ac2a-a359f46cc966",
    "contacts": [
      { "phone_number": "+14155550123", "first_name": "Jane", "metadata": { "source": "webform" } },
      { "phone_number": "+14155550124", "first_name": "John" }
    ]
  }'

Export Contacts

Export contacts as a CSV file. Exports all contacts in the org, or filter by folder.

Parameters

Query parameters:

Parameter	Type	Description
`folder_id`	UUID	Export only contacts from this folder. Omit to export all contacts.

cURL

curl "https://api.truedy.ai/api/public/v1/contacts/export?folder_id=6f4af8be-0a96-49b0-ac2a-a359f46cc966" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o contacts.csv

Returns a CSV file with Content-Disposition: attachment.

Contact Object

Field	Type	Description
`id`	UUID	Contact ID
`folder_id`	UUID	Folder this contact belongs to
`phone_number`	string	E.164 phone number
`first_name`	string	First name
`last_name`	string	Last name
`email`	string	Email address
`company_name`	string	Company or organization
`industry`	string	Industry
`location`	string	Location
`pin_code`	string	Postal code
`keywords`	string	Comma-separated tags
`metadata`	object	Custom key-value data
`last_call_outcome`	string	Outcome of the most recent call: `contacted`, `voicemail`, `no_answer`, `escalated`, `interested`, `not_interested`
`last_called_at`	datetime	When this contact was last called
`created_at`	datetime	When the contact was created
`updated_at`	datetime	Last updated

API documentation

Endpoints

Contacts

Contacts

List Folders

Parameters

cURL

Response

Create Folder

Parameters

cURL

Delete Folder

List Contacts

Parameters

cURL

Add Contact

Parameters

Example

cURL

Update Contact

Parameters

cURL

Delete Contact

Import Contacts

Parameters

cURL

Export Contacts

Parameters

cURL

Contact Object

​Contacts

​List Folders

​Parameters

​cURL

​Response

​Create Folder

​Parameters

​cURL

​Delete Folder

​List Contacts

​Parameters

​cURL

​Add Contact

​Parameters

​Example

​cURL

​Update Contact

​Parameters

​cURL

​Delete Contact

​Import Contacts

​Parameters

​cURL

​Export Contacts

​Parameters

​cURL

​Contact Object

Contacts

List Folders

Parameters

cURL

Response

Create Folder

Parameters

cURL

Delete Folder

List Contacts

Parameters

cURL

Add Contact

Parameters

Example

cURL

Update Contact

Parameters

cURL

Delete Contact

Import Contacts

Parameters

cURL

Export Contacts

Parameters

cURL

Contact Object