> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omneo.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Favourite groups

> Give each Profile its own group instance whose members are resolved from the owner's connections, via the 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](/concepts/groups).

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](/concepts/profiles/connections). 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.

```shell theme={null}
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:

```shell theme={null}
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:

```shell theme={null}
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:

```json theme={null}
{
  "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](/dev-guides/groups/working-with-groups) when you need those.

Read or delete a single instance by its `id`:

```shell theme={null}
# 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:

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

Add a member by its Profile id:

```shell theme={null}
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:

```shell theme={null}
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.

<Steps>
  <Step title="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`.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Add favourites">
    `POST /profiles/{profile}/groups/{group}/profiles` with the connected Profile's `profile_id` for each store the customer favourites.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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](/concepts/profiles/connections).
* **`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.

## Related

* [Groups concept](/concepts/groups)
* [Working with Groups](/dev-guides/groups/working-with-groups)
* [Building dynamic groups](/dev-guides/groups/dynamic-groups)
* [Connections concept](/concepts/profiles/connections)
* [Add Group Definition API](/api-reference/group-definition/add-group-definition)
* [Group instances this Profile owns API](/api-reference/profile-group/group-instances-this-profile-owns)
* [Create or return a Profile's instance API](/api-reference/profile-group/create-or-return-this-profiles-instance-of-a-definition)
* [Read a Profile's group instance API](/api-reference/profile-group/get-v3profiles-groups)
* [Delete a Profile's group instance API](/api-reference/profile-group/delete-v3profiles-groups)
* [List members of an instance API](/api-reference/group-member/get-v3profiles-groups-profiles)
* [Add a member to an instance API](/api-reference/group-member/post-v3profiles-groups-profiles)
* [Remove a member from an instance API](/api-reference/group-member/delete-v3profiles-groups-profiles)