> ## 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.

# Connections

> Profile-to-profile relationships in Omneo using the Definition/Instance pattern.

**Connections** in Omneo are profile-to-profile relationships. They follow the Definition/Instance pattern: you define the type of relationship once, then create instances of it between specific profiles.

## Connection definitions

A **Connection Definition** describes a type of relationship and configures how instances of it behave. Each definition includes:

| Field                  | Description                                                                |
| ---------------------- | -------------------------------------------------------------------------- |
| `name`                 | The relationship type label (e.g., `Staff`, `Referrer`, `Stylist`)         |
| `handle`               | Machine-readable identifier                                                |
| `short_description`    | A brief label for use in UI surfaces                                       |
| `description`          | A longer description of the connection type and its purpose                |
| `shareable_attributes` | Which profile attributes are shared between connected profiles (see below) |
| `meta`                 | Arbitrary JSON metadata for brand or integration-specific use              |
| `icon_url`             | Icon image URL for representing the connection type in frontends           |
| `cover_image_url`      | Cover image URL for richer frontend representations                        |

Connection definitions also have a publish state: **Published**, **Archived**, or **Pending**. Only published definitions can have active instances created against them.

### Shareable attributes

A connection definition can specify which profile attributes are shared between the two connected profiles. For example, a household connection might share a postal address; a staff connection might share a discount entitlement. Shareable attributes reduce duplication and ensure related profiles stay in sync on key data points.

### Images

Icon and cover image URLs on a connection definition are available to any Omneo frontend surface that represents the connection type, including Profile Portal, Omneo Wallet, and Clienteling. These allow brands to give connection types a distinct visual identity.

## Connection instances

A connection instance is a specific relationship between two profiles. It references a Connection Definition and links a source profile to a target profile, with optional directionality depending on how the definition is configured.

## Use cases

* **Referral:** tracking which profile referred a new customer, enabling referral reward mechanics on both sides
* **Stylist and client:** linking a staff profile to the clients they serve for personalised Clienteling views
* **Corporate and employee:** linking an employee profile to their employer's organisation profile
* **Household members:** linking profiles that share a household for household-level analytics and shared attributes
* **Partners:** linking two profiles in a mutual personal relationship
* **Parents and children:** linking a parent profile to dependent profiles
* **Co-workers:** linking colleagues for peer referral or group incentive programs

## Connections in reactions

Connection data is available in event contexts. Reactions can fire on connection creation events, for example issuing a referral reward when a new connection is established and the referred profile completes their first purchase.

<Info>
  The Connections API supports browse, create, read, update, and delete operations for both definitions and instances. See [Connection definition API](/api-reference/connection-definition) and [Profile connection API](/api-reference/profile-connection) for full endpoint reference.
</Info>

## Related

* [Profiles](/concepts/profiles/overview)
* [Connection definition API](/api-reference/connection-definition)
* [Profile connection API](/api-reference/profile-connection)