Contacts and tags

A contact is one person on one platform: someone who commented, messaged the brand, or went through a campaign. It carries the email and phone they gave in a message, their tags and custom fields. The same person linked across ids (the Instagram id a private reply answers with, and their comment id) is one contact.

Updated September 26, 2026

The contact object

Example

{
  "id": "3c1f7a52-8e0b-4d59-a2b7-6f4e1d9c0a18",
  "platform": "instagram",
  "account_id": "cf2d0cac-6c2e-4510-8d91-4ce6545d7202",
  "account_name": "Wildermere",
  "name": "Maya Thompson",
  "handle": "mayahikes",
  "email": "<their email>",
  "phone": "+15125550142",
  "tags": [
    "restock",
    "vip"
  ],
  "fields": {
    "shoe size": "9"
  },
  "follows_you": true,
  "last_message_at": "2026-09-24T21:02:11.000Z",
  "created_at": "2026-09-20T15:40:03.000Z",
  "updated_at": "2026-09-24T21:05:40.000Z"
}

email and phone are what they gave; phone is E.164. In these docs the email is shown as a placeholder.
follows_you is known only on Instagram, after they messaged or tapped (otherwise null).
last_message_at is their last message or tap. Facebook and Instagram accept messages for 24 hours after it, TikTok for 48; can_message=true on the list finds people inside that window now.

List contacts

GET/api/v1/contacts

People, newest first. Every filter can be combined.

Who can call it: Any API key.

Query parameters

platform enum: Only people on this platform.
One of: facebook, instagram, tiktok, youtube, threads
tag string · up to 400 characters: Tag names, comma separated: people with any of them.
has enum: People with an email, a phone, or either.
One of: email, phone, either
email string · up to 254 characters: An exact email address.
q string · up to 200 characters: Search names, handles, emails and phones.
can_message enum: true: only people inside their platform's messaging window now.
One of: true, false
updated_since datetime: Changed at or after this time, for syncing. ISO 8601 with an offset.
limit integer · 1 to 100 · default 50: How many to return per page.
cursor string · up to 200 characters: next_cursor from the previous page. Leave it out for the first page.

Example

Request

curl "https://commentgate.com/api/v1/contacts?tag=vip&has=email" \
  -H "Authorization: Bearer $COMMENTGATE_API_KEY"

200 OK. A page of contacts.

200 OK response

{
  "data": [
    {
      "id": "3c1f7a52-8e0b-4d59-a2b7-6f4e1d9c0a18",
      "platform": "instagram",
      "account_id": "cf2d0cac-6c2e-4510-8d91-4ce6545d7202",
      "account_name": "Wildermere",
      "name": "Maya Thompson",
      "handle": "mayahikes",
      "email": "<their email>",
      "phone": "+15125550142",
      "tags": [
        "restock",
        "vip"
      ],
      "fields": {
        "shoe size": "9"
      },
      "follows_you": true,
      "last_message_at": "2026-09-24T21:02:11.000Z",
      "created_at": "2026-09-20T15:40:03.000Z",
      "updated_at": "2026-09-24T21:05:40.000Z"
    }
  ],
  "next_cursor": null
}

Errors

HTTP	Code	When
400	`invalid_request`	A filter or the cursor is not valid
401	`unauthorized`	Missing, unknown or revoked key

Get a contact

GET/api/v1/contacts/:id

One person.

Who can call it: Any API key.

Path parameters

id string· required: The contact id.

Example

Request

curl https://commentgate.com/api/v1/contacts/3c1f7a52-8e0b-4d59-a2b7-6f4e1d9c0a18 \
  -H "Authorization: Bearer $COMMENTGATE_API_KEY"

200 OK. The contact.

200 OK response

{
  "data": {
    "id": "3c1f7a52-8e0b-4d59-a2b7-6f4e1d9c0a18",
    "platform": "instagram",
    "account_id": "cf2d0cac-6c2e-4510-8d91-4ce6545d7202",
    "account_name": "Wildermere",
    "name": "Maya Thompson",
    "handle": "mayahikes",
    "email": "<their email>",
    "phone": "+15125550142",
    "tags": [
      "restock",
      "vip"
    ],
    "fields": {
      "shoe size": "9"
    },
    "follows_you": true,
    "last_message_at": "2026-09-24T21:02:11.000Z",
    "created_at": "2026-09-20T15:40:03.000Z",
    "updated_at": "2026-09-24T21:05:40.000Z"
  }
}

Errors

HTTP	Code	When
401	`unauthorized`	Missing, unknown or revoked key
404	`not_found`	No contact with that id in this workspace

Update a contact

PATCH/api/v1/contacts/:id

Send at least one change. Tags are created on first use. A change sends contact.updated to subscribed hooks, and Klaviyo is updated when it is connected with "Send each new email or phone" on.

Who can call it: Any API key.

Path parameters

id string· required: The contact id.

Body

email string or null · up to 254 characters: Their email address. null removes it.
phone string or null · up to 40 characters: Their phone number, with the country code outside the US. null removes it.
fields object: Custom fields to set. A null value removes that field.
add_tags array of strings · up to 20 items: Tag names to add.
remove_tags array of strings · up to 20 items: Tag names to remove.

Example

Request

curl -X PATCH https://commentgate.com/api/v1/contacts/3c1f7a52-8e0b-4d59-a2b7-6f4e1d9c0a18 \
  -H "Authorization: Bearer $COMMENTGATE_API_KEY" \
  -H "content-type: application/json" \
  -d '{"add_tags":["vip"],"fields":{"shoe size":"9"}}'

200 OK. The updated contact.

200 OK response

{
  "data": {
    "id": "3c1f7a52-8e0b-4d59-a2b7-6f4e1d9c0a18",
    "platform": "instagram",
    "account_id": "cf2d0cac-6c2e-4510-8d91-4ce6545d7202",
    "account_name": "Wildermere",
    "name": "Maya Thompson",
    "handle": "mayahikes",
    "email": "<their email>",
    "phone": "+15125550142",
    "tags": [
      "restock",
      "vip"
    ],
    "fields": {
      "shoe size": "9"
    },
    "follows_you": true,
    "last_message_at": "2026-09-24T21:02:11.000Z",
    "created_at": "2026-09-20T15:40:03.000Z",
    "updated_at": "2026-09-24T21:05:40.000Z"
  }
}

Errors

HTTP	Code	When
400	`invalid_request`	Nothing to change, or an email or phone that does not validate
401	`unauthorized`	Missing, unknown or revoked key
404	`not_found`	No contact with that id in this workspace

List tags

GET/api/v1/tags

Every tag with how many contacts have it.

Who can call it: Any API key.

Example

Request

curl https://commentgate.com/api/v1/tags \
  -H "Authorization: Bearer $COMMENTGATE_API_KEY"

200 OK. The tags.

200 OK response

{
  "data": [
    {
      "id": "6d0e4b1a-2f3c-4a5b-8c7d-9e0f1a2b3c4d",
      "name": "vip",
      "contacts": 42
    }
  ]
}

Errors

HTTP	Code	When
401	`unauthorized`	Missing, unknown or revoked key

In the help center

Connect Zapier and Make
Start a Zap or a Make scenario when a comment arrives, is hidden, needs you or turns into a lead, and hide, reply or record a sale from any other app.
Send people to Klaviyo
Emails and phone numbers people give you in DMs go to a Klaviyo list with their tags. By default they are only added to the list, not subscribed to marketing.
Move over from ManyChat
Bring your ManyChat tags, custom fields and contacts over, and rebuild your automations as campaigns. ManyChat does not let anyone copy its automations out.