Skip to main content
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 caseEndpoint family
Create or update a basic phone-based contact with an integer contact IDv1 contact endpoints
Retrieve or update a contact by UUID, or manage phone/email channels on one contactv2 contact endpoints
Find a contact when you only know a phone number or email addressPOST /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.