# Segment groups API reference

Create, read, update, and delete segment groups and their email-platform synchronization settings.

Available on the Scale and Pro plans.

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](https://rightmessage.com/help/rest-api-overview#base-url-and-authentication) 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](https://rightmessage.com/help/rest-api-overview#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](https://rightmessage.com/help/rest-api-publishing) applies the whole project draft, including edits made elsewhere. The [draft contract](https://rightmessage.com/help/rest-api-overview#draft-and-live-configuration) 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.

```http
GET /v1/123456/segment-groups HTTP/1.1
Host: api.rightmessage.com
Authorization: Bearer YOUR_API_TOKEN
Accept: application/json

GET /v1/123456/segment-groups/dim_example1 HTTP/1.1
Host: api.rightmessage.com
Authorization: Bearer YOUR_API_TOKEN
Accept: application/json

POST /v1/123456/segment-groups HTTP/1.1
Host: api.rightmessage.com
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json
Accept: application/json

{
	"name": "WorkForge team type",
	"segments": [
		{
			"name": "Agency"
		}
	]
}

PATCH /v1/123456/segment-groups/dim_example1 HTTP/1.1
Host: api.rightmessage.com
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json
Accept: application/json

{
	"name": "WorkForge updated"
}

DELETE /v1/123456/segment-groups/dim_example1 HTTP/1.1
Host: api.rightmessage.com
Authorization: Bearer YOUR_API_TOKEN
Accept: application/json
```

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.

```json
{
	"data": {
		"id": "dim_example1",
		"name": "WorkForge team type",
		"semantic_type": null,
		"allow_multiple": false,
		"segments": [
			{
				"id": "seg_example1",
				"name": "Agency"
			}
		],
		"signals": [],
		"sync_platform": null,
		"sync_field": null,
		"sync_mode": "field",
		"sync_mappings": {}
	}
}
```