Favourite groups - Omneo API

A favourite group gives each Profile its own set of Profiles. You create one favourite Group Definition, and every Profile that activates it gets a personal Group instance whose members are resolved from that Profile’s connections. Use this for per-customer sets such as favourite stores or preferred stylists. This guide covers creating the definition, managing per-Profile instances, and managing the members within an instance. For the model behind groups, see the Groups concept. All endpoints are bearer authenticated and live under https://api.[tenant].getomneo.com/api/v3.

How favourite groups work

A favourite Group Definition is ownable by a Profile. The definition holds no members itself; instead, each owner Profile gets its own instance, and the members of that instance are resolved from the definition’s source. The only current source is a Connection Definition. The definition’s source_type is connection_definition and its source_id points at a Connection Definition. Each instance’s members are the Profiles connected to its owner through that Connection Definition. The owner is the instance’s own Profile; the members are the connected Profiles.

Create the Definition

Create the definition with POST /groups/definitions, type: "favourite", and the source fields.

curl -X POST "https://api.[tenant].getomneo.com/api/v3/groups/definitions" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Favourite stores",
    "handle": "favourite-stores",
    "type": "favourite",
    "source_type": "connection_definition",
    "source_id": 7
  }'

Field	Required	Description
`type`	Yes	`favourite`.
`source_type`	Yes	The source of members. `connection_definition` is the only current value.
`source_id`	Yes	The `id` of the Connection Definition members are resolved from.

Manage per-Profile instances

Instances are managed through the profile-scoped endpoints under /profiles/{profile}/groups. The instance URL never contains the word “favourite”; the definition’s type is what makes these instances favourite groups. List the instances a Profile owns:

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

Create an instance for a Profile by referencing the definition:

curl -X POST "https://api.[tenant].getomneo.com/api/v3/profiles/{profile}/groups" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "group_definition_id": 42 }'

This is idempotent. If the Profile already owns an instance of that definition, the response is 200; a newly created instance returns 201.

Field	Required	Description
`group_definition_id`	Yes	The favourite Group Definition to instantiate for this Profile.
`meta`	No	Free-form metadata stored on the instance.

The response is the instance, a lightweight record that links an owner Profile to a definition:

{
  "data": {
    "id": 5501,
    "group_definition_id": 42,
    "owner": { "type": "profile", "id": "a1b460b2-953f-4587-b4eb-fb0f29b55e02" },
    "status": "active",
    "meta": {},
    "created_at": "2026-07-02T11:00:00Z",
    "updated_at": "2026-07-02T11:00:00Z"
  }
}

Field	Description
`id`	The instance id. This is the `{group}` you use in the member and single-instance endpoints below.
`group_definition_id`	The favourite Group Definition this instance was created from.
`owner`	The owner, as `{ type, id }`. For a Profile owner, `type` is `profile` and `id` is the Profile UUID.
`status`	The instance state, `active` by default.
`meta`	Free-form metadata.
`created_at` / `updated_at`	Timestamps.

The instance carries the membership, not the configuration: the definition (via group_definition_id) holds the source_type, source_id, and other settings. Read the definition through the Group Definition endpoints when you need those. Read or delete a single instance by its id:

# Read one instance
GET /api/v3/profiles/{profile}/groups/{group}

# Delete an instance
DELETE /api/v3/profiles/{profile}/groups/{group}

Manage members within an instance

An instance’s members are the connected Profiles. List, add, and remove them through the member endpoints under the instance. List the members of an instance:

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

Add a member by its Profile id:

curl -X POST "https://api.[tenant].getomneo.com/api/v3/profiles/{profile}/groups/{group}/profiles" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "profile_id": "c3d9f0a1-77b2-4c10-9f2e-1a2b3c4d5e6f" }'

Field	Required	Description
`profile_id`	Yes	The connected Profile to add as a member.

Remove a member by its Profile id:

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

In these paths, {profile} is the owner and {member} is the connected Profile you are adding or removing. The instance member listing returns the connected Profiles. The same members also appear in the unified definition listing, GET /groups/definitions/{group}/profiles, where each row’s record_type is connection and record is the connection linking the owner to the member. current_member_count on a favourite definition is always 0, so count members from either listing rather than that field.

Worked example: favourite stores

This runs a favourite group from definition to a per-customer set.

Create the definition

POST /groups/definitions with type: "favourite", source_type: "connection_definition", and source_id set to the Connection Definition. The response is 201 with the definition id, for example 42.

Give a customer their instance

POST /profiles/{profile}/groups with { "group_definition_id": 42 }. A first call returns 201 with a new instance; a repeat returns 200 with the one the Profile already owns. Note the instance id for the member calls.

Add favourites

POST /profiles/{profile}/groups/{group}/profiles with the connected Profile’s profile_id for each store the customer favourites.

Read the set

GET /profiles/{profile}/groups/{group}/profiles returns the members for that owner. The same members appear in GET /groups/definitions/42/profiles as connection rows across all owners.

Remove one or tidy up

DELETE /profiles/{profile}/groups/{group}/profiles/{member} removes a favourite. DELETE /profiles/{profile}/groups/{group} removes the whole instance for that customer.

Errors

Status	When
`200`	Creating an instance the Profile already owns (idempotent).
`201`	A new instance or a new member was created.
`204`	An instance or a member was deleted.
`401`	Missing or invalid bearer token.
`403`	The token lacks the scope or permission for this Profile or group.
`404`	The definition, the instance, or the member is not found under the Profile or instance named in the URL.
`422`	Validation failed. For example, creating a profile-owned instance of a `static` or `dynamic` definition, or a favourite definition without a valid `source_type` and `source_id`.

Edge cases and gotchas

The definition holds no members. Each owner Profile gets its own instance, and each instance resolves its own members. Read members per instance, or across all owners through the unified definition listing.
Instances are favourite only. Creating a profile-owned instance of a static or dynamic definition returns 422.
The instance URL never says “favourite”. Instances live under /profiles/{profile}/groups; the definition’s type is what makes them favourite groups.
Members come from connections. The only source_type is connection_definition, and members are the Profiles connected to the owner through that Connection Definition.
current_member_count is always 0. It never reflects favourite members. Count from a member listing.
Owner versus member. In the member paths, {profile} is the owner and {member} is the connected Profile.

​How favourite groups work

​Create the Definition

​Manage per-Profile instances

​Manage members within an instance

​Worked example: favourite stores

​Errors

​Edge cases and gotchas

​Related