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

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
Python

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}`);

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}")

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

Explore the full request schema, filtering options, pagination, and response format for the contacts endpoint.

Get Started

SDKs

Core Features

Contacts

Contacts

Create Contacts

Contact Groups

Tags & Metadata

Bulk Import

Basic Usage

Contact Fields

Best Practices

API Reference: List Contacts

​Contacts

Create Contacts

Contact Groups

Tags & Metadata

Bulk Import

​Basic Usage

​Contact Fields

​Best Practices

API Reference: List Contacts

Contacts

Basic Usage

Contact Fields

Best Practices