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

# Lists API overview

> Organize contacts into named lists for broadcast messaging. Each contact receives messages individually and can reply privately to your team.

Lists organize multiple contacts for broadcast messaging. Each contact on a list receives the message individually and can reply privately. You can create and manage lists programmatically to keep your contact groups in sync with your own data sources.

## The List object

<ResponseField name="id" type="integer">
  Unique identifier for the list.
</ResponseField>

<ResponseField name="name" type="string">
  Display name of the list.
</ResponseField>

<ResponseField name="local_id" type="string">
  Client-provided unique identifier. Use this to map Heymarket lists to records in your own system.
</ResponseField>

<ResponseField name="targets" type="object">
  Object of ListTarget objects, keyed by phone number. Each value is an object with `f` (first name) and `l` (last name).
</ResponseField>

<ResponseField name="team_id" type="integer">
  Identifier of the team that owns this list.
</ResponseField>

<ResponseField name="creator_id" type="integer">
  Identifier of the user who created the list.
</ResponseField>

<ResponseField name="shared" type="boolean">
  Whether the list is shared with all members of the team.
</ResponseField>

<ResponseField name="created" type="string">
  ISO 8601 timestamp when the list was created.
</ResponseField>

<ResponseField name="updated" type="string">
  ISO 8601 timestamp when the list was last updated.
</ResponseField>

<ResponseField name="rev" type="integer">
  Revision number. Increments on each update.
</ResponseField>

<ResponseField name="archived" type="boolean">
  Whether the list has been archived.
</ResponseField>

<Note>
  Use the v2 endpoints (`/v2/lists`) to create, update, and delete lists in new integrations. List pagination is still available only through the deprecated v1 pagination endpoints.
</Note>

## Endpoints

| Method   | Endpoint          | Description                                                                  |
| -------- | ----------------- | ---------------------------------------------------------------------------- |
| `POST`   | `/v1/lists`       | Paginate lists. Deprecated, but currently the only list pagination endpoint. |
| `POST`   | `/v1/lists/count` | Count lists that match the same pagination filters. Deprecated.              |
| `POST`   | `/v2/lists`       | Create a list                                                                |
| `PUT`    | `/v2/lists/{id}`  | Update a list                                                                |
| `DELETE` | `/v2/lists/{id}`  | Delete a list                                                                |

<Warning>
  There is no documented `GET /v2/list`, `POST /v2/list`, or v2 list pagination endpoint. Use the plural `/v2/lists` paths for v2 write operations.
</Warning>