Skip to main content
POST
/
v2
/
lists
curl --request POST \
  --url https://api.heymarket.com/v2/lists \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "title": "My VIP Contacts",
    "type": "contacts",
    "local_id": "dc3deb9b-940a-444d-9d0e-8e3087a160e9",
    "contacts": [1001, 1002, 1003]
  }'

{
  "id": 42,
  "rev": 1,
  "uuid": "dc3deb9b-940a-444d-9d0e-8e3087a160e9"
}
Create a new contact list and optionally populate it with existing contacts or new ones identified by phone or email. Lists are used to send broadcast messages where each recipient receives the message individually.

​
Request body

​
title
string
required
The display name for the list.
​
local_id
string
required
A client-provided unique identifier. Use a UUID or a stable key from your own system to avoid creating duplicate lists.
​
type
string
Set to "contacts" to create an omnichannel contact-based list. Omit for a standard phone-number list.
​
contacts
integer[]
Array of existing contact IDs to add to the list at creation time.
​
phones
string[]
Array of phone numbers in E.164 format without the leading + (e.g., "14155550100"). New contacts are created for any number not already in your account.
​
emails
string[]
Array of email addresses to add as new contacts.

​
Response

​
id
integer
Unique identifier of the newly created list.
​
rev
integer
Initial revision number.
​
uuid
string
UUID of the created list.

​
Example

curl --request POST \
  --url https://api.heymarket.com/v2/lists \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "title": "My VIP Contacts",
    "type": "contacts",
    "local_id": "dc3deb9b-940a-444d-9d0e-8e3087a160e9",
    "contacts": [1001, 1002, 1003]
  }'

{
  "id": 42,
  "rev": 1,
  "uuid": "dc3deb9b-940a-444d-9d0e-8e3087a160e9"
}
POST /v1/list is deprecated. Use POST /v2/lists for all new integrations.