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

# Contacts & lists

> The people you reach — how they get in, what you can store on them, and how to group them.

A **contact** is one person you can message, identified by their **phone
number**. On top of that you can store a name, any **custom fields** you like,
**tags**, their **opt-in status**, and their **timezone**. You group contacts
into **lists** (static sets) and slice them into [segments](/segments) (live
rules). Every send targets a list or a segment.

## Getting contacts in

<Steps>
  <Step title="Import a CSV">
    Upload a file of contacts. Map the phone column (required) and any others;
    columns you don't map to a standard field are stored as **custom fields**.
    Optionally drop them onto a list as you import.
  </Step>

  <Step title="Via the API or your CRM">
    `POST /v1/contacts` **upserts by phone** — an existing contact is updated in
    place, never duplicated — so it doubles as your bulk-import and sync endpoint.
    Pass `list` or `list_id` to add them to a list in the same call. See
    [Create or update contacts](/api-reference).
  </Step>

  <Step title="Automatically">
    Contacts are also created as people **reply** to campaigns, and can be tied
    to on-site behavior by the [web pixel](/pixel) when they identify.
  </Step>
</Steps>

## What you can store

* **Standard fields** — phone, first/last name, timezone.
* **Custom fields** — anything else you send (plan, state, source, renewal date…).
  Unknown fields on import or upsert become custom fields automatically, and
  dot-notation nests them. Use them two ways: as **personalization tokens**
  (`{plan}` in a message) and as **segment conditions**.
* **Tags** — lightweight labels you attach to contacts and later segment or
  filter on.
* **Opt-in status & timezone** — used for compliance (below).

## Lists

A **list** is a static, hand-built set of contacts — a fixed audience you add
people to and that only changes when you edit it.

|            | List                           | [Segment](/segments)          |
| ---------- | ------------------------------ | ----------------------------- |
| Membership | Manual — you add/remove people | Rules — recalculates itself   |
| Best for   | a fixed, curated set           | "everyone who did X recently" |

Add contacts to a list on import, from the contact view, or with
`POST /v1/lists/{id}/contacts`. Deleting a list never deletes the contacts — only
their membership.

## Opt-outs, timezone & compliance

* **Opt-outs are automatic.** A contact who replies STOP is opted out and never
  messaged again — you don't manage this by hand. To keep specific numbers off
  sends for other reasons, use a suppression list.
* **Deleting a contact is not an opt-out.** A deleted contact you later re-import
  can be messaged again; use suppression to stop contact permanently.
* **Timezone** powers quiet hours — messages respect the recipient's local
  8am–9pm window. Where a contact's timezone is known (e.g. derived from their
  area) it's used; otherwise your workspace default applies.

## Over the API & MCP

Manage contacts and lists programmatically — [Contacts](/api-reference) and
[Lists](/api-reference) — or in natural language through the [MCP server](/mcp).