Skip to main content
POST

Authorizations

x-api-key
string
header
required

The Minerva API key used for this integration. Manage API keys in the Minerva dashboard under Administration > Developers.

Headers

X-Idempotency-Key
string
required

Required. A unique key for this request, at most 200 bytes (200 ASCII characters). Keys are scoped to the organization profile in the path. Use a new key for each party, and a new key for any change to a request that succeeded. The key is tied only to the party (its profileId or externalId; for a new party, its kind and externalId, or, without an externalId, its kind, name and date of birth or registration number), relationshipTypes, ownershipPercent, ownershipBasis and onMatch. Sending the key again with a different value in any of these returns 422. A change to any other field, for example relationshipLabel, addNote, clientKey or a new party's address, is not detected: once the first request has completed, you get 200 with its original result, and the change is not saved.

Maximum string length: 200

Path Parameters

profileId
string
required

ID of the organization profile.

Body

application/json

The related party and the relationship.

Adds one related party to an organization profile.

party
object
required

The related party. Send exactly one of profileId, externalId or profile.

relationshipTypes
enum<string>[]
required

Required. One or more of: ubo, shareholder, controlling_person, senior_managing_officer, director_officer, signing_authority, trustee, settlor, trust_beneficiary, parent_company, ultimate_parent, subsidiary, other. Repeats are removed and the list is stored sorted. An individual cannot be parent_company, ultimate_parent or subsidiary; an organization cannot be ubo, controlling_person, senior_managing_officer or signing_authority.

Minimum array length: 1
Available options:
ubo,
shareholder,
controlling_person,
senior_managing_officer,
director_officer,
signing_authority,
trustee,
settlor,
trust_beneficiary,
parent_company,
ultimate_parent,
subsidiary,
other
Example:
addNote
string

Why the party was added, at most 2,000 characters.

Maximum string length: 2000
Example:

"Declared on the client's beneficial ownership form dated 2026-11-12."

clientKey
string

Your own reference for this party, at most 200 bytes (200 ASCII characters). Returned in the response, including needs_review responses, so you can match results to your records. A repeat with the same X-Idempotency-Key returns the clientKey of the original request, even if you sent a different one.

Maximum string length: 200
Example:

"party-1"

onMatch
enum<string>

Send create to create the new party even though possible duplicates were found (see the needs_review response). The decision is recorded on the relationship.

Available options:
create
Example:

"create"

ownershipBasis
enum<string>

Required with ownershipPercent, and rejected without it. direct, or indirect_declared for ownership held through another entity as declared by your client (Minerva does not calculate indirect ownership).

Available options:
direct,
indirect_declared
Example:

"direct"

ownershipPercent
number

The declared ownership, from 0 to 100 with at most two decimal places. Requires ownershipBasis. Not accepted when the only relationship type is subsidiary.

Required range: 0 <= x <= 100
Example:

62.5

relationshipLabel
string

What the relationship is, at most 200 characters. Required when relationshipTypes includes other, and rejected otherwise.

Maximum string length: 200
Example:

"Protector of the trust"

Response

Repeat of a completed request with the same X-Idempotency-Key. The body is the original result, including the original clientKey. Nothing new was added, and nothing that differs in this request was saved.

msg
string
Example:

"Created"

result
object
status
integer
Example:

201