Appearance

User Relationships Beta ​

The User Relationships system allows you to link entities together (e.g., legal entity with an individual, or two individuals) via a granular and dynamic role mapping.

This system aims to gradually replace the Parent-Children legacy hierarchical model with a flexible relationship graph. As opposed to the previous model, Relationships allow you to:

  • Modify a user's role after creation, which was previously impossible.
  • Accumulate multiple roles for a single user without having to create duplicate users.
  • Define relationships between a user and multiple companies.
  • Inject specific values associated with a relationship, such as the number of shares for an effective beneficiary.

Introduction ​

The Relationship object can be defined as the link between a source and its target users.

relationship illurelationship illu
  • Source user: The entity holding the relationship (e.g., a company or parent).
  • Target user: The linked individual (e.g., legal representative, shareholder, employee, minor).
  • Type (link): The nature of the relationship (e.g., LEGAL_REPRESENTATIVE).

Key attributes ​

Below are the main attributes you can find in the Relationship object.

AttributeTypeDescription
targetUserIdintegerThe unique identifier of the target User, linked to the entity.
sourceUserIdintegerThe unique identifier of the source User; holding the relationship.
relationTypeIdintegerThe type of relationship between the source user and the target user. See the types of relation.
relationTypeNamestringThe name of the relationship between the source user and the target user. See the types of relation.
valuestringAssociated value if included with the role (e.g., % of shares for EFFECTIVE_BENEFICIARY_SHARES).

Types of relation ​

Below is the list of currently supported relation types. Please note the list will evolve as Treezor deprecates Parent-Children relations for User Relationships.

relationTypeIdrelationTypeNameDescription
1LEGAL_REPRESENTATIVELinks a company (source) with its legal representative (target).
A Legal Representative is an individual legally authorized to act on behalf of a company, typically to exercise rights, fulfill obligations, or provide formal consent in legal and administrative matters.
2EFFECTIVE_BENEFICIARY_SHARESLinks a company (source) with its shareholders (target). Shareholders must declare their shares with the value attribute (e.g., "34.11").
An Effective Beneficiary, often referred to as a Ultimate Beneficial Owner, is a natural person who ultimately owns or controls a company, either through direct or indirect ownership of a significant percentage of shares or voting rights. Treezor documentation refers to them as Shareholders.
3COMPANY_REPRESENTATIVELinks a company (source) with its representative (target).
A Company Representative is a specific type of legal relationship where an individual is granted the formal power to execute documents and enter into binding agreements on behalf of a company. This relationship type is often defined by a specific scope of authority or a board resolution.
4EMPLOYEELinks a company (source) with its employees (target).
This type of link is used for employee benefits use cases for instance.
5CHILDLinks a parent individual (source) to their children (target).
A Parent Child relation represents a legal or biological connection where a parent holds the authority and responsibility to act in the best interests of a minor or dependent.
6ASSITEDLinks an assistant (source) to an assisted (target).
An Assistant-Assisted relation identifies a support structure where the assistant provides administrative, operational, or decision-support services to an individual without necessarily holding the power of legal representation.

The relationship object ​

json
{
  "relationshipId": 888,
  "targetUserId": 200,    // Target
  "sourceUserId": 101,    // Source
  "relationTypeId": 2,    // Nature
  "relationTypeName": "LEGAL_REPRESENTATIVE",
  "value": null
}

Creating a Relationship ​

Paperclip icon

Prerequisites – You must create the users first

You must first declare both the source and target users using the /v1/users endpoint.

Parameters ​

Below are the parameters for creating a relationship.

Please note the creation must always be done from the target user, which is identified with the targetUserId path parameter of the relationship creation request.

AttributeTypeDescription
sourceUserId integerThe unique identifier of the user who is the source of the current one (e.g., legal entity, parent).
relationTypeId integerThe type of relationship between the source user and the current user. See the types of relation.
value stringAssociated value if included with the type (e.g., % of shares for EFFECTIVE_BENEFICIARY_SHARES). Might be required depending on the relationTypeId.

To declare a legal representative, you create a relationship linking the target user (individual) to the source (legal entity).

Endpoint: /v1/users/{userId}/relationships

bash
curl -X POST '{baseUrl}/v1/users/{targetUserId}/relationships' \
  --header 'Authorization: Bearer {accessToken}' \
  --header 'Content-Type: application/json' \
  -d '{payload}'

Here is an example of {payload}:

json
{
  "sourceUserId": 101,
  "relationTypeId": 1
}

Returns the created Relationship object:

json
{
  "relationshipId": 888,
  "targetUserId": 200,
  "sourceUserId": 101,
  "relationTypeId": 1,
  "relationTypeName": "LEGAL_REPRESENTATIVE",
  "value": null
}

Declaring an effective beneficiary ​

This shareholder type of relationship requires a mandatory associated value for the percentage of shares an effective beneficiary holds.

Endpoint: /v1/users/{userId}/relationships

bash
curl -X POST '{baseUrl}/v1/users/{targetUserId}/relationships' \
  --header 'Authorization: Bearer {accessToken}' \
  --header 'Content-Type: application/json' \
  -d '{payload}'

Here is an example of {payload}:

json
{
  "sourceUserId": 101,
  "relationTypeId": 2,
  "value": "45.75"
}

Returns the created Relationship object:

json
{
  "relationshipId": 1498,
  "targetUserId": 202,
  "sourceUserId": 101,
  "relationTypeId": 2,
  "relationTypeName": "EFFECTIVE_BENEFICIARY_SHARES",
  "value": "45.75"
}

Treezor also sends a user.relationship.create webhook.

Retrieving relationships ​

You can retrieve the list of relationships for a given user.

Endpoint: /v1/users/{targetUserId}/relationships

bash
curl -X GET '{baseUrl}/v1/users/{targetUserId}/relationships' \
  --header 'Authorization: Bearer {accessToken}'

Returns a paginated list of relationships:

json
{
  "metadata":{
    "page": 0,
    "pageAvailable": 10
  },
  "relationships": [
    {
      "relationshipId": 1498,
      "targetUserId": 202,
      "sourceUserId": 101,
      "relationTypeId": 2,
      "relationTypeName": "EFFECTIVE_BENEFICIARY_SHARES",
      "value": "45.75"
    }
  ]
}

Deleting a relationship ​

To remove a relationship (e.g., the user is no longer a legal representative of a given company), you can delete the specific relationship.

This action is irreversible; you will have to create a new relationship if the need arise.

Request example ​

Endpoint: /v1/user/{targetUserId}/relationships/{relationshipId}

bash
curl -X DELETE '{baseUrl}/v1/user/{targetUserId}/relationships/{relationshipId}' \
  --header 'Authorization: Bearer {accessToken}'

Treezor also sends a user.relationship.cancel webhook.

Endpoints ​

EndpointScope
/v1/users/{targetUserId}/relationships
Create a new relationship for a user.		read_write
/v1/users/{targetUserId}/relationships
Retrieve the relationships of a user.		read_only
/v1/user/{targetUserId}/relationships/{relationshipId}
Remove an existing relationship.		read_only