Skip to navigation

Create a Business Relationship

Attaches one of your consumers to a business as a control person or a beneficial owner. The control person is the person with the highest ownership in the business; attach each other person who owns more than 25% as a beneficial owner. Sending a pairing of business, consumer and role that already exists updates that relationship instead of creating a new one: it is set back to active, its ownership_percentage is replaced and 200 OK is returned. Requires the api:write scope on a partner token.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

business_external_idstringRequired

The id of the business.

Request

This endpoint expects an object.
related_consumer_idstringRequiredformat: "uuid"

The id of the consumer to attach. It must be one of your consumers.

roleenumRequired

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.

Allowed values:
ownership_percentagestringRequiredformat: "decimal"
Share of the business the consumer owns, from 0 to 100 with up to two decimal places. Required for both roles.

Response

The relationship already existed. It is now active and carries the ownership_percentage you sent.

idstringformat: "uuid"

The id of the relationship.

principal_idstringformat: "uuid"

The id of the business, or of the consumer who holds the account, that the relationship belongs to.

principal_typeenum

Whether the principal is a business or a consumer.

Allowed values:
related_consumer_idstringformat: "uuid"

The id of the consumer attached to the principal.

ownership_percentagedouble or null0-100

Share of the business the attached consumer owns, from 0 to 100 with two decimal places. Set for business relationships, null otherwise.

relationship_typeenum or null

What the account holder is to the authorized user. Set for consumer relationships, null otherwise.

Allowed values:
roleenumOptionalRead-only

What the attached consumer is to the principal. A business grants beneficial_owner or control_person; a consumer grants authorized_user.

Allowed values:
statusenumOptionalRead-only

active while the relationship is in effect. Removed relationships stay readable with the status removed.

Allowed values:
created_atstringOptionalRead-onlyformat: "date-time"

Errors

400
Bad Request Error
403
Forbidden Error
404
Not Found Error