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

# Contacts

# 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](/api-reference/introduction#data-formats).

## List Folders

<Endpoint method="GET" path="/api/public/v1/contacts/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

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

<Endpoint method="POST" path="/api/public/v1/contacts/folders" />

### Parameters

**Request body:**

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

### cURL

```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": "West Coast Leads",
    "description": "Imported from CRM segment A"
  }'
```

## Delete Folder

<Endpoint method="DELETE" path="/api/public/v1/contacts/folders/{folder_id}" />

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

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

<Endpoint method="GET" path="/api/public/v1/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

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

<Endpoint method="POST" path="/api/public/v1/contacts" />

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

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

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

<Endpoint method="PATCH" path="/api/public/v1/contacts/{contact_id}" />

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

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

<Endpoint method="DELETE" path="/api/public/v1/contacts/{contact_id}" />

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

## Import Contacts

<Endpoint method="POST" path="/api/public/v1/contacts/import" />

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

```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", "metadata": { "source": "webform" } },
      { "phone_number": "+14155550124", "first_name": "John" }
    ]
  }'
```

## Export Contacts

<Endpoint method="GET" path="/api/public/v1/contacts/export" />

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

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