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.
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
Sendtags (names) or tag_ids (ids). Tag names are not case-sensitive. You can add up to 50 tags in one request.
Remove a tag
Put the tag’sid in the URL. You get the id from GET /v1/tags or from the contact’s tags.
- Both are safe to repeat. Adding a tag the contact already has, or removing one it does not have, returns
200and changes nothing. - Several tags are added together. If one tag in the request is unknown, the request returns
400and 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 returns404. Create the tag in the dashboard first. - Use one field, not both. Sending
tagsandtag_idstogether returns400. - 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
Sendtags (names) or tag_ids (ids) when you create or update a contact.
- Leave the field out to keep the tags. An update without
tagsandtag_idsdoes not touch them. - Send an empty list to clear them.
{"tags": []}removes every tag from the contact. - Use one field, not both. Sending
tagsandtag_idstogether returns400. - 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_IDlists the contacts that hold a tag. - Get told when tags change. Any tag change sends the
contact.updatedwebhook. A tag change does not move the contact’supdated_at, soupdated_sincewill 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 usemultipart/form-data, not JSON. A new photo replaces the old one.
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
photo_url set to null. Removing a photo that is already gone is not an error.
