Skip to main content
Use the conversations list endpoint to retrieve and paginate through conversations in your Heymarket inboxes. You can filter by open or closed status, unread state, and specific inboxes. A separate count endpoint lets you retrieve the total number of conversations matching a date range.

​
POST /v1/conversations — list conversations

Returns a paginated list of conversations. Results are sorted by updated descending by default. Pass the updated value of the last returned conversation as the date cursor to fetch the next page.

​
Request body

​
id
integer
required
The user ID of a member of the inbox. This is used to verify inbox membership and scope the results.
​
filters
object
required
An object containing filter criteria for the conversations query.
​
date
string
An RFC 3339 pagination cursor. Only conversations updated before this timestamp are returned. Use the updated field of the last item in the previous response to fetch the next page.

​
Request example

{
  "date": "2022-01-01T00:00:00+00:00",
  "id": 1111,
  "filters": {
    "inboxes": [2222, 3333],
    "closed": false,
    "unread": false
  }
}

​
Example

curl --request POST \
  --url https://api.heymarket.com/v1/conversations \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "id": 1111,
    "filters": {
      "inboxes": [2222, 3333],
      "closed": false,
      "unread": false
    },
    "date": "2026-04-16T00:00:00+00:00"
  }'
To paginate through all conversations, take the updated field of the last item in each response and use it as the date value in your next request. Continue until the response returns an empty array.

​
POST /v1/conversations/count — count conversations

Returns the total number of conversations, optionally filtered by a date range.

​
Request body

​
date
string
An RFC 3339 timestamp. When provided, only conversations updated before this date are counted.

​
Example

curl --request POST \
  --url https://api.heymarket.com/v1/conversations/count \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "date": "2026-04-16T00:00:00+00:00"
  }'

​
The Conversation object

​
id
integer
The unique ID of the conversation.
​
channel
string
The channel type: sms, mms, email, or chat.
​
status
string
Whether the conversation is open or closed.
​
assigned
object
The team member the conversation is assigned to, if any.
​
inbox
object
The inbox this conversation belongs to.
​
target
string
The contact’s phone number or email address.
​
members
object[]
An array of team members who are participants in the conversation.
​
created
string
The ISO 8601 timestamp of when the conversation was created.
​
updated
string
The ISO 8601 timestamp of the most recent activity in the conversation. Use this as the date pagination cursor.
​
read
boolean
Whether the conversation has been read by the requesting user.
​
replied
boolean
Whether the conversation has received a reply.
​
blocked
boolean
Whether the contact has been blocked.
​
muted
boolean
Whether notifications are muted for this conversation.
​
snooze_till
string
An ISO 8601 timestamp indicating when the snooze on this conversation expires, if snoozed.