Manage contacts, lists and profile data

Contacts are workspace-scoped customer records. Store a valid phone number, email, or external customer ID, along with profile fields, tags, and custom fields. Use lists to organize audience records and segments to query them dynamically.

In the dashboard, create or open a contact list and use Add contacts. Bulk import supports CSV and Excel (.xlsx); map source columns to phone, email, name, and custom fields, then inspect the background import result.

Review imported values, especially international phone numbers, duplicate destinations, blank names, and consent. A successful import does not certify that the whole list can receive marketing or that every number is reachable on WhatsApp.

POST /api/v1/contacts requires contacts:write. Convert normalizes valid phones to E.164 and emails to lowercase. Matching normalized email, phone, or external customer ID can enrich an existing record rather than create a duplicate.

12345678{
  "phone_number": "+2348012345678",
  "email": "[email protected]",
  "external_customer_id": "customer-1042",
  "first_name": "Ada",
  "tags": ["customer"],
  "custom_fields": {"tier": "gold", "order_id": "ORD-1042"}
}

List-specific upsert is available at POST /api/v1/contact_lists/:contact_list_id/contacts. The list controls placement and matching within that list. Custom field keys must be configured in the workspace, and this flow does not change consent or suppression state. Its optional idempotency key prevents conflicting replays.

PATCH /api/v1/contacts/:id is a partial update. Omitted fields keep their values. Send explicit null only when clearing a supported field intentionally. Use the numeric ID returned for the workspace contact.

Use stable identifiers for event intake when duplicate contact rows share an email/phone across lists. An ambiguous identify request requires a contact ID or external ID, and contradictory identifiers are rejected.

custom_fields stores persistent profile attributes, such as tier or order number. These can become merge fields and segment inputs. Template variables are request-specific; OTPs are not automatically persisted as custom fields by the single-message API.

DELETE /api/v1/contacts/:id returns 204 No Content. Deletion is permanent and also removes dependent recipient delivery records. Use opt-out/preferences when you need to stop messaging while retaining customer history.

Next: read consent, segments, or identify and events.