Skip to main content
Contacts are the people your team communicates with. Each contact stores identifying information — name, phone number, email address — alongside custom fields your team defines. When you send or receive a message, Heymarket associates it with a contact automatically based on the phone number or channel identifier.

​
The Contact object

The following attributes are returned when you fetch a contact from the API.
AttributeDescription
idUnique identifier for the contact
display_nameDisplay name, usually first name + last name
firstFirst name
lastLast name
emailEmail address
phonePhone number
customCustom fields as an object mapping field ID to value
team_idYour Heymarket team ID
creator_idID of the user who created the contact
sharedWhether the contact is shared with team members
createdCreation timestamp
updatedLast updated timestamp
revLast revision number
assigned_user_idID of the user assigned as contact owner
tagsArray of up to 5 tag objects
is_opted_outWhether this contact is opted out of messaging

​
Custom fields

Your team can define custom fields to store additional data on contacts — for example, account numbers, plan types, or any other attribute relevant to your workflow. To retrieve the custom field IDs defined for your team, call: 
POST /v1/contact-fields
When creating or updating a contact, pass the numeric field ID as a string key inside the custom object: 
{
  "custom": {
    "12": "Enterprise",
    "47": "Account-9823"
  }
}

​
Omnichannel contact channels

Version 2 contacts support multiple communication channels per contact. Instead of a single phone field, these contacts include a contact_channels array that can contain entries for phone (SMS/MMS), email, Facebook Messenger, and other supported channels. This lets you associate multiple identifiers with a single contact and track conversations across channels in one place.

​
Contact status

A contact’s status reflects their messaging relationship with your team:
  • active — the contact is reachable and can receive messages
  • blocked — the contact has been blocked and cannot receive messages
  • unblocked — a previously blocked contact that has been unblocked
  • subscribed — the contact has opted in to receive messages
  • unsubscribed — the contact has opted out of receiving messages

​
Tags

You can attach up to 5 tags to a contact to help your team categorize and filter contacts. Each tag object includes an ID, a name, and a color. Tags are defined at the team level and shared across contacts.
Phone numbers must be in E.164 format without the leading plus sign. For example, use 14155553434 instead of +1 (415) 555-3434.