Usage Info

This method establishes an ownership relationship between a Person and a Business entity, capturing essential information such as ownership type, percentage, and position within the company. Use this method when adding new stakeholders to a business, documenting changes in ownership structure, or completing beneficial ownership information for compliance purposes.

Request

Authentication: KSig1-HMAC-SHA256

Parameters

Parameter	Type	Required	Description
business_id	string	Yes	The Business to add this Owner to.
business_owner	object	No	The business_owner parameter defined in the table below.

Business_Owner Parameters

Parameter	Type	Required	Description
person_id	string	Yes	The Person to be added to the Business as an owner.
ownership_type	string	No	The type of ownership the person has over the business. Must be one of the BENEFICIAL_OWNERSHIP_TYPES.
ownership_percentage	integer	No	The amount of ownership the person has over the business. The range of allowed values is 0 to 100.
ownership_year_month	string	No	The month and year when the person first obtained significant ownership in the business. This must be in the YYYY-MM format and contain only digits [0-9] and dashes.
business_person_position	string	No	The position the person has within the business. Must be one of the BUSINESS_PERSON_POSITIONS .

Example

{
  "business_id": "b_7eobHllxknr7mfqbjnX2Pp",
  "business_owner": {
    "person_id": "p_4PYsekjAX8VMuAOfmW81C7",
    "ownership_type": "CONTROL_PRONG",
    "ownership_percentage": 45,
    "ownership_year_month": "2023-11",
    "business_person_position": "PRESIDENT"
  }
}

Response

Data

Parameter	Type	Description
business_owner	object	The business_owner parameter defined in the tables below.

Business Owner Parameters

Parameter	Type	Description
business_owner_id	string	The identifier for the Business Owner just created.

Example

{
  "meta": {
    "status": "SUCCESS",
    "trace_id": "trc_2h1MG0xRq9dPAPWLuygFk5",
    "version": "2025-03-24"
  },
  "data": {
    "business_owner": {
      "business_owner_id": "bo_5nCWRq51h3ILIJvOOhfF4i"
    }
  }
}

Errors

Error Code	HTTP Code	Possible Cause
ACCOUNT_CONFIGURATION_VIOLATION	400	Account configuration rule violations are described below.
BAD_REQUEST	400	Required parameters not provided. Invalid values provided. Enum value provided does not correspond to an available type.
ENTITY_NOT_FOUND	400	The `subject_record_id` provided does not exist.
SYSTEM_RULE_VIOLATION	400	System rule violations are described below.

Account Configuration Violations

When a ACCOUNT_CONFIGURATION_VIOLATION error occurs, the response will include additional entity_type and sub_code fields to provide more specific information:

Entity Type	Sub-code	Description
Business Owner	MINIMUM_OWNERSHIP_PERCENTAGE	Owner must have at least X% ownership to be added as a beneficial owner.
Business	MAX_OWNER_LIMIT	The maximum number of owners has been reached for this Business entity, as per stablished in the account configuration.

System Rule Violations

When a SYSTEM_RULE_VIOLATION error occurs, the response will include additional entity_type and sub_code fields to provide more specific information:

Entity Type	Sub-code	Description
Business	CONTROL_PRONG_AGE_REQUIREMENT	Control prong owners must be at least 18 years of age.
Business	DUPLICATE_OWNER_ASSOCIATION	This Person is already registered as an owner of this Business entity.
Business	MAX_OWNER_LIMIT	The maximum number of owners has been reached for this Business entity.
Business	OWNERSHIP_DATE_BEFORE_ESTABLISHED	The ownership date cannot precede the business establishment date. Ownership cannot begin before the business existed.
Business	OWNERSHIP_DATE_BEFORE_BIRTH_DATE	The ownership date cannot precede the person's date of birth.
Business	OWNERSHIP_PERCENTAGE_EXCEEDS_MAXIMUM	The total ownership percentage across all owners cannot exceed 100%. The current operation would result in a total ownership of X%.
Business	SINGLE_CONTROL_PRONG	Only one person can be designated as the control prong owner for a business entity.
Business	SOLE_PROPRIETORSHIP_OWNERSHIP_TYPE	Only 'CONTROL_PRONG' ownership type is allowed for a 'SOLE_PROPRIETORSHIP' Business entity.
Business	SOLE_PROPRIETORSHIP_OWNERSHIP_PERCENTAGE	'CONTROL_PRONG' owner in 'SOLE_PROPRIETORSHIP' Business entity must have 100% ownership.
Subject Record	CROSS_SUBJECT_RECORD_REFERENCE	The referenced entities must belong to the same subject record. Associations cannot be created between entities that exist in different subject records. The Person must belong to the same Subject Record as the Business specified in the business_id parameter.