Skip to main content
Segments are dynamic groups — they automatically include any contact that matches a set of filter rules. Unlike lists, you don’t manually add members; the segment recalculates on every use.

​
Authentication

All endpoints require:
  • Authorization: Bearer YOUR_API_KEY
  • X-Project-ID: YOUR_PROJECT_ID (or encoded in the API key)

​
Endpoints

MethodPathDescription
GET/api/v1/contacts/segmentsList all segments
GET/api/v1/contacts/segments/:idGet a single segment
POST/api/v1/contacts/segmentsCreate a segment
PATCH/api/v1/contacts/segments/:idUpdate a segment
DELETE/api/v1/contacts/segments/:idDelete a segment

​
Segment Rules

Each rule targets a contact field and applies an operator:
OperatorDescription
eqField equals value
neqField does not equal value
containsField contains string
not_containsField does not contain string
gt / ltGreater / less than
gte / lteGreater / less than or equal
existsField is present and non-null
emptyField is null or missing
Supported fields: any top-level contact field (status, company, country, etc.) or a dot-path into custom fields (custom_fields.plan).

​
List Segments

GET https://api.usegately.com/api/v1/contacts/segments
SDK
const segments = await crm.listSegments()

​
Create a Segment

POST https://api.usegately.com/api/v1/contacts/segments
Body 
{
  "name": "Pro Plan Users",
  "description": "All active contacts on the pro plan",
  "rules": [
    { "field": "custom_fields.plan", "operator": "eq", "value": "pro" },
    { "field": "status",             "operator": "eq", "value": "active" }
  ]
}
SDK
const segment = await crm.createSegment({
  name: 'Pro Plan Users',
  rules: [
    { field: 'custom_fields.plan', operator: 'eq', value: 'pro' },
    { field: 'status',             operator: 'eq', value: 'active' },
  ],
})
Response 
{
  "id": "seg-uuid",
  "project_id": "proj-uuid",
  "name": "Pro Plan Users",
  "description": "All active contacts on the pro plan",
  "rules": [
    { "field": "custom_fields.plan", "operator": "eq", "value": "pro" },
    { "field": "status", "operator": "eq", "value": "active" }
  ],
  "list_id": null,
  "created_at": "2025-06-01T10:00:00.000Z"
}

​
Update a Segment

PATCH https://api.usegately.com/api/v1/contacts/segments/SEGMENT_ID
SDK
await crm.updateSegment('SEGMENT_ID', {
  name: 'Enterprise Users',
  rules: [{ field: 'custom_fields.plan', operator: 'eq', value: 'enterprise' }],
})

​
Delete a Segment

DELETE https://api.usegately.com/api/v1/contacts/segments/SEGMENT_ID
SDK
await crm.deleteSegment('SEGMENT_ID')

​
TypeScript Types

interface ContactSegment {
  id: string
  project_id: string
  name: string
  description?: string | null
  rules: SegmentRule[]
  list_id?: string | null
  created_at: string
  updated_at?: string
}

interface SegmentRule {
  field: string
  operator: 'eq' | 'neq' | 'contains' | 'not_contains' | 'gt' | 'lt' | 'gte' | 'lte' | 'exists' | 'empty'
  value?: string | number | boolean
}