Segments

A segment is a dynamic group of contacts. Segments are defined by conditions, and their members are worked out each time you query them.

The segment object

{
  "id": 3,
  "name": "French CTOs",
  "description": null,
  "conditions": [
    { "field": "custom_fields.country", "operator": "equals", "value": "FR" },
    { "field": "email", "operator": "ends_with", "value": ".fr", "connector": "or" }
  ],
  "contacts_count": 87,
  "created_at": "2026-02-01T10:00:00.000000Z",
  "updated_at": "2026-02-01T10:00:00.000000Z"
}

Endpoints

Method	Path	Permission	Description
GET	/segments	segments:read	List segments (paginated). Query: search
POST	/segments	segments:write	Create a segment
GET	/segments/{id}	segments:read	Get a segment
PUT	/segments/{id}	segments:write	Update a segment (partial)
DELETE	/segments/{id}	segments:write	Delete a segment. Returns 204.
GET	/segments/{id}/contacts	segments:read	Contacts that match (paginated)
GET	/segments/{id}/preview	segments:read	Number of matches and a sample of 5 contacts

List segments

GET /segments

Returns segments 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	Segments 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.
match_type	enum	all or any.
sort	enum	created_at, updated_at, name, or match_type.
direction	enum	asc or desc. Default desc.

curl --get https://app.beeving.com/api/v1/segments \
  -H "Authorization: Bearer TOKEN" \
  -H "Accept: application/json" \
  --data-urlencode "search=French CTO" \
  --data-urlencode "match_type=all" \
  --data-urlencode "sort=name" \
  --data-urlencode "direction=asc"

List contacts in a segment

GET /segments/{id}/contacts

The parent segment and generated contact query are both restricted to the token workspace. A segment 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, list_id, tag_id	integer	Further restrict matches to a workspace company, 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/segments/3/contacts \
  -H "Authorization: Bearer TOKEN" \
  -H "Accept: application/json" \
  --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 a segment

POST /segments

Field	Type	Rules
name	string	Required. Max 255 characters
description	string	Max 1000 characters
match_type	enum	Required. all (AND) or any (OR)
conditions	array	Required. 1 to 20 conditions
conditions.*.field	string	Contact fields such as email, linkedin_url, lifecycle_stage, status, created_at; relationships company_id, tag_id, list_id; or custom_fields.<key> for a relational custom field
conditions.*.operator	enum	See the table below
conditions.*.value	string	Max 500 characters. Leave it out for is_empty and is_not_empty
conditions.*.connector	enum	and or or. Overrides match_type for this condition and is ignored on the first condition

Operator	Meaning
equals / not_equals	Exact match
contains / not_contains	Substring
starts_with / ends_with	Prefix or suffix
is_empty / is_not_empty	Empty or filled
greater_than / less_than	Comparison, for dates and numbers

curl -X POST https://app.beeving.com/api/v1/segments \
  -H "Authorization: Bearer TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Active Gmail users",
    "match_type": "all",
    "conditions": [
      { "field": "status", "operator": "equals", "value": "active" },
      { "field": "email", "operator": "ends_with", "value": "@gmail.com" }
    ]
  }'

201: { "data": Segment }

Update

PUT /segments/{id} is partial: send only the fields you want to change. When you send conditions, it replaces every existing condition.

Preview

GET /segments/{id}/preview

{
  "data": {
    "count": 87,
    "sample": [ /* up to 5 contacts */ ]
  }
}