Relationship
Relationship connects the conversation's customer to another customer: a shareholder, a guarantor, an employee, a relative. It finds the other party by an identity document, links them, and hands back the other customer's ID in a flow variable so later nodes can write to them. It is a silent node; nothing is sent to the customer.
One piece of vocabulary, because the field names say otherwise: a contact is a customer. There is no separate contact entity; the name is historic. See Relationships API for the record.
The two modes
| Mode | What it does |
|---|---|
| Create (default) | Finds or creates the other customer by identity and links them |
| Read | Returns the conversation's customer's relationships as a list |
Create
Finding the other customer
You pick an identity type from the identity catalog — a national ID, a tax ID — and
where the value comes from: a flow variable (the usual case, written by an
Ask Question) or a typed value.
What happens then:
| Matches | Result |
|---|---|
| Exactly one | That customer is the contact |
| More than one | The highest-priority one is linked and a warning notice names how many shared the identity and which one won. The search caps at 25, so the notice says "at least 25" rather than invent a number |
| None | A new customer is created carrying that identity, with a blank label, and linked |
An identity type that is not in the catalog only leaves a warning notice — the search still runs.
A sensitive identity type cannot be used here. Sensitive identities are stored encrypted with a random nonce and no searchable index, so looking one up by value is impossible, not merely slow. The node exits through Error, and publishing a flow that configures one is blocked before it ever runs.
Linking a customer to themselves is refused. If the identity resolves to the conversation's own customer — usually because the flow passed the account holder's document by mistake — the node exits through Error instead of creating a self-relationship.
The relationship itself
| Setting | Notes |
|---|---|
| Relationship | One of shareholder, guarantor, employee, family, other, unspecified. Required |
| Legal representative | Off by default |
| Priority | A whole number. Orders the relationships when they are read back |
| Ownership % | A number between 0 and 100. Only valid when the relationship is shareholder |
| Test | Off by default. It flags the customer created for the contact, not the relationship |
A relationship value outside that list, a priority that is not a whole number, an ownership
percentage outside 0–100, or an ownership percentage on a relationship that is not
shareholder, all exit through Error with a notice naming the problem.
Only one relationship per customer can be the legal representative. Saving a new one as legal representative turns the others off.
Re-running the node does not duplicate. The same customer, contact and relationship kind is recognized and reused rather than created twice.
Outputs
| Output | Type | What it holds |
|---|---|---|
contactBorrowerId | string | The other customer's ID. The reason to use this node rather than Create Entity, which never gave you one |
relationshipId | string | The relationship's ID |
contactCreated | boolean | Whether the customer was created or already existed |
matchCount | number | How many customers shared that identity |
contactBorrowerId is what you feed into
Customer Update's Customer ID from a variable, or
into the Deal node's Add contact mode, to keep working on
the guarantor rather than on the person in the conversation.
A Create with no outputs configured still writes the relationship; it leaves a warning notice and continues.
Read
Read returns the conversation's customer's relationships. It writes nothing.
The customer is the conversation's own by default, or one whose ID sits in a flow variable. A variable with no customer ID in it exits through Error.
| Output | Type | What it holds |
|---|---|---|
relationships | object | The list, ordered by priority ascending |
count | number | How many entries |
Each entry carries contactId, relationship, isLegalRepresentative, priority,
ownershipPct and isActive.
A customer with no relationships is not an error. The list comes back empty and the node
continues, which is what lets a flow branch on count.
At most 50 relationships are returned, by priority. Beyond that a warning notice says so.
A Read with no outputs configured is an error, unlike Create: the relationships were read and thrown away, so the node exits through Error with "The relationships were read but no output variable is configured, so the whole read was thrown away."
Output Handles
| Handle | When |
|---|---|
| Continue | The relationship was written, or the list was read. Warnings (several identity matches, an unknown output key) still exit here |
| Error | Bad configuration, an identity that cannot be searched, a self-relationship, no customer, or a Read with no outputs |
Failures on this node leave a warning-level notice rather than an error-level one, even when they take the Error handle. That is deliberate: a misconfigured node is the tenant's problem, not an engineering incident, and it should not page anyone. Only an unexpected crash leaves an error-level notice.
Connect the Error handle. A failure through an unconnected Error handle sends the conversation to the channel connector's default responder — or, without one, leaves it with no active flow.
Notices are visible in the conversation's notices panel in Chat and aggregated in Flow Notices.
Things to Know
An output key the mode does not know is not an error. It leaves a warning notice — "'X' is not an output of this mode; variable 'Y' was left untouched" — and the node succeeds. A typo in an output key therefore produces a node that looks like it worked and saved nothing. Check the variable, not the handle.
contactBorrowerId is the whole point. Without it, a flow that collects a guarantor's
data has nowhere to put it.
A customer created for a contact has a blank label. They exist and carry the identity
you searched by, but nothing else. Follow the node with a
Customer Update pointed at contactBorrowerId to
fill in the name.
Ownership % belongs to shareholders only. Setting it on a guarantor is refused, not ignored.