> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.upwardli.com/llms.txt.

# Owners, Control Persons and Authorized Users

## Overview

You can record the people connected to the businesses and accounts you manage on Upward:

* On a **business**, its beneficial owners and control persons.
* On a **consumer's account**, its authorized users.

Each connection is a **relationship**. A relationship links a **principal** (the business, or the consumer who holds the account) to one of your consumers in one **role**.

| Principal                 | Role               | Who it describes                                        | Extra field            |
| ------------------------- | ------------------ | ------------------------------------------------------- | ---------------------- |
| Business                  | `control_person`   | The person with the highest ownership in the business   | `ownership_percentage` |
| Business                  | `beneficial_owner` | Any other person who owns more than 25% of the business | `ownership_percentage` |
| Consumer (account holder) | `authorized_user`  | A person added to the account holder's account          | `relationship_type`    |

> **Note**
>
> A relationship records the connection only. It does not onboard the attached person or change their identity verification status. Onboard each person as a consumer before you attach them.

### Endpoints at a Glance

| Action                                            | API                                                                 |
| ------------------------------------------------- | ------------------------------------------------------------------- |
| Attach an owner or control person to a business   | `POST /v2/businesses/{business_id}/relationships/`                  |
| List a business's relationships                   | `GET /v2/businesses/{business_id}/relationships/`                   |
| Get one business relationship                     | `GET /v2/businesses/{business_id}/relationships/{relationship_id}/` |
| Attach an authorized user to a consumer's account | `POST /v2/consumers/{consumer_id}/relationships/`                   |
| Get one authorized-user relationship              | `GET /v2/consumers/{consumer_id}/relationships/{relationship_id}/`  |

---

## Before You Start

* **Your token has the right scope.** Creating a relationship needs `api:write`. Reading one needs `api:read`.
* **You use a partner token for businesses.** Business relationship endpoints reject user-scoped (customer) tokens with `403 Forbidden`. Authorized-user endpoints accept a partner token for any of your consumers, or a user-scoped token for that consumer's own account only. See [Token Exchange](/concepts/authentication/token-exchange).
* **The principal exists.** Create the business with the [create business](/api-access/api-reference/businesses/create-business) API, or onboard the account holder as a consumer.
* **Every attached person is one of your consumers.** Create each owner, control person or authorized user as a consumer first and keep their `id`. A business can't be attached as a related person, and consumers from another program can't be attached.

---

## Business Owners and Control Persons

> **Note**
>
> The control person is the person with the highest ownership in the business. Add each other person who owns more than 25% of the business as a beneficial owner.

In this example, the business has a single owner who holds 100% of it, so they are attached as its control person.

### Step 1: Attach the Control Person

See the [create business relationship](/api-access/api-reference/businesses/relationships/create-business-relationship) API.

POST `https://api-sandbox.upwardli.com/v2/businesses/{business_id}/relationships/`

```json
Header
{
    "Authorization":"Bearer [access_token]",
    "Content-Type":"application/json"
}
```

Body

```json
{
  "related_consumer_id": "{owner's consumer id}",
  "role": "control_person",
  "ownership_percentage": "100.00"
}
```

| Field                  | Type          | Required | Description                                                                                                                                        |
| ---------------------- | ------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `related_consumer_id`  | string (UUID) | Yes      | The `id` of the consumer to attach.                                                                                                                |
| `role`                 | string        | Yes      | `control_person` for the person with the highest ownership in the business. `beneficial_owner` for each other person who owns more than 25% of it. |
| `ownership_percentage` | decimal       | Yes      | The share of the business the person owns, from `0` to `100` with up to two decimal places.                                                        |

Do not send `relationship_type` on a business relationship; the request is rejected with `400 Bad Request`.

Response `201 Created`

```json
{
  "id": "{relationship id}",
  "principal_id": "{business id}",
  "principal_type": "business",
  "related_consumer_id": "{owner's consumer id}",
  "role": "control_person",
  "ownership_percentage": 100.0,
  "relationship_type": null,
  "status": "active",
  "created_at": "2026-11-02T15:04:12Z"
}
```

Save the relationship `id`.

### Step 2: Attach Beneficial Owners

If more than one person owns the business, attach the person with the highest ownership as the control person with their own share, then attach each other person who owns more than 25% as a beneficial owner. For example, if the control person owns 60% and a second person owns 40%:

```json
{
  "related_consumer_id": "{second owner's consumer id}",
  "role": "beneficial_owner",
  "ownership_percentage": "40.00"
}
```

Each relationship is validated on its own, so make sure the percentages you send for a business are accurate.

### Step 3: Read the Business's Relationships

See the [list business relationships](/api-access/api-reference/businesses/relationships/list-business-relationships) API.

GET `https://api-sandbox.upwardli.com/v2/businesses/{business_id}/relationships/`

Results are paginated with `page` and `page_size`, and returned oldest first. You can filter them:

| Query parameter | Values                               | Description                                                                                 |
| --------------- | ------------------------------------ | ------------------------------------------------------------------------------------------- |
| `role`          | `beneficial_owner`, `control_person` | Only return relationships with this role.                                                   |
| `status`        | `active`, `removed`                  | Only return relationships with this status. Without it, removed relationships are included. |

For example, to list the current owners only:

GET `https://api-sandbox.upwardli.com/v2/businesses/{business_id}/relationships/?role=beneficial_owner&status=active`

To read a single relationship, use the [get business relationship](/api-access/api-reference/businesses/relationships/get-business-relationship) API:

GET `https://api-sandbox.upwardli.com/v2/businesses/{business_id}/relationships/{relationship_id}/`

---

## Authorized Users

An authorized user is attached to the consumer who holds the account. In the path, use the account holder's `id`. In the body, send the authorized user's `id`.

### Step 1: Attach the Authorized User

See the [create consumer relationship](/api-access/api-reference/consumers/relationships/create-consumer-relationship) API.

POST `https://api-sandbox.upwardli.com/v2/consumers/{account holder's consumer id}/relationships/`

```json
Header
{
    "Authorization":"Bearer [access_token]",
    "Content-Type":"application/json"
}
```

Body

```json
{
  "related_consumer_id": "{authorized user's consumer id}",
  "role": "authorized_user",
  "relationship_type": "spouse"
}
```

| Field                 | Type          | Required | Description                                                                                   |
| --------------------- | ------------- | -------- | --------------------------------------------------------------------------------------------- |
| `related_consumer_id` | string (UUID) | Yes      | The `id` of the consumer to add as an authorized user. It can't be the account holder.        |
| `role`                | string        | Yes      | Always `authorized_user`.                                                                     |
| `relationship_type`   | string        | Yes      | What the account holder is to the authorized user: `parent`, `guardian`, `spouse` or `other`. |

Do not send `ownership_percentage` on an authorized-user relationship; the request is rejected with `400 Bad Request`.

Response `201 Created`

```json
{
  "id": "{relationship id}",
  "principal_id": "{account holder's consumer id}",
  "principal_type": "consumer",
  "related_consumer_id": "{authorized user's consumer id}",
  "role": "authorized_user",
  "ownership_percentage": null,
  "relationship_type": "spouse",
  "status": "active",
  "created_at": "2026-11-03T10:22:51Z"
}
```

> **Note**
>
> There is no endpoint to list a consumer's authorized users. Save the relationship `id` from this response; you need it to read the relationship later.

### Step 2: Read the Relationship

See the [get consumer relationship](/api-access/api-reference/consumers/relationships/get-consumer-relationship) API.

GET `https://api-sandbox.upwardli.com/v2/consumers/{account holder's consumer id}/relationships/{relationship_id}/`

Read it under the account holder's `id`. The same relationship is not found under the authorized user's `id`.

---

## Updating a Relationship

A principal, an attached consumer and a role form one relationship for its whole life. To change it, send the same create request again with the new value:

* For a business relationship, the new `ownership_percentage` replaces the old one.
* For an authorized-user relationship, the new `relationship_type` replaces the old one.

When the relationship already exists, the response is `200 OK` instead of `201 Created`, and it returns the same relationship `id`. This also makes the create request safe to retry: if a request times out, send it again and you will never get a duplicate.

## Removed Relationships

A relationship that is no longer in effect has the status `removed`. Removed relationships stay readable so you can see a business's or account's history.

Relationships can't be removed through the API. To remove one, contact your Upward representative. If you later send a create request for a removed relationship, it becomes `active` again with the values you sent.

---

## Relationship Object

Every relationship endpoint returns the same object.

| Field                  | Type               | Description                                                         |
| ---------------------- | ------------------ | ------------------------------------------------------------------- |
| `id`                   | string (UUID)      | The relationship's `id`.                                            |
| `principal_id`         | string (UUID)      | The `id` of the business, or of the consumer who holds the account. |
| `principal_type`       | string             | `business` or `consumer`.                                           |
| `related_consumer_id`  | string (UUID)      | The `id` of the attached consumer.                                  |
| `role`                 | string             | `beneficial_owner`, `control_person` or `authorized_user`.          |
| `ownership_percentage` | number or null     | Set for business relationships, `null` otherwise.                   |
| `relationship_type`    | string or null     | Set for authorized-user relationships, `null` otherwise.            |
| `status`               | string             | `active` or `removed`.                                              |
| `created_at`           | string (date-time) | When the relationship was first created.                            |

## Errors

| Status                     | Business relationships                                                                                                                                      | Authorized users                                                                                                                                   |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400 Bad Request`          | A required field is missing, the role is not `beneficial_owner` or `control_person`, `relationship_type` was sent, or the related entity is not a consumer. | A required field is missing, `ownership_percentage` was sent, the related consumer is the account holder, or the related entity is not a consumer. |
| `403 Forbidden`            | The token is a user-scoped (customer) token, or lacks the required scope.                                                                                   | The token lacks the required scope.                                                                                                                |
| `404 Not Found`            | The business or the related consumer does not exist or is not one of yours, or the relationship does not belong to this business.                           | The related consumer does not exist or is not one of yours, or the relationship does not belong to this account holder.                            |
| `422 Unprocessable Entity` | —                                                                                                                                                           | The account holder does not exist, is not one of your consumers, or is not the consumer of the user-scoped token used.                             |