Relationship types

A relationship type is the shape of a link, not a link itself. Every relationship (e.g. person user_123 → order ord_998) points at a relationship type that defines its role, the object types involved, and metadata like cardinality. Think of it as the schema for your edges. Creating a relationship requires a relationshipTypeId, so registering the type — or finding an existing one with GET /relationship-types — is a prerequisite for linking over the API. Registering also lets you attach cardinality, description, and bidirectional so your graph is self-describing and queryable in Segments.

When you register a type, you reference custom object types by name (order, line_item). When you create a relationship, you reference the type by its relationshipTypeId (returned here) — so register or list your types first. See the FAQ below.

What you need before you register

Registration validates against your existing catalog, so have these ready first — in this order:

An organization API key

Sent as Authorization: Bearer boom_org_…. The organization is derived from the key. See Authentication.

The custom object type(s), already created

Both endpoints reference object types by name, and those types must already exist for your org. An unknown name returns 404 with fuzzy suggestions. Confirm with:

curl "$BASE/custom-objects/types" -H "Authorization: Bearer $BOOM_KEY"

For person_to_co you need one type; for co_to_co you need both the parent and the child type.

A role and (recommended) the metadata

Decide the role label and, ideally, the cardinality and a short description. These are the fields documented in the catalog below.

Field catalog

Required vs. optional fields per kind. role, cardinality, description, and bidirectional are common to both.

`kind: "person_to_co"`

Field	Required	Type	Notes
`kind`	✅	`"person_to_co"`	Discriminator.
`role`	✅	string (1–255)	Label for the link, e.g. `placed`, `returned`.
`customObjectType`	✅	string (1–255)	Name of an existing custom object type.
`cardinality`	—	enum	One of the cardinality values.
`description`	—	string (1–1000)	Human-readable explanation.
`bidirectional`	—	boolean	Defaults to `false`.

`kind: "co_to_co"`

Field	Required	Type	Notes
`kind`	✅	`"co_to_co"`	Discriminator.
`role`	✅	string (1–255)	Label for the link, e.g. `contains`.
`parentCustomObjectType`	✅	string (1–255)	Name of an existing type (parent side).
`childCustomObjectType`	✅	string (1–255)	Name of an existing type (child side).
`cardinality`	—	enum	One of the cardinality values.
`description`	—	string (1–1000)	Human-readable explanation.
`bidirectional`	—	boolean	Defaults to `false`.

Both person_to_co and co_to_co relationships can be created over the API. To link two objects, call Link a relationship with kind: "co_to_co" and parentExternalId / childExternalId (instead of personExternalId / customObjectExternalId).

Cardinality catalog

cardinality is optional but recommended. For person_to_co, read it as person→object; for co_to_co, read it as parent→child.

Value	Meaning	Example (`person_to_co`)
`ONE_TO_ONE`	One on each side.	A person has exactly one `profile`.
`ONE_TO_MANY`	One subject, many objects.	A person `placed` many `order`s.
`MANY_TO_ONE`	Many subjects, one object.	Many people belong to one `household`.
`MANY_TO_MANY`	Many on both sides.	People `favorited` many `product`s.

Any other value is rejected with 400.

Register a type

curl -X POST "$BASE/relationship-types" \
  -H "Authorization: Bearer $BOOM_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "person_to_co",
    "role": "placed",
    "customObjectType": "order",
    "cardinality": "ONE_TO_MANY",
    "description": "A person who placed an order"
  }'

curl -X POST "$BASE/relationship-types" \
  -H "Authorization: Bearer $BOOM_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "co_to_co",
    "role": "contains",
    "parentCustomObjectType": "order",
    "childCustomObjectType": "line_item",
    "cardinality": "ONE_TO_MANY"
  }'

The response echoes the resolved type, including created (false when the type already existed and was refined in place):

{
  "kind": "person_to_co",
  "relationshipTypeId": "rt_2hk9",
  "role": "placed",
  "customObjectType": "order",
  "cardinality": "ONE_TO_MANY",
  "description": "A person who placed an order",
  "bidirectional": false,
  "created": true
}

Registration is an upsert — re-post the same (kind, role, type) to refine metadata. Omitted optional fields are preserved, so you can patch just the description without clearing a previously-set cardinality.

List your types

curl "$BASE/relationship-types" -H "Authorization: Bearer $BOOM_KEY"

{
  "data": [
    { "kind": "person_to_co", "relationshipTypeId": "rt_2hk9", "role": "placed", "customObjectType": "order", "cardinality": "ONE_TO_MANY", "description": "A person who placed an order", "bidirectional": false },
    { "kind": "co_to_co", "relationshipTypeId": "rt_8fa1", "role": "contains", "parentCustomObjectType": "order", "childCustomObjectType": "line_item", "cardinality": "ONE_TO_MANY", "description": null, "bidirectional": false }
  ],
  "next_cursor": null
}

Recommended order of operations

Create custom object types

POST /custom-objects/types (or via your dashboard / data sync). The public API never auto-creates object types.

POST /relationship-types with cardinality + description. Keep the relationshipTypeId from the response — you’ll need it to create relationships.

Upsert people and custom objects

POST /people and POST /custom-objects.

Create relationships

POST /relationships, passing the relationshipTypeId from step 2.

FAQ

Do I send the `relationshipTypeId` when creating a relationship?

Yes — it’s required. POST /relationships takes the relationshipTypeId, which fixes the link’s role and which custom object type it targets, so you don’t pass those separately. Get the id from the response of POST /relationship-types or from GET /relationship-types.

// POST /relationships — request
{ "personExternalId": "user_123", "customObjectExternalId": "ord_998",
  "relationshipTypeId": "rt_2hk9" }

// response
{ "created": true, "relationshipTypeId": "rt_2hk9" }

What happens if I skip registration?

You can’t — POST /relationships needs a relationshipTypeId, and the only way to get one is to register a type (or list a type that already exists from a prior data sync). So registering is a prerequisite for linking over the API.

Can I change a type’s cardinality later?

Yes — re-POST the same type with the new value. It’s an upsert and only the fields you send are updated.

Quickstart

Events

Record what your linked people and objects did.

​What you need before you register

​Field catalog

​kind: "person_to_co"

​kind: "co_to_co"

​Cardinality catalog

​Register a type

​List your types

​Recommended order of operations

​FAQ

​Do I send the relationshipTypeId when creating a relationship?

​What happens if I skip registration?

​Can I change a type’s cardinality later?

​Related

Quickstart

Events

What you need before you register

Field catalog

`kind: "person_to_co"`

`kind: "co_to_co"`

Cardinality catalog

Register a type

List your types

Recommended order of operations

FAQ

Do I send the `relationshipTypeId` when creating a relationship?

What happens if I skip registration?

Can I change a type’s cardinality later?

Related