Segment groups API reference
Create, read, update, and delete segment groups and their email-platform synchronization settings.
Use segment groups to organize named audiences and their email-platform synchronization settings. These endpoints edit the project draft.
Authentication and segment-group operations
Paths below follow https://api.rightmessage.com/v1/{teamPid}. GET requires read or write; mutations require write. The * ability satisfies both. The shared request conventions cover bearer authentication, headers, project access, and rate limits.
| Method and path | Request | Success |
|---|---|---|
GET /segment-groups | No filters or pagination parameters | 200, {"data":[RESOURCE]} |
GET /segment-groups/{segmentGroup} | Resource ID from the list | 200, {"data":RESOURCE} |
POST /segment-groups | Create body below | 201, {"data":RESOURCE} |
PUT or PATCH /segment-groups/{segmentGroup} | Partial body below | 200, {"data":RESOURCE} |
DELETE /segment-groups/{segmentGroup} | No body | 204, empty body |
PUT and PATCH have the same partial-update behavior. An omitted top-level field retains its value. A collection with no resources returns {"data":[]}. Reads return the draft when one exists, otherwise the stable configuration.
Errors and draft effects
The shared error contract applies. Invalid request fields return 422 with message and field-keyed errors. Full-configuration validation can return 500 instead.
Mutations save a draft, not live changes. Publishing applies the whole project draft, including edits made elsewhere. The draft contract covers snapshots, dashboard updates, and save failures.
Segment-group request fields
Only name is required on create. All fields are optional on update. Nullable means that JSON null is accepted.
| Field | Type and validation | Create default |
|---|---|---|
name | Nonempty string, maximum 255 characters | Required |
semantic_type | Nullable string: INDUSTRY, ROLE, COMPANY_SIZE, GOAL, PROBLEM, STAGE, or CUSTOM | null |
allow_multiple | Boolean | false |
segments | Array of objects | [] |
segments[].name | Required for each supplied segment, string, maximum 255 | No default |
sync_platform | Nullable provider-name string | null |
sync_field | Nullable custom-field string | null |
sync_mode | field or tag | field |
sync_mappings | Map of segment IDs to nullable strings | Empty map in the response |
New segments receive seg_ IDs. Groups receive dim_ IDs. Supplying segments replaces that list, not individual elements. Preserve existing segment IDs when replacing an existing list. The request validates segment names but has no separate ID rule for nested segment objects.
For a connected provider with structured custom fields, sync_field resolves an exact field ID or a case-insensitive label, templating token, or key. An unknown field raises a server error. If the provider is not connected or the field lookup fails, the service retains the supplied string. This does not prove that synchronization can succeed.
Synchronization details can generate matching signals in the draft. In field mode, a new sync-managed condition starts with an empty string value. The service does not derive that value from the segment name or from sync_mappings. Existing matching field conditions retain their values. In tag mode, sync_mappings maps segment IDs to tag IDs; empty mappings remove the matching sync-managed conditions. Switching modes removes managed conditions from the other mode, while unrelated rules remain.
Setting sync_platform to null returns before signal synchronization; it does not remove existing generated signals. signals is returned but is not a declared top-level write parameter in this REST request. Use the dashboard when you need to configure field values or inspect leftover Auto-Segment rules. This endpoint does not create a question automatically.
Resource and deletion behavior
Each resource contains id, name, semantic_type, allow_multiple, segments, signals, sync_platform, sync_field, sync_mode, and sync_mappings. Returned segments contain only id and name. sync_mappings is always a JSON object. Signals are the stored configuration objects, including generated synchronization conditions.
Deleting a group also removes its linked questions and phrases, and clears flow-node segment-group references to that group's dim_ ID. It does not clear direct raq_ references to the removed questions. An answer condition that still depends on a linked question can block deletion. Deletion does not rewrite every campaign rule or data action. Review the draft's remaining references before publication.
Illustrative requests and responses
These illustrative examples use the fictional WorkForge project. The same resource schema covers every CRUD response.
The PATCH example also works with PUT. The create, item-read, and update envelopes have this shape. The list places these resource objects in its data array. An update returns the updated values. DELETE returns no JSON.