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.
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
Before You Start
- Your token has the right scope. Creating a relationship needs
api:write. Reading one needsapi: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/
Body
Do not send relationship_type on a business relationship; the request is rejected with 400 Bad Request.
Response 201 Created
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%:
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:
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/
Body
Do not send ownership_percentage on an authorized-user relationship; the request is rejected with 400 Bad Request.
Response 201 Created
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_percentagereplaces the old one. - For an authorized-user relationship, the new
relationship_typereplaces 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.

