> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hiveinspect.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Contact Tags and Photos in the API

> Set a contact's tags by name or id and upload or remove a contact photo with the Hive Inspect API. Learn the rules, limits and file types.

<p className="hive-locator">In the dashboard: <strong>Contacts</strong>, then open a contact</p>

<Note>
  **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.
</Note>

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.

<Steps titleSize="h3">
  <Step title="List your tags">
    Get each tag's `id` and `name`, plus how many contacts hold it:

    ```bash theme={"theme":{"light":"github-light","dark":"vesper"}}
    curl "https://api.hiveinspect.com/v1/tags" \
      -H "Authorization: Bearer YOUR_API_KEY"
    ```
  </Step>

  <Step title="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.

    ```bash theme={"theme":{"light":"github-light","dark":"vesper"}}
    curl -X PATCH "https://api.hiveinspect.com/v1/contacts/CONTACT_ID" \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"tags": ["VIP", "Top Agent"]}'
    ```
  </Step>
</Steps>

<Warning>
  **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.
</Warning>

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.

```bash theme={"theme":{"light":"github-light","dark":"vesper"}}
curl -X POST "https://api.hiveinspect.com/v1/contacts/CONTACT_ID/photo" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@dana-reyes.jpg;type=image/jpeg"
```

The response is the updated contact.

| Rule | Value |
| - | - |
| File types | jpg, jpeg, png, gif, webp |
| Maximum size | 10 MB |
| Content type | Must match the file's extension, for example `image/jpeg` for a `.jpg` file |

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

```bash theme={"theme":{"light":"github-light","dark":"vesper"}}
curl -X DELETE "https://api.hiveinspect.com/v1/contacts/CONTACT_ID/photo" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

The response is the contact with `photo_url` set to `null`. Removing a photo that is already gone is not an error.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.