Tags

Tags are labels you can attach to contacts.

The tag object

{
  "id": 5,
  "name": "VIP",
  "color": "#f59e0b",
  "created_at": "2026-02-01T10:00:00.000000Z",
  "updated_at": "2026-02-01T10:00:00.000000Z"
}

Endpoints

Method	Path	Permission	Description
GET	/tags	tags:read	List tags, newest first (paginated). Query: search
POST	/tags	tags:write	Create a tag
GET	/tags/{id}	tags:read	Get a tag
PUT	/tags/{id}	tags:write	Update a tag
DELETE	/tags/{id}	tags:write	Delete a tag. Returns 204.
GET	/tags/{id}/contacts	tags:read	Contacts with this tag (paginated)
POST	/tags/{id}/contacts	tags:write	Add the tag to contacts

List tags

GET /tags

Returns tags from the token workspace. Results default to created_at desc, then id desc. Invalid query values return 422.

Query	Type	Description
page	integer	Page number, minimum 1, default 1.
per_page	integer	Tags per page, from 1 to 100, default 15.
search	string	Partial name search. Every term must match; at most six terms are used.
color	string	Exact tag color.
has_contacts	boolean	1 keeps tags with contacts; 0 keeps unused tags.
sort	enum	created_at, updated_at, name, or contacts_count.
direction	enum	asc or desc. Default desc.

curl --get https://app.beeving.com/api/v1/tags \
  -H "Authorization: Bearer TOKEN" \
  -H "Accept: application/json" \
  --data-urlencode "search=priority customer" \
  --data-urlencode "has_contacts=1" \
  --data-urlencode "sort=name" \
  --data-urlencode "direction=asc"

List contacts with a tag

GET /tags/{id}/contacts

The parent tag and returned contacts are both restricted to the token workspace. A tag from another workspace returns 404.

Query	Type	Description
page, per_page	integer	Page defaults to 1. Page size is from 1 to 100 and defaults to 15.
search	string	Partial contact search over identity, name, job title and linked company.
status	enum	active, unsubscribed, bounced, or complained.
lifecycle_stage	enum	subscriber, lead, marketing_qualified_lead, sales_qualified_lead, opportunity, customer, evangelist, or other.
company_id	integer	Only contacts linked to this workspace company.
list_id, tag_id	integer	Intersect with a workspace list or another tag. A foreign ID returns 422.
has_email, has_linkedin, has_company	boolean	1 requires the value or relation; 0 requires it to be absent.
sort	enum	created_at, updated_at, first_name, last_name, email, linkedin_url, job_title, status, or lifecycle_stage.
direction	enum	asc or desc. Default desc.

curl --get https://app.beeving.com/api/v1/tags/5/contacts \
  -H "Authorization: Bearer TOKEN" \
  -H "Accept: application/json" \
  --data-urlencode "status=active" \
  --data-urlencode "has_email=1" \
  --data-urlencode "sort=created_at" \
  --data-urlencode "direction=desc"

Both listing responses contain data, navigation URLs in links, and meta with current_page, last_page, per_page, total, and count for the current page.

Create / update

Field	Type	Rules
name	string	Required, on both create and update. Max 50 characters and unique in the workspace
color	string	Hex color such as #f59e0b. Defaults to #6366f1

201 on create and 200 on update. Both return { "data": Tag }.

Tag contacts

POST /tags/{id}/contacts

{ "contact_ids": [12, 13, 14] }

You can send up to 1000 IDs. IDs that don't belong to your workspace are ignored.

200: { "data": { "message": "Tag added to 3 contacts" }, "count": 3 }

To remove tags from a contact, send the full tags array to PUT /contacts/{id}.