Skip to main content

​
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:
ParameterTypeDescription
sort_bystringSort by: name, created_at, contact_count. Default created_at
orderstringasc 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:
FieldTypeRequiredDescription
namestringYesFolder display name
descriptionstringNoOptional 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:
ParameterTypeDescription
folder_idUUIDFilter to a specific folder
searchstringSearch by name, phone, or email
last_call_outcomestringFilter by outcome: contacted, voicemail, no_answer, escalated, interested, not_interested
pageintegerPage number (1-based). Default 1
limitinteger1–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:
FieldTypeRequiredDescription
folder_idUUIDYesTarget folder
phone_numberstring (E.164)YesContact phone number, e.g. +14155550123
first_namestringNoFirst name
last_namestringNoLast name
emailstringNoEmail address
company_namestringNoCompany or organization
industrystringNoIndustry category
locationstringNoCity, region, or free-text location
pin_codestringNoPostal or ZIP code
keywordsstringNoComma-separated tags for search and filtering
metadataobjectNoAny 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:
FieldTypeRequiredDescription
folder_idUUIDYesTarget folder
contactsobject[]No*Array of contact objects (same fields as Add Contact)
csv_base64stringNo*Base64-encoded CSV. Expected columns: phone_number, first_name, last_name, email
mapping_configobjectNoColumn 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:
ParameterTypeDescription
folder_idUUIDExport 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

FieldTypeDescription
idUUIDContact ID
folder_idUUIDFolder this contact belongs to
phone_numberstringE.164 phone number
first_namestringFirst name
last_namestringLast name
emailstringEmail address
company_namestringCompany or organization
industrystringIndustry
locationstringLocation
pin_codestringPostal code
keywordsstringComma-separated tags
metadataobjectCustom key-value data
last_call_outcomestringOutcome of the most recent call: contacted, voicemail, no_answer, escalated, interested, not_interested
last_called_atdatetimeWhen this contact was last called
created_atdatetimeWhen the contact was created
updated_atdatetimeLast updated