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.
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. |
Phone numbers must be in E.164 format without the leading + sign. For example, use 14155553434 instead of +14155553434.
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 | /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.
Authorization: Bearer YOUR_API_KEY
