Skip to main content
Heymarket provides several endpoints for retrieving contact data. You can fetch a single contact by its integer ID, phone number, or UUID, or you can paginate through all contacts using cursor-based or offset-based pagination.

​
GET /v1/contact/

Returns a single contact by its integer ID.

​
Path parameters

​
id
integer
required
The integer ID of the contact to retrieve.

​
Example

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

{
  "id": 98765,
  "display_name": "API Contact",
  "first": "API",
  "last": "Contact",
  "email": "help@heymarket.com",
  "phone": "15105553344",
  "is_opted_out": false
}

​
POST /v1/contact/get

Returns a contact by phone number or integer ID. This is useful when you know a phone number but not the internal ID.

​
Request body

​
phone
string
The contact’s phone number in E.164 format without the leading +.
​
id
string
The contact’s integer ID as a string.
Provide either phone or id. If you supply both, phone takes precedence.

​
Example

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

​
GET /v2/contact/

Returns a single contact by its UUID. Use this endpoint when working with the v2 API surface.

​
Path parameters

​
contactID
string
required
The UUID of the contact to retrieve.

​
Example

curl -X GET https://api.heymarket.com/v2/contact/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer YOUR_API_KEY"

​
POST /v1/contacts

Returns a paginated list of contacts. By default, each response contains up to 30 contacts. Use the updated timestamp of the last item in the response as the date parameter in your next request to fetch the next page.

​
Request body

​
date
string
An RFC 3339 timestamp used as the pagination cursor. Pass the updated value of the last contact returned in the previous response to get the next page of results.

​
Example

# First page
curl -X POST https://api.heymarket.com/v1/contacts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

# Next page — use the `updated` value from the last item above
curl -X POST https://api.heymarket.com/v1/contacts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"date": "2024-06-01T12:00:00Z"}'
To paginate through all contacts, keep passing the updated timestamp of the last result until the response returns fewer than 30 contacts. That signals you have reached the end of the list.

​
POST /v2/contacts/list

Returns a paginated list of contacts using the v2 API. Supports explicit page and limit parameters for offset-based pagination.

​
Request body

​
limit
integer
default:"30"
Maximum number of contacts to return per page. Defaults to 30. Maximum is 100.
​
page
integer
default:"0"
Zero-indexed page number.
​
date
string
An RFC 3339 timestamp to filter contacts updated after this time.
​
ascending
boolean
Set to true to return contacts in ascending order by updated. Defaults to descending.

​
Example

curl -X POST https://api.heymarket.com/v2/contacts/list \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "limit": 50,
    "page": 0,
    "ascending": true
  }'

​
POST /v1/contacts/count

Returns the total number of contacts in your team.

​
Request body

​
date
string
An RFC 3339 timestamp. If provided, returns the count of contacts updated after this date.

​
Response

Returns the count as a string value. 
"1042"

​
Example

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