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 set 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.
1

List your tags

Get each tag’s id and name, plus how many contacts hold it:
2

Set the tags on a contact

Send tags (names) or tag_ids (ids) when you create or update a contact. Tag names are not case-sensitive.
The list you send replaces the contact’s tags. To add one tag, send the contact’s current tags plus the new one. A tag you leave out is removed from the contact.
Things to know:
  • 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. Create the tag in the dashboard first.
  • Filter by tag. GET /v1/contacts?tag_id=TAG_ID lists the contacts that hold a tag.

​
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 October 2, 2026