Working with Groups

A Group is a named set of Profiles you target for messaging, personalisation, and integration. You create a Group Definition once, choose its type, then manage membership according to that type. This guide covers creating a definition, running a static group end to end, and reading members for any group. For the model behind groups, see the Groups concept. All endpoints are bearer authenticated and live under https://api.[tenant].getomneo.com/api/v3.

Choose a group type

Every Group Definition has one of three types. The type sets how membership is determined and which endpoints you use to manage it.

Type	Members determined by	Use when
`static`	Explicit add and remove calls	You maintain the list yourself: hand-curated segments, imported lists, or membership another system owns.
`dynamic`	Rules evaluated on a refresh schedule	Membership should follow Profile data automatically, for example “profiles that spent over $500 in the last 12 months”. See Building dynamic groups.
`favourite`	Resolved from the owner Profile’s connections	Each Profile has its own set, for example a customer’s favourite stores or preferred stylists. See Favourite groups.

Create a Group Definition

Create a definition with POST /groups/definitions. Only name, handle, and type are required.

curl -X POST "https://api.[tenant].getomneo.com/api/v3/groups/definitions" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "VIP customers",
    "handle": "vip-customers",
    "type": "static"
  }'

The response is 201 with the created definition, including its id, which you use in the membership endpoints below.

Field	Required	Description
`name`	Yes	Human-readable name.
`handle`	Yes	Handle for the definition.
`type`	Yes	`static`, `dynamic`, or `favourite`.
`short_description` / `description`	No	Descriptive copy shown alongside the group.
`meta`	No	Free-form metadata object.
`is_published` / `is_active` / `is_archived`	No	Publication and lifecycle flags.

Dynamic groups add query and rule fields; favourite groups add source_type and source_id. Those are covered on the sibling pages.

The type is set when the definition is created and cannot be changed afterwards. To move membership to a different mechanism, create a new definition of the type you want.

Read, update, and delete a definition

Read a single definition with GET /groups/definitions/{group}, change it with PUT, and remove it with DELETE. PUT accepts the same fields as create, except type, which is fixed once set. DELETE returns 204 and removes the definition together with its membership records.

# Read one definition
curl "https://api.[tenant].getomneo.com/api/v3/groups/definitions/{group}" \
  -H "Authorization: Bearer ${TOKEN}"

# Update a definition
curl -X PUT "https://api.[tenant].getomneo.com/api/v3/groups/definitions/{group}" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "short_description": "Hand-curated VIP list" }'

# Delete a definition
curl -X DELETE "https://api.[tenant].getomneo.com/api/v3/groups/definitions/{group}" \
  -H "Authorization: Bearer ${TOKEN}"

A read returns the full definition. Every definition returns the same field set regardless of type; fields that do not apply to the group’s type are null or empty. The response below is the static group created above.

{
  "data": {
    "id": 17,
    "name": "VIP customers",
    "handle": "vip-customers",
    "type": "static",
    "source_type": null,
    "source_id": null,
    "query": null,
    "query_type": null,
    "arguments": null,
    "period": 30,
    "period_type": "days",
    "absolute_expiry": null,
    "refresh_period": null,
    "refresh_period_type": null,
    "refresh_absolute_expiry": null,
    "last_refreshed_at": null,
    "next_refresh_at": null,
    "refresh_status": null,
    "refresh_error": null,
    "short_description": "Hand-curated VIP list",
    "description": null,
    "owner_profile_id": null,
    "meta": {},
    "is_published": true,
    "is_active": true,
    "is_archived": false,
    "current_member_count": 128,
    "rules": [],
    "created_at": "2026-07-01T09:00:00Z",
    "updated_at": "2026-07-10T14:30:00Z"
  }
}

Field	Applies to	Description
`id`	All	Definition id used in the membership, rule, and snapshot endpoints.
`name`	All	Human-readable name.
`handle`	All	Handle for the definition.
`type`	All	`static`, `dynamic`, or `favourite`. Fixed once set.
`source_type` / `source_id`	Favourite	Member source. Currently `connection_definition` and the Connection Definition id. `null` otherwise.
`query` / `query_type` / `arguments`	Dynamic	Candidate query name, its type, and its `[{name,value}]` arguments. `null` otherwise.
`period` / `period_type` / `absolute_expiry`	Static	Membership expiry: a `period` counted in `period_type` units, or a fixed `absolute_expiry` date.
`refresh_period` / `refresh_period_type` / `refresh_absolute_expiry`	Dynamic	Re-evaluation cadence.
`last_refreshed_at` / `next_refresh_at`	Dynamic	When the group last re-evaluated and when it is next due.
`refresh_status`	Dynamic	Evaluation state: `fresh`, `stale`, `refreshing`, or `failed`.
`refresh_error`	Dynamic	Message from the last failed run, otherwise `null`.
`short_description` / `description`	All	Descriptive copy shown alongside the group.
`owner_profile_id`	Favourite	The owning Profile on a profile-owned instance. `null` on a shared definition.
`meta`	All	Free-form metadata object.
`is_published` / `is_active` / `is_archived`	All	Publication and lifecycle flags.
`current_member_count`	Static	Count of active static members. Always `0` for dynamic and favourite.
`rules`	Dynamic	The attached inclusion and exclusion rules. See Building dynamic groups.
`created_at` / `updated_at`	All	Timestamps.

Run a static group

A static group is a list you manage directly. Create a static definition, then add and remove Profiles.

Add a Profile

curl -X POST "https://api.[tenant].getomneo.com/api/v3/groups/definitions/{group}/profiles" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "profile_id": "a1b460b2-953f-4587-b4eb-fb0f29b55e02" }'

The add is idempotent. A Profile that is already an active member returns 200; a newly added Profile returns 201.

Field	Required	Description
`profile_id`	Yes	The Profile to add.
`source_type` / `source_id`	No	Where the membership came from, for your own tracking.
`added_by_profile_id`	No	The Profile that performed the add.
`meta`	No	Free-form metadata stored on the membership.

Remove a Profile

curl -X POST "https://api.[tenant].getomneo.com/api/v3/groups/definitions/{group}/profiles/{profile}/remove" \
  -H "Authorization: Bearer ${TOKEN}"

Removal returns 404 when the Profile has no active membership in the group, so a 404 here means there was nothing to remove.

Direct add and remove apply to static groups only. Dynamic membership is computed from rules, and favourite membership is managed per Profile through the profile-scoped endpoints.

Expire memberships

To make static memberships expire, set period and period_type on the definition, or set an absolute_expiry date. Each membership’s expiry is calculated once, at the moment the Profile is added.

curl -X POST "https://api.[tenant].getomneo.com/api/v3/groups/definitions" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Summer promo",
    "handle": "summer-promo",
    "type": "static",
    "period": 30,
    "period_type": "days"
  }'

period_type accepts days, weeks, months, years, absolute_date, absolute_week, or absolute_month. Use absolute_expiry when every membership should end on the same fixed date rather than a period counted from when each Profile joined.

Read members

List a group’s members with GET /groups/definitions/{group}/profiles. One endpoint returns members for every group type in the same shape, so consumers do not branch on type.

curl "https://api.[tenant].getomneo.com/api/v3/groups/definitions/{group}/profiles" \
  -H "Authorization: Bearer ${TOKEN}"

Type	What the listing returns
`static`	The Profiles currently on the list.
`dynamic`	The members from the most recent completed snapshot.
`favourite`	The connected Profiles across all owners of the definition.

Each row has the same wrapper for every type: a profile_id, a record_type that tells you which membership mechanism produced the row, and a record holding the underlying membership object. The example below is a static group, so every row is a group_profile.

{
  "data": [
    {
      "profile_id": "a1b460b2-953f-4587-b4eb-fb0f29b55e02",
      "record_type": "group_profile",
      "record": {
        "profile_id": "a1b460b2-953f-4587-b4eb-fb0f29b55e02",
        "source_type": "import",
        "source_id": "2026-q3-vip.csv",
        "added_by_profile_id": null,
        "meta": {},
        "created_at": "2026-07-02T11:00:00Z"
      }
    }
  ],
  "meta": { "pagination": { "total": 128, "count": 1, "per_page": 50, "current_page": 1, "total_pages": 3 } }
}

The record_type depends on the group’s type, and record carries the corresponding resource.

`record_type`	Group type	What `record` contains
`group_profile`	`static`	The static membership record.
`group_snapshot_profile`	`dynamic`	The Profile’s row from the most recent completed snapshot. See Building dynamic groups.
`connection`	`favourite`	The connection linking the owner Profile to the member. See Favourite groups.

The listing is paginated. Page through meta.pagination as with every Omneo list endpoint.

The current_member_count on a definition counts static members only. It is always 0 for dynamic and favourite groups. To size a dynamic group, read its latest snapshot; to size a favourite group, page the member listing.

Worked example: a static VIP list

This walks a static group from creation to a running, expiring list.

Create the definition

POST /groups/definitions with type: "static", period: 30, and period_type: "days". The response is 201 and includes the new id, for example 17. Every membership added from now on expires 30 days after it is added.

Add members

POST /groups/definitions/17/profiles with a profile_id for each customer. A first add returns 201; re-adding the same Profile returns 200 without creating a duplicate. Pass source_type and source_id to record the import or system the membership came from.

Read the current list

GET /groups/definitions/17/profiles returns group_profile rows and meta.pagination. GET /groups/definitions/17 shows current_member_count for a quick size.

Remove a member

POST /groups/definitions/17/profiles/{profile}/remove ends the membership. If that Profile is not an active member, the call returns 404, so a 404 here means there was nothing to remove.

Act on changes

Subscribe to group.profile.add and group.profile.remove through a Reaction to message customers as they join or leave, including when a membership expires.

Errors

Status	When
`200`	Add succeeded for a Profile that was already an active member (idempotent, no duplicate created).
`201`	Add created a new membership, or a definition was created.
`204`	A definition was deleted.
`401`	Missing or invalid bearer token.
`403`	The token lacks the scope or permission for this group.
`404`	The Group Definition does not exist, or (on remove) the Profile has no active membership in it.
`422`	Validation failed. For example, manual add or remove against a `dynamic` or `favourite` group, or sending `query`, rule, or `source` fields that do not apply to a `static` group.

Edge cases and gotchas

type is immutable. You cannot convert a group between static, dynamic, and favourite. Create a new definition instead.
Manual membership is static only. Add and remove calls are rejected with 422 on dynamic and favourite groups. Dynamic membership is computed from rules; favourite membership is managed per Profile.
Expiry is fixed at add time. A membership’s expiry is calculated once, when the Profile is added. Changing period or absolute_expiry later does not reschedule memberships already created.
current_member_count is static only. It stays 0 for dynamic and favourite groups even when they have members. Size those from the member listing or the latest snapshot.
Instances are favourite only. Creating a profile-owned instance of a static or dynamic definition returns 422. See Favourite groups.

Membership and definition changes emit events you can act on through Reactions and webhook Targets.

Event	Fires when
`group.profile.add`	A Profile joins a group (static add, dynamic match, or favourite connection).
`group.profile.remove`	A Profile leaves a group (static removal or expiry, dynamic departure, or favourite disconnect).
`group_definition.created`	A Group Definition is created.
`group_definition.updated`	A Group Definition is changed.
`group_definition.deleted`	A Group Definition is deleted.

For example, subscribe to group.profile.add to send a welcome message when a customer enters a VIP group, or to group.profile.remove to revoke access when they leave.

Next steps

Building dynamic groups

Compute membership from a candidate query and reusable inclusion and exclusion rules.

Favourite groups

Give each Profile its own set, resolved from that Profile’s connections.

​Choose a group type

​Create a Group Definition

​Read, update, and delete a definition

​Run a static group

​Expire memberships

​Read members

​Worked example: a static VIP list

​Errors

​Edge cases and gotchas

​Subscribe to group events

​Next steps

Building dynamic groups

Favourite groups

​Related

Choose a group type

Create a Group Definition

Read, update, and delete a definition

Run a static group

Expire memberships

Read members

Worked example: a static VIP list

Errors

Edge cases and gotchas

Subscribe to group events

Next steps

Related