Skip to main content
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: 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.

​
Relationship types

Every definition carries a type that groups it into a category. When you create or update a definition, type must be one of: brand, referral, dependant, stylist, company, partner, household, advisor, staff_join, staff_preferred, gift, external, other Omneo also ships a built-in definition with the handle staff and the type staff, which carries the Joined Staff and Preferred Staff records. Those two are told apart by the connection’s name, not by the definition. staff is reserved for that definition and is not accepted when you create or update one of your own. type is a label. It does not change how Omneo processes a connection, and more than one definition can share the same type. handle is what uniquely identifies a definition.
You can filter definitions by type on Browse Connection Definitions. You cannot filter a profile’s connections by their definition’s type, so resolve the definition IDs you want first, then filter connections by connection_definition_id. See Read Profile Connections for a worked example.

​
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 holds the two profiles in separate fields: A connection is identified by the pair, not by either profile alone. The same two profiles can hold several connections against different definitions, and one profile can appear on the same side of many connections.

​
Connection direction

Omneo does not reserve connected_id for one real-world role and connector_id for another. Which profile lands in which field depends on the definition and on what created the connection. This matters when you read a profile’s connections. Read Profile Connections returns one side at a time, selected with the type parameter: type=connected returns connections where the profile is the connected_id, and type=connector returns connections where the profile is the connector_id. It defaults to connected, and there is no option that returns both, so reading every connection touching a profile takes two calls. A profile’s Joined Staff and Preferred Staff records come back under type=connected. Reading the same records from the staff member’s own profile needs type=connector.

​
Shared profile data

Each side of a connection can expose a different set of its own profile attributes to the other, controlled by shareable_attributes on the definition and scoped to the connection’s current status. Read Connected Profile Data returns the attributes configured for the role the requested profile plays.

​
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.
The Connections API supports browse, create, read, update, and delete operations for both definitions and instances. See Connection definition API and Profile connection API for full endpoint reference.