Docs/Workspace API/Segments

Segments

Saved contact lists. Two flavours:
static — you manage the membership manually (add/remove contacts via API);
smart — membership is calculated from rules at read time. The rules format lives with the CRM UI; V1 API exposes rules as an opaque JSON blob so you can round-trip it. Smart segments reject manual membership changes with HTTP 422. Scopes: crm.segments.read / crm.segments.write / crm.segments.delete.

Endpoints

GET /api/workspace/v1/segments

GET /api/workspace/v1/segments/{id}

POST /api/workspace/v1/segments

PATCH /api/workspace/v1/segments/{id}

POST /api/workspace/v1/segments/{id}/contacts

DELETE /api/workspace/v1/segments/{id}/contacts/{contact_id}

DELETE /api/workspace/v1/segments/{id}

POST /api/workspace/v1/segments/{id}/restore

POST /api/workspace/v1/segments/bulk-delete

Create a static segment

curl "https://app.staffifyai.com/api/workspace/v1/segments" \
  -X POST \
  -H "Authorization: Bearer sfy_wsp_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "VIP customers 2026", "type": "static" }'

Add contacts to a static segment

Max 500 contact ids per request. Ids that don't belong to your tenant are silently filtered. Duplicate memberships are ignored (INSERT IGNORE).

curl -X POST "https://app.staffifyai.com/api/workspace/v1/segments/7/contacts" \
  -H "Authorization: Bearer sfy_wsp_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "contact_ids": [1893, 1894, 1895] }'

Webhooks

segment.created
segment.updated (also fires on membership add/remove)
segment.deleted
segment.restored