Add a beneficial owner

post

https://api.everee.com/integration/v1/partner/companies/{companyId}/beneficial-owners

Add a person or entity that owns 25% or more of the company.

Use this endpoint to add a beneficial owner: a person or legal entity that owns 25% or more of the company. Add one call per owner.

📘
Part of People and ownership. For how this fits into onboarding, see the guide: Collecting company information: the people.

Owner types

ownerType: PERSON (the default): the person fields and identity describe the owner.
ownerType: ENTITY: the owner is a legal entity. entityName, entityEin, representativeOwnershipPercentage and the representative's title are all required, and the person fields and identity describe the individual who represents the entity.

ownershipPercentage is from 25 to 100. Together with the control person's percentage and the other owners' it can't exceed 100% (a 400 otherwise).

identity takes either an ssn, or a passportNumber and passportCountry, but not both.

You also need to make an ownership declaration of hasAdditionalOwners: true for the owners to count.

When you can call this

While the onboarding is a DRAFT and the contract documents haven't been signed.
While the onboarding is UNDER_REVIEW, only to answer an open ADDITIONAL_PERSON_DETAILS review request. Pass that request's ID as requestId. Adding the owner resolves the request, sends the new owner their identity-verification link, and voids the signed contract so that a new signature is requested, with the new owner on the documents.

Otherwise it returns 409.

Errors

Status	Meaning
`400`	`identity` is invalid, an `ENTITY` owner is missing required details, or ownership would total more than 100%.
`401`	The API key is missing, malformed or expired.
`404`	No company with this ID belongs to your partner account.
`409`	The onboarding can no longer be edited this way, or the contract has been signed.
`422`	A required field is missing or malformed, or `ownershipPercentage` is outside 25 to 100.

Path Params

companyId

integer

required

The company's ID, as returned when the company was created.

Query Params

requestId

integer

The ID of an open ADDITIONAL_PERSON_DETAILS request. Required when the onboarding is under review; not used on a draft.

Body Params

firstName

string

required

lastName

string

required

title

string

Job title or role at the company.

string

required

Email address. The person's identity-verification link is sent here.

phone

string

required

10-digit US phone number. Formatting characters are allowed. The person's identity-verification link is sent here.

identity

object

required

The details Everee uses to verify the person.

ownerType

string

enum

Whether the owner is an individual or a legal entity. Defaults to PERSON. For an ENTITY, the person fields describe the individual who represents the entity.

Allowed:

ownershipPercentage

number

required

25 to 100

The percentage of the company the owner holds, from 25 to 100.

entityName

string

The entity's name. Required for an ENTITY owner.

entityEin

string

The entity's 9-digit EIN. Required for an ENTITY owner.

representativeOwnershipPercentage

number

0.01 to 100

The percentage of the entity the representative owns, from 0.01 to 100. Required for an ENTITY owner.

Responses

Language

Credentials

Header

Loading…

Response

Choose an example:

application/json

Owner types

When you can call this

Errors

200The beneficial owner that was added.

400identity is invalid, an ENTITY owner is missing its entity name, EIN, title or representative percentage, or the ownership percentages would add up to more than 100%.

401The API key is missing, malformed or expired.

404No company with this ID belongs to your partner account.

409The onboarding is no longer a draft (and no matching open request was identified with requestId), or the contract has been signed.

422The request body is invalid. For example, a required field is missing or a value is malformed.