Skip to main content
POST
/
v2
/
contacts
Bulk Create Contacts (V2)
curl --request POST \
  --url https://api.heymarket.com/v2/contacts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "contacts": [
    {
      "phone": "12345678900",
      "avatar": "https://some.image.url.com/img.jpg",
      "custom": {},
      "display_name": "John Smith",
      "email": "john.s@heymarket.com",
      "first": "John",
      "last": "Smith",
      "assignee_id": 42,
      "tags": [
        {
          "tag_id": 1
        },
        {
          "tag_id": 2
        }
      ],
      "is_opted_out": true,
      "email_suppressions": [
        123
      ],
      "contact_channels": [
        {
          "channel_type": "phone",
          "channel_id": "14155551234",
          "channel_ids": [
            "<string>"
          ],
          "channel_handle": "<string>",
          "info_channel": "<string>"
        }
      ]
    }
  ]
}
'
{
  "contacts": [
    {
      "avatar": "<string>",
      "created": "<string>",
      "creator_id": 123,
      "custom": {},
      "display_name": "<string>",
      "email": "<string>",
      "external_id": "<string>",
      "external_ref": "<string>",
      "first": "<string>",
      "id": 123,
      "inbox_id": 123,
      "last": "<string>",
      "note": [
        {
          "date": "<string>",
          "id": "<string>",
          "name": "<string>",
          "text": "<string>",
          "user_id": 123
        }
      ],
      "op": "<string>",
      "parent_id": 123,
      "phone": "<string>",
      "rev": 123,
      "shared": true,
      "team_id": 123,
      "type": "<string>",
      "updated": "<string>",
      "assigned_user_id": 123,
      "tags": [
        "<unknown>"
      ]
    }
  ],
  "failed_contacts": [
    {
      "contact": {
        "phone": "12345678900",
        "avatar": "https://some.image.url.com/img.jpg",
        "custom": {},
        "display_name": "John Smith",
        "email": "john.s@heymarket.com",
        "first": "John",
        "last": "Smith",
        "assignee_id": 42,
        "tags": [
          {
            "tag_id": 1
          },
          {
            "tag_id": 2
          }
        ],
        "is_opted_out": true,
        "email_suppressions": [
          123
        ],
        "contact_channels": [
          {
            "channel_type": "phone",
            "channel_id": "14155551234",
            "channel_ids": [
              "<string>"
            ],
            "channel_handle": "<string>",
            "info_channel": "<string>"
          }
        ]
      },
      "error": "<string>"
    }
  ]
}
Use this endpoint for v2 bulk contact imports and updates.

Authorizations

Authorization
string
header
required

Recommended authentication for new integrations. Generate a short-lived JWT from your API Secret ID and API Secret Key, then pass the signed JWT as a bearer token in the Authorization header.

API Secret credentials are available in the Heymarket app under Settings > Integrations > API. The Secret Key is shown only when it is generated, so copy and store it securely before closing the dialog.

Use the following JWT values:

{
"alg": "HS256",
"typ": "JWT"
}
{
"iss": "YOUR_API_SECRET_ID",
"iat": CURRENT_UNIX_TIMESTAMP
}

Replace CURRENT_UNIX_TIMESTAMP with the current Unix timestamp in seconds when generating the token.

Sign the JWT with HMAC-SHA256 using this signing secret:

YOUR_API_SECRET_ID||YOUR_API_SECRET_KEY

Send the signed JWT as a bearer token:

Authorization: Bearer YOUR_SIGNED_JWT

Tokens expire 5 minutes after the iat timestamp. Generate a new JWT per request, or cache it briefly for less than 5 minutes. Generate JWTs only from trusted server-side code; do not expose the API Secret Key in browser, mobile, or other client-side code.

Body

application/json

Bulk contact json

contacts
object[]

List of contacts to create or update

Response

Bulk create response

contacts
object[]

Successfully created or updated contacts

failed_contacts
object[]

Contacts that failed to create or update