Skip to main content
Bulk operations let you create, update, or delete many contacts in a single API call instead of making one request per contact. Heymarket provides a legacy v1 batch create endpoint and v2 endpoints for bulk create/update and bulk delete.

​
POST /v1/batch/contacts

Creates multiple contacts in a single request. If a contact with the same phone number already exists, it is skipped unless you set overwrite=true.

​
Query parameters

​
overwrite
boolean
default:"false"
When true, overwrites any existing contact that matches a phone number in your request. When false, existing contacts are left unchanged.

​
Request body

Send an array of contact objects. Each object supports the following fields:
​
phone
string
required
Phone number in E.164 format without the leading +.
​
first
string
First name.
​
last
string
Last name.
​
display_name
string
Full display name shown in the inbox.
​
email
string
Email address.
​
is_opted_out
boolean
Set to true if the contact has opted out of messages.

​
Response

Returns an array of contact objects that failed to be created. If all contacts were created successfully, returns "ok".

​
Example

curl -X POST https://api.heymarket.com/v1/batch/contacts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "phone": "15105551234",
      "first": "Alice",
      "last": "Smith",
      "email": "alice@example.com",
      "is_opted_out": false
    },
    {
      "phone": "15105555678",
      "first": "Bob",
      "last": "Jones",
      "display_name": "Bob Jones"
    }
  ]'

​
POST /v2/contacts

Bulk creates or updates contacts using the v2 API. Contacts that include a contact_id (UUID) are updated; contacts without one are created.

​
Request body

​
contacts
array
required
Array of contact objects. Each object follows the same structure as POST /v2/contact. Include contact_id (UUID) to update an existing contact, or omit it to create a new one.

​
Response

​
contacts
array
Array of successfully created or updated contact objects.
​
failed_contacts
array
Array of contact objects that could not be created or updated, along with error details.

​
Example

curl -X POST https://api.heymarket.com/v2/contacts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      {
        "contact_channels": [
          {"channel_type": "phone", "channel_id": "15105551234"}
        ],
        "first": "Alice",
        "last": "Smith"
      },
      {
        "contact_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "contact_channels": [
          {"channel_type": "phone", "channel_id": "15105555678"}
        ],
        "first": "Bob",
        "last": "Jones Updated"
      }
    ]
  }'

​
DELETE /v2/contacts

Bulk deletes contacts by UUID using the v2 API.

​
Request body

​
contact_channels
array
required
Array of channel filter objects. To delete by UUID, use channel_type: "id" and provide the contact UUIDs in channel_ids.
  • channel_type — set to "id" to target contacts by UUID.
  • channel_ids — array of contact UUID strings to delete.
To bulk delete by UUID, set channel_type to "id" and pass the list of contact UUIDs in channel_ids.

​
Example

curl -X DELETE https://api.heymarket.com/v2/contacts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_channels": [
      {
        "channel_type": "id",
        "channel_ids": [
          "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "b2c3d4e5-f6a7-8901-bcde-f12345678901"
        ]
      }
    ]
  }'
Bulk deletion is permanent. All deleted contacts and their associated data cannot be recovered.