Skip to main content

​
Preparing Contacts

Clean contact data is what makes campaigns predictable. This guide shows how to prepare contacts and load them into Truedy using either:
  • the Contacts API (recommended for reuse + analytics)
  • the Batch Call contacts upload endpoint (good for quick drafts)

​
Who this is for

  • Teams building outbound campaigns with folders/segments.
  • Developers importing leads from CSV or CRM exports.

​
The one rule: use E.164 phone numbers

Every outbound call ultimately depends on a phone number in E.164 format. Examples:
  • +14155550123
  • +15551234567
Avoid:
  • 415-555-0123
  • (415) 555-0123
  • local formats without country code
This matters because the API validates phone numbers and because telephony providers only accept normalized numbers. When you import contacts into a folder, you can reuse that curated set across campaigns. High-level flow:
  1. Create a contact folder
  2. Import contacts into that folder (CSV or JSON)
  3. Create a batch campaign using that contact_folder_id

​
1) Create a folder

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": "Q1 Sales Leads",
    "description": "Imported from CRM export"
  }'

​
2) Import contacts (JSON array)

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", "last_name": "Doe", "email": "jane@example.com" },
      { "phone_number": "+14155550124", "first_name": "John", "last_name": "Smith", "email": "john@example.com" }
    ]
  }'
For CSV import, use the same endpoint and provide csv_base64.

​
Alternative workflow: upload contacts directly to a draft campaign

If you want a one-off campaign draft, you can upload contacts to the batch call directly. Endpoint:

​
Upload inline contacts to a draft campaign

curl -X POST "https://api.truedy.ai/api/public/v1/batch-calls/BATCH_CALL_ID/contacts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      { "phone_number": "+14155550123", "first_name": "Jane" },
      { "phone_number": "+14155550124", "first_name": "John" }
    ],
    "add_to_folder": true
  }'

​
Deduping and data quality

Best practices:
  • Deduplicate by phone_number in your own system before importing (prevents wasted calls).
  • Keep consistent first/last name fields if your prompt relies on personalization.
  • If you rely on segmenting, use metadata/custom fields consistently (and document the keys you use).

​
Next steps