> ## 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.

# Contacts API overview

> Manage contacts in Heymarket: create, retrieve, update, delete, search, and control opt-out and block status across v1 and v2 endpoints.

The Contacts API lets you programmatically manage the people you message in Heymarket. You can create and update contact records, attach custom field values, search by phone or email, and control messaging status such as opt-outs and blocks. The API exposes both a legacy v1 surface and a newer v2 surface that introduces UUID-based identifiers and contact channels.

## The Contact object

Every contact is represented by the following fields.

| Field              | Type    | Description                                                   |
| ------------------ | ------- | ------------------------------------------------------------- |
| `id`               | integer | Unique integer identifier for the contact.                    |
| `display_name`     | string  | Full display name shown in the inbox.                         |
| `first`            | string  | First name.                                                   |
| `last`             | string  | Last name.                                                    |
| `email`            | string  | Email address.                                                |
| `phone`            | string  | Primary phone number in E.164 format without the leading `+`. |
| `custom`           | object  | Custom field values keyed by field ID (string).               |
| `team_id`          | integer | ID of the team that owns this contact.                        |
| `creator_id`       | integer | ID of the user who created the contact.                       |
| `shared`           | boolean | Whether the contact is shared across teams.                   |
| `created`          | string  | ISO 8601 timestamp of when the contact was created.           |
| `updated`          | string  | ISO 8601 timestamp of the last update.                        |
| `rev`              | integer | Revision number, incremented on every write.                  |
| `op`               | string  | Last operation performed on the contact.                      |
| `assigned_user_id` | integer | ID of the user currently assigned to this contact.            |
| `tags`             | array   | List of tag objects attached to the contact.                  |
| `is_opted_out`     | boolean | Whether the contact has opted out of messages.                |

<Note>
  Phone numbers must be in E.164 format **without** the leading `+` sign. For example, use `14155553434` instead of `+14155553434`.
</Note>

## Endpoints

| Method   | Endpoint                  | Description                         |
| -------- | ------------------------- | ----------------------------------- |
| `POST`   | `/v1/contact`             | Create a contact                    |
| `GET`    | `/v1/contact/{id}`        | Get a contact by integer ID         |
| `PUT`    | `/v1/contact/{id}`        | Update a contact                    |
| `DELETE` | `/v1/contact/{id}`        | Delete a contact                    |
| `POST`   | `/v1/contacts`            | List and paginate contacts          |
| `POST`   | `/v1/contacts/count`      | Get the total contact count         |
| `POST`   | `/v1/contact/get`         | Get a contact by phone number or ID |
| `POST`   | `/v1/contact/status`      | Get contact messaging status        |
| `POST`   | `/v1/contact/set_status`  | Set contact messaging status        |
| `POST`   | `/v1/batch/contacts`      | Batch create contacts               |
| `POST`   | `/v1/contact-fields`      | List custom contact fields          |
| `POST`   | `/v1/contacts/fields`     | Create custom contact fields        |
| `POST`   | `/v2/contact`             | Create a contact (v2)               |
| `GET`    | `/v2/contact/{contactID}` | Get a contact by UUID (v2)          |
| `PUT`    | `/v2/contact/{contactID}` | Update a contact (v2)               |
| `DELETE` | `/v2/contact/{contactID}` | Delete a contact (v2)               |
| `POST`   | `/v2/contacts`            | Bulk create or update contacts (v2) |
| `DELETE` | `/v2/contacts`            | Bulk delete contacts (v2)           |
| `POST`   | `/v2/contacts/list`       | List contacts with pagination (v2)  |
| `POST`   | `/v2/contacts/search`     | Search contacts by channel (v2)     |

## Authentication

All requests require a Bearer token in the `Authorization` header. For new integrations, generate a signed JWT from an API Secret and use it as the Bearer token.

```bash theme={null}
Authorization: Bearer YOUR_SIGNED_JWT
```