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

# Contacts

> Manage your WhatsApp contacts with full CRUD operations, groups, tags, custom metadata, and bulk import through the Zeplo API.

# Contacts

The Zeplo Contacts API gives you complete control over your contact database. Create, read, update, and delete individual contacts, organize them into groups, attach tags and custom metadata, and import thousands of records in a single bulk operation. Contacts are the foundation for targeted messaging and campaign audiences.

> **[Create Contacts](https://docs.zeplo.ai/docs/api-reference/contacts/create-contact.md)**
>
> Add new contacts programmatically with phone numbers, names, email addresses, and any custom metadata your business needs.

> **Contact Groups**
>
> Organize contacts into groups for segmented messaging and campaign targeting. Groups support dynamic membership rules.

> **Tags & Metadata**
>
> Attach searchable tags and structured key-value metadata to any contact for flexible segmentation and personalization.

> **Bulk Import**
>
> Upload CSV or JSON files to create or update thousands of contacts in a single asynchronous job with detailed error reporting.

## Basic Usage

**JavaScript/TypeScript**

```typescript theme={null}
import { Zeplo } from "@zeplo/sdk";

const zeplo = new Zeplo({ apiKey: process.env.ZEPLO_API_KEY });

// Create a contact
const contact = await zeplo.contacts.create({
  phone: "+1234567890",
  name: "Jane Doe",
  email: "jane@example.com",
  tags: ["vip", "newsletter"],
  metadata: {
    company: "Acme Corp",
    plan: "enterprise",
  },
});

// List contacts with filters
const { contacts } = await zeplo.contacts.list({
  tags: ["vip"],
  limit: 50,
  offset: 0,
});

// Update a contact
await zeplo.contacts.update(contact.id, {
  tags: ["vip", "priority"],
  metadata: { plan: "starter" },
});

// Manage groups
const group = await zeplo.contacts.groups.create({
  name: "Enterprise Customers",
  description: "All enterprise-tier contacts",
});

await zeplo.contacts.groups.addMembers(group.id, {
  contactIds: [contact.id],
});

console.log(`Contact ${contact.id} added to group ${group.name}`);
```

**Python**

```python theme={null}
import os
from zeplo import Zeplo

zeplo = Zeplo(api_key=os.environ["ZEPLO_API_KEY"])

# Create a contact
contact = zeplo.contacts.create(
    phone="+1234567890",
    name="Jane Doe",
    email="jane@example.com",
    tags=["vip", "newsletter"],
    metadata={
        "company": "Acme Corp",
        "plan": "enterprise",
    },
)

# List contacts with filters
result = zeplo.contacts.list(tags=["vip"], limit=50, offset=0)
contacts = result.contacts

# Update a contact
zeplo.contacts.update(
    contact.id,
    tags=["vip", "priority"],
    metadata={"plan": "starter"},
)

# Manage groups
group = zeplo.contacts.groups.create(
    name="Enterprise Customers",
    description="All enterprise-tier contacts",
)

zeplo.contacts.groups.add_members(
    group.id,
    contact_ids=[contact.id],
)

print(f"Contact {contact.id} added to group {group.name}")
```

> [!NOTE]
>
> Bulk import accepts CSV and JSON files up to 50 MB with up to 100,000 rows per job. Use the `contacts.import` method to start an import and poll its status until completion.

## Contact Fields

| Field | Type | Description |
| - | - | - |
| `id` | `string` | Unique contact identifier (auto-generated) |
| `name` | `string` | Display name of the contact |
| `phone` | `string` | Phone number in E.164 format (e.g., `+1234567890`) |
| `email` | `string` | Email address (optional) |
| `tags` | `string[]` | Array of searchable tags |
| `metadata` | `object` | Arbitrary key-value pairs for custom data |
| `groups` | `string[]` | IDs of groups the contact belongs to |
| `createdAt` | `string` | ISO 8601 timestamp of creation |
| `updatedAt` | `string` | ISO 8601 timestamp of last update |

## Best Practices

> Always store phone numbers in **E.164 format** (`+<country_code><number>`). Zeplo validates numbers against the WhatsApp network at creation time. Invalid or non-WhatsApp numbers are flagged but not rejected — check the `valid` field after creation.

> Each contact supports up to **50 metadata keys**. Keys must be strings (max 64 characters) and values can be strings, numbers, or booleans. Store structured data you need for personalization or segmentation — avoid duplicating data that already exists in tags or groups.

> Use groups for broad segmentation (e.g., "Customers", "Leads") and tags for finer-grained labels (e.g., "high-value", "churn-risk"). Groups support bulk operations and are ideal for campaign targeting, while tags are better suited for filtering in automation flows.

> Zeplo automatically deduplicates contacts by phone number. If you create a contact with a phone number that already exists, the existing record is updated instead of creating a duplicate. Use the `upsert` parameter to control this behavior explicitly.

> **[API Reference: List Contacts](https://docs.zeplo.ai/docs/api-reference/contacts/list-contacts.md)**
>
> Explore the full request schema, filtering options, pagination, and response format for the contacts endpoint.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.