Skip to main content
The Heymarket API gives you full control over your contact list. You can create contacts with standard fields like name and email, attach custom field values, update records as information changes, and delete contacts you no longer need. All phone numbers must be in E.164 format without the leading plus sign.

​
Create a contact

Send a POST request to /v1/contact with at least a phone number. All other fields are optional. 
curl -X POST https://api.heymarket.com/v1/contact \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "15105553344",
    "first": "Jordan",
    "last": "Rivera",
    "email": "jordan.rivera@example.com",
    "tags": [{"tag_id": 55}, {"tag_id": 56}]
  }'

​
Create contact fields

FieldTypeDescription
phonestringRequired. E.164 format without leading plus (e.g., 15105553344).
firststringFirst name.
laststringLast name.
display_namestringName shown in conversations if different from first + last.
emailstringEmail address.
customobjectCustom field values keyed by numeric field ID as a string.
avatarstringURL of a profile image.
assignee_idintegerUser ID to assign this contact to by default.
tagsarray of objectsTags to apply to the contact. Each item is {"tag_id": integer}. Maximum of 5.
is_opted_outbooleanWhen true, marks the contact as opted out of messaging.

​
Get a contact by ID

Retrieve a single contact by passing its ID in the URL path. 
curl -X GET https://api.heymarket.com/v1/contact/98765 \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Update a contact

Send a PUT request to /v1/contact/{id} to update fields on an existing contact. phone is required; all other fields are optional. 
curl -X PUT https://api.heymarket.com/v1/contact/98765 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "15105553344",
    "first": "Jordan",
    "custom": {
      "123": "Premium",
      "456": "2024-01-15"
    }
  }'
Use the overwrite query parameter to control how custom fields are merged:
  • ?overwrite=false (default) — merges the provided custom fields with existing values, preserving fields you do not include.
  • ?overwrite=true — replaces all existing custom field values with the ones you provide.

​
Delete a contact

Send a DELETE request to remove a contact permanently. 
curl -X DELETE https://api.heymarket.com/v1/contact/98765 \
  -H "Authorization: Bearer YOUR_API_KEY"

​
List all contacts

Send a POST request to /v1/contacts to retrieve a paginated list of contacts. Use the date parameter as a cursor to page through results — pass the date value from the last contact in the previous response to fetch the next page. 
curl -X POST https://api.heymarket.com/v1/contacts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "date": "2026-04-01T00:00:00Z"
  }'

​
Working with custom fields

Custom fields let you store additional structured data on a contact. Each field has a numeric ID that you use as the key when setting values.
1

Get your custom field IDs

Call POST /v1/contact-fields to retrieve all custom fields defined in your account. The response includes each field’s numeric ID and its display name.
curl -X POST https://api.heymarket.com/v1/contact-fields \
  -H "Authorization: Bearer YOUR_API_KEY"
Example response:
{
  "fields": [
    { "id": 123, "name": "Plan" },
    { "id": 456, "name": "Renewal Date" }
  ]
}
2

Set custom field values

Use the numeric field ID as a string key in the custom object when creating or updating a contact.
{
  "phone": "15105553344",
  "custom": {
    "123": "Premium",
    "456": "2024-01-15"
  }
}
The value is always a string, regardless of the field type configured in Heymarket.
Phone numbers must be in E.164 format without the leading plus sign. For example, use 15105553344 rather than +15105553344 or (510) 555-3344.
Use local_id as a stable client-side identifier when creating contacts. This lets you reference the contact by your own ID and makes create-or-update operations idempotent.