Lists

Lists are static groups of contacts. You add contacts to them and remove contacts from them yourself. A contact can belong to several lists.

The list object

{
  "id": 1,
  "name": "Newsletter",
  "description": "Monthly product updates",
  "color": "#6366f1",
  "contacts_count": 120,
  "created_at": "2026-02-01T10:00:00.000000Z",
  "updated_at": "2026-02-01T10:00:00.000000Z"
}

Endpoints

Method	Path	Permission	Description
GET	/lists	lists:read	List lists, sorted by name (paginated)
POST	/lists	lists:write	Create a list
GET	/lists/{id}	lists:read	Get a list
PUT	/lists/{id}	lists:write	Update a list (partial)
DELETE	/lists/{id}	lists:write	Delete a list. Returns 204.
GET	/lists/{id}/contacts	lists:read	The list's active contacts (paginated)
POST	/lists/{id}/contacts	lists:write	Add contacts
DELETE	/lists/{id}/contacts	lists:write	Remove contacts

List lists

GET /lists

Returns lists from the token workspace. The default order remains name asc, then id asc. Invalid query values return 422.

Query	Type	Description
page	integer	Page number, minimum 1, default 1.
per_page	integer	Lists per page, from 1 to 100, default 15.
search	string	Partial search over name and description. Every term must match; at most six terms are used.
color	string	Exact list color.
has_contacts	boolean	1 keeps lists with contacts; 0 keeps empty lists.
sort	enum	name, created_at, updated_at, or contacts_count.
direction	enum	asc or desc. The default is asc.

curl --get https://app.beeving.com/api/v1/lists \
  -H "Authorization: Bearer TOKEN" \
  -H "Accept: application/json" \
  --data-urlencode "search=product leads" \
  --data-urlencode "has_contacts=1" \
  --data-urlencode "sort=contacts_count" \
  --data-urlencode "direction=desc"

List contacts in a list

GET /lists/{id}/contacts

The parent list and returned contacts are both restricted to the token workspace. A list from another workspace returns 404. Results default to active contacts ordered by created_at desc, then id desc; an explicit status selects another status.

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. Defaults to active.
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 another workspace list or 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/lists/12/contacts \
  -H "Authorization: Bearer TOKEN" \
  -H "Accept: application/json" \
  --data-urlencode "search=alice acme" \
  --data-urlencode "lifecycle_stage=lead" \
  --data-urlencode "has_email=1" \
  --data-urlencode "sort=first_name" \
  --data-urlencode "direction=asc"

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 create. Max 255 characters
description	string | null	Max 1000 characters

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

Add or remove contacts

POST   /lists/{id}/contacts
DELETE /lists/{id}/contacts

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

Every ID must be a contact in your workspace. Otherwise the request fails with 422.

200: { "data": { "message": "Contacts added to list" } }, or "Contacts removed from list" for a removal.

TIP

To create contacts and add them to lists in a single call, send lists: [id] to POST /contacts.