Add a person relation to a business customer

POST 
/v1/customers/business/:businessUserId/related-persons

Adds a person relation (shareholder, representative, director, etc.) to a business customer.

Pre-approval (PENDING status): Stores relation in the onboarding data. Post-approval (APPROVED status): Creates a beneficial owner record via banking partner integration.

Hard constraints validated:

• At least 1 SHAREHOLDER required
• At least 1 REPRESENTATIVE required
• SHAREHOLDER ownership percentages must total ≥ 51%

Request

Path Parameters

businessUserId stringrequired

The ID of the business customer

application/json

Body

required

Person relation details to add

relation

object

required

userId stringrequired

User ID of the related person (shareholder, representative, etc.)

role stringrequired

Possible values: [REPRESENTATIVE, SHAREHOLDER]

Role of the person in the business

ownershipPercentage string

Ownership percentage as a string (required for SHAREHOLDER role, e.g. "51", "30.5")

representingRange

object

required

Representing date range (period of beneficial ownership)

startDate stringrequired

Start date of the representing period (ISO 8601)

endDate string

End date (ISO 8601, omit for open-ended)

Responses

201

The person relation was successfully added.

application/json

Schema

Schema

traceId string
message string

data

object

personRelations

object[]

required

Updated list of person relations

Array [

userId stringrequired

User ID of the related person

role stringrequired

Role of the person in the business

ownershipPercentage string

Ownership percentage (present for SHAREHOLDER role)

]

action stringrequired

Possible values: [ADD, UPDATE, REMOVE]

Action that was performed

Example (from schema)

{
  "traceId": "string",
  "message": "string",
  "data": {
    "personRelations": [
      {
        "userId": "123e4567-e89b-12d3-a456-426614174021",
        "role": "SHAREHOLDER",
        "ownershipPercentage": "51"
      }
    ],
    "action": "ADD"
  }
}

400

Invalid request payload. This can happen if required fields are missing or have invalid formats.

application/json

Schema

Schema

traceId string
message string

Example (from schema)

{
  "traceId": "string",
  "message": "string"
}

403

The API key is invalid or the client does not have sufficient permissions.

application/json

Schema

Schema

traceId string
message string

Example (from schema)

{
  "traceId": "string",
  "message": "string"
}

404

One of the specified resources was not found. Does not apply for empty result set.

application/json

Schema

Schema

traceId string
message string

Example (from schema)

{
  "traceId": "string",
  "message": "string"
}

Loading...