Create and manage contacts

Contacts are the people your team messages. Use contact endpoints to keep customer identity, phone numbers, email addresses, tags, ownership, opt-out state, and custom fields in sync with your system.

Choose v1 or v2 contacts

Use the contact surface that matches the identifiers you have.

Use case	Endpoint family
Create or update a basic phone-based contact with an integer contact ID	v1 contact endpoints
Retrieve or update a contact by UUID, or manage phone/email channels on one contact	v2 contact endpoints
Find a contact when you only know a phone number or email address	`POST /v2/contacts/search`

The v1 endpoints use integer id values. The v2 endpoints use the contact UUID as contactID.

Create a contact

Create a v1 contact with POST /v1/contact. A phone number is required and must use E.164 digits without the leading plus sign.

curl -X POST https://api.heymarket.com/v1/contact \
  -H "Authorization: Bearer YOUR_SIGNED_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "15105553344",
    "first": "Jordan",
    "last": "Rivera",
    "email": "jordan.rivera@example.com",
    "tags": [
      { "tag_id": 55 },
      { "tag_id": 56 }
    ]
  }'

The response includes the contact id, revision, and UUID.

{
  "id": 98765,
  "rev": 1,
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Update a contact

Use PUT /v1/contact/{id} to update an existing v1 contact. Include phone in the request body.

curl -X PUT "https://api.heymarket.com/v1/contact/98765?overwrite=false" \
  -H "Authorization: Bearer YOUR_SIGNED_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "15105553344",
    "first": "Jordan",
    "custom": {
      "123": "Premium",
      "456": "2026-06-01"
    }
  }'

The overwrite query parameter controls custom-field updates:

overwrite=false merges the provided custom fields with existing values.
overwrite=true replaces existing custom field values with the object you provide.

Contact names are overwritten during update regardless of the overwrite value.

Work with custom fields

Custom field keys are numeric field IDs, not field names. Get the IDs before writing custom values.

curl -X POST https://api.heymarket.com/v1/contact-fields \
  -H "Authorization: Bearer YOUR_SIGNED_JWT" \
  -H "Content-Type: application/json" \
  -d '{}'

Example response:

[
  { "id": 123, "title": "Plan" },
  { "id": 456, "title": "Renewal Date" }
]

Then pass those IDs as string keys in the contact custom object.

Search by phone or email

Use POST /v2/contacts/search when you have a channel value and need the matching contact.

curl -X POST https://api.heymarket.com/v2/contacts/search \
  -H "Authorization: Bearer YOUR_SIGNED_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_channels": [
      {
        "channel_type": "phone",
        "channel_ids": ["15105553344"]
      }
    ]
  }'

You can omit channel_type when Heymarket can infer it from the value format.

Add a contact channel

Use POST /v2/contact/{contactID}/channel to add another phone number, email address, or supported channel to an existing v2 contact.

curl -X POST https://api.heymarket.com/v2/contact/a1b2c3d4-e5f6-7890-abcd-ef1234567890/channel \
  -H "Authorization: Bearer YOUR_SIGNED_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_type": "email",
    "channel_id": "jordan.rivera@example.com"
  }'

List and delete contacts

Use POST /v1/contacts to paginate contacts. Pass the previous page’s last timestamp as date to retrieve the next page. For example, if the last contact on the current page has updated: "2026-04-12T15:30:00Z", use that timestamp as the next date cursor.

curl -X POST https://api.heymarket.com/v1/contacts \
  -H "Authorization: Bearer YOUR_SIGNED_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "date": "2026-04-01T00:00:00Z"
  }'

Delete a contact with DELETE /v1/contact/{id}.

curl -X DELETE https://api.heymarket.com/v1/contact/98765 \
  -H "Authorization: Bearer YOUR_SIGNED_JWT"

Contacts

Understand contact identifiers, channels, tags, and status.

Contacts reference

Review contact endpoints and field-level details.

Search contacts reference

Look up contacts by phone number, email address, or another channel value.

Contact channel reference

Add a channel to an existing v2 contact.

Get Started

Core Concepts

Guides

Choose v1 or v2 contacts

Create a contact

Update a contact

Work with custom fields

Search by phone or email

Add a contact channel

List and delete contacts

Contacts

Contacts reference

Search contacts reference

Contact channel reference

​Choose v1 or v2 contacts

​Create a contact

​Update a contact

​Work with custom fields

​Search by phone or email

​Add a contact channel

​List and delete contacts

​Related pages

Contacts

Contacts reference

Search contacts reference

Contact channel reference

Choose v1 or v2 contacts

Create a contact

Update a contact

Work with custom fields

Search by phone or email

Add a contact channel

List and delete contacts

Related pages