Skip to main content

In the dashboard: Contacts, then open a contact

The Hive Inspect API is a work in progress. It is available to a small group of accounts today, and the release for everyone is coming very soon. To ask for early access, message us from the chat bubble in your dashboard.
Every contact in the API returns its tags and a photo_url. You can change both through the API.

Tags

Tags are the labels you create in the dashboard, such as “VIP” or “Top Agent”. The API can put existing tags on a contact. It cannot create, rename or delete a tag. There are two ways to change a contact’s tags: To see your tags, with each tag’s id, name and how many contacts hold it:

Add a tag

Send tags (names) or tag_ids (ids). Tag names are not case-sensitive. You can add up to 50 tags in one request.
The response is the contact with its full tag list.
Use this when other people or tools also tag your contacts. Adding a tag keeps every tag the contact already has, including one that a teammate, a tag rule or another integration adds at the same moment. You do not need to read the contact first.

Remove a tag

Put the tag’s id in the URL. You get the id from GET /v1/tags or from the contact’s tags.
The response is the contact with its full tag list. Things to know about adding and removing:
  • Both are safe to repeat. Adding a tag the contact already has, or removing one it does not have, returns 200 and changes nothing.
  • Several tags are added together. If one tag in the request is unknown, the request returns 400 and none of them is added.
  • Unknown tags are refused. Adding a name or id that is not one of your tags returns 400. Removing an id that is not one of your tags returns 404. Create the tag in the dashboard first.
  • Use one field, not both. Sending tags and tag_ids together returns 400.
  • Tag rules still run. If a tag has an automatic rule, the rule can add the tag again or remove it the next time it runs.
  • Removing a tag can stop automations. An automation that only sends to contacts with that tag will skip this contact, the same as when you remove the tag in the dashboard.

Replace all tags

Send tags (names) or tag_ids (ids) when you create or update a contact.
The list you send replaces the contact’s tags. A tag you leave out is removed from the contact, even one that was added a moment ago by someone else. To add or remove a single tag, use the requests above instead.
Things to know about replacing:
  • Leave the field out to keep the tags. An update without tags and tag_ids does not touch them.
  • Send an empty list to clear them. {"tags": []} removes every tag from the contact.
  • Use one field, not both. Sending tags and tag_ids together returns 400.
  • Unknown tags are refused. A name or id that is not one of your tags returns 400, and nothing on the contact changes.

Find contacts and hear about changes

  • Filter by tag. GET /v1/contacts?tag_id=TAG_ID lists the contacts that hold a tag.
  • Get told when tags change. Any tag change sends the contact.updated webhook. A tag change does not move the contact’s updated_at, so updated_since will not pick it up.

Photos

photo_url is a signed link that works for 1 hour. Do not store it. Fetch the contact again when you need a fresh link.

Upload or replace a photo

Uploads use multipart/form-data, not JSON. A new photo replaces the old one.
The response is the updated contact. A file of another type, or a file that is not a real image, returns 400. A file over 10 MB returns 413.

Remove a photo

The response is the contact with photo_url set to null. Removing a photo that is already gone is not an error.
Last modified on November 14, 2026