> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truedy.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Preparing Contacts

> Build clean contact lists for batch campaigns (E.164, folders, CSV formats)

# 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.

## Recommended workflow: Contacts API + folders

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

```bash theme={null}
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)

```bash theme={null}
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 Contacts to Batch Call](/api-reference/batch-calls#upload-contacts-to-batch-call)

### Upload inline contacts to a draft campaign

```bash theme={null}
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

* Create a campaign: [Creating Your First Campaign](/guides/creating-your-first-campaign)
* Build scheduling rules: [Scheduling & Delivery Logic](/guides/scheduling-and-delivery-logic)