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

> Understand how Heymarket contacts store customer identity, channels, custom fields, tags, ownership, and messaging status.

Contacts are the people your team messages in Heymarket. A contact can store names, phone numbers, email addresses, custom fields, tags, owner assignment, and messaging status.

When you send or receive a message, Heymarket uses the channel identifier, such as a phone number or email address, to associate that activity with a contact and conversation.

## How contacts fit into the API

Contacts connect several API workflows:

* **Messages** use a contact's phone number, email address, or existing conversation.
* **Conversations** are usually tied to one contact and one inbox.
* **Lists** group contacts or phone-number targets for broadcasts.
* **Templates** can use contact values as merge tokens.
* **Tags and custom fields** help segment, search, and personalize contacts.

## Contact identifiers

The API exposes both older integer IDs and newer v2 contact identifiers. Use the identifier expected by the endpoint you are calling.

| Surface                       | Identifier                                               | Notes                                                                                                    |
| ----------------------------- | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| v1 contact endpoints          | Integer contact ID                                       | Used by endpoints such as `GET /v1/contact/{id}`.                                                        |
| v2 contact endpoints          | Contact UUID as `contactID`                              | Used by endpoints such as `GET /v2/contact/{contactID}`. Do not pass the v1 integer `id` to these paths. |
| SMS and MMS message endpoints | Phone number, conversation ID, list ID, or group targets | The required target depends on the send flow.                                                            |
| Email message endpoint        | Email `targets` or existing `convo_id`                   | Email uses `POST /v1/email/send`, not `POST /v1/message/send`.                                           |

## Custom fields

Custom fields let your team store account numbers, plan names, lifecycle stages, or other data that belongs on the contact.

To retrieve the custom field IDs defined for your team, call `POST /v1/contact-fields`. When creating or updating a contact, pass custom values as an object keyed by field ID:

```json theme={null}
{
  "custom": {
    "12": "Enterprise",
    "47": "Account-9823"
  }
}
```

## Contact channels

v2 contact endpoints support contact channels. A channel is a specific way to reach a contact, such as a phone number or email address.

Use contact channels when a customer can be reached through multiple identifiers and you need to manage those identifiers as part of one contact record.

## Tags and status

Tags categorize contacts for filtering and routing. Each contact can have up to five tags.

Contact status describes whether a contact can be messaged. For example, contacts can be active, blocked, subscribed, or unsubscribed. Check status before sending if your workflow depends on opt-in or block state.

<Note>
  Phone numbers must use E.164 digits without the leading plus sign. For example, use `14155553434` instead of `+1 (415) 555-3434`.
</Note>

## Related pages

<CardGroup cols={2}>
  <Card title="Manage contacts" icon="address-book" href="/guides/manage-contacts">
    Create, update, delete, search, and list contacts.
  </Card>

  <Card title="Contacts reference" icon="code" href="/api-reference/contacts/overview">
    Review contact endpoints and request details.
  </Card>
</CardGroup>