Skip to main content
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.
SurfaceIdentifierNotes
v1 contact endpointsInteger contact IDUsed by endpoints such as GET /v1/contact/{id}.
v2 contact endpointsContact UUID as contactIDUsed by endpoints such as GET /v2/contact/{contactID}. Do not pass the v1 integer id to these paths.
SMS and MMS message endpointsPhone number, conversation ID, list ID, or group targetsThe required target depends on the send flow.
Email message endpointEmail targets or existing convo_idEmail 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: 
{
  "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.
Phone numbers must use E.164 digits without the leading plus sign. For example, use 14155553434 instead of +1 (415) 555-3434.

Manage contacts

Create, update, delete, search, and list contacts.

Contacts reference

Review contact endpoints and request details.