Skip to navigation

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.

PrincipalRoleWho it describesExtra field
Businesscontrol_personThe person with the highest ownership in the businessownership_percentage
Businessbeneficial_ownerAny other person who owns more than 25% of the businessownership_percentage
Consumer (account holder)authorized_userA person added to the account holder’s accountrelationship_type

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

ActionAPI
Attach an owner or control person to a businessPOST /v2/businesses/{business_id}/relationships/
List a business’s relationshipsGET /v2/businesses/{business_id}/relationships/
Get one business relationshipGET /v2/businesses/{business_id}/relationships/{relationship_id}/
Attach an authorized user to a consumer’s accountPOST /v2/consumers/{consumer_id}/relationships/
Get one authorized-user relationshipGET /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.
  • The principal exists. Create the business with the 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

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.

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

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

Body

{
"related_consumer_id": "{owner's consumer id}",
"role": "control_person",
"ownership_percentage": "100.00"
}
FieldTypeRequiredDescription
related_consumer_idstring (UUID)YesThe id of the consumer to attach.
rolestringYescontrol_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_percentagedecimalYesThe 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

{
"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%:

{
"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.

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 parameterValuesDescription
rolebeneficial_owner, control_personOnly return relationships with this role.
statusactive, removedOnly 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:

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.

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

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

Body

{
"related_consumer_id": "{authorized user's consumer id}",
"role": "authorized_user",
"relationship_type": "spouse"
}
FieldTypeRequiredDescription
related_consumer_idstring (UUID)YesThe id of the consumer to add as an authorized user. It can’t be the account holder.
rolestringYesAlways authorized_user.
relationship_typestringYesWhat 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

{
"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"
}

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.

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.

FieldTypeDescription
idstring (UUID)The relationship’s id.
principal_idstring (UUID)The id of the business, or of the consumer who holds the account.
principal_typestringbusiness or consumer.
related_consumer_idstring (UUID)The id of the attached consumer.
rolestringbeneficial_owner, control_person or authorized_user.
ownership_percentagenumber or nullSet for business relationships, null otherwise.
relationship_typestring or nullSet for authorized-user relationships, null otherwise.
statusstringactive or removed.
created_atstring (date-time)When the relationship was first created.

Errors

StatusBusiness relationshipsAuthorized users
400 Bad RequestA 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 ForbiddenThe token is a user-scoped (customer) token, or lacks the required scope.The token lacks the required scope.
404 Not FoundThe 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.