Skip to navigation

Create a Consumer Relationship

Attaches one of your consumers to another consumer’s account as an authorized user. The consumer in the path is the account holder. Sending a pairing that already exists updates that relationship instead of creating a new one: it is set back to active, its relationship_type is replaced and 200 OK is returned. Requires the api:write scope.

Authentication

AuthorizationBearer

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

Path parameters

consumer_external_idstringRequired

The id of the account holder.

Request

This endpoint expects an object.
related_consumer_idstringRequiredformat: "uuid"

The id of the consumer to add as an authorized user. It must be one of your consumers and can’t be the account holder.

roleenumRequired

Always authorized_user.

Allowed values:
relationship_typeenumRequired
What the account holder is to the authorized user.
Allowed values:

Response

The relationship already existed. It is now active and carries the relationship_type 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
404
Not Found Error
422
Unprocessable Entity Error