curl --request POST \
--url https://api.gominerva.com/clm/v1/profiles/{profileId}/relationships \
--header 'Content-Type: application/json' \
--header 'X-Idempotency-Key: <x-idempotency-key>' \
--header 'x-api-key: <api-key>' \
--data @- <<EOF
{
"party": {
"profile": {
"kind": "individual",
"name": "Margaret Ostrander",
"dateOfBirth": "1971-04-22",
"address1": "14 Lighthouse Lane",
"addressCity": "Halifax",
"addressState": "NS",
"addressPostalCode": "B3H 1Z9",
"country": "Canada",
"nationality": "Canada",
"externalId": "NHL-UBO-001"
}
},
"relationshipTypes": [
"ubo"
],
"ownershipPercent": 62.5,
"ownershipBasis": "direct",
"addNote": "Declared on the client's beneficial ownership form dated 2026-11-12.",
"clientKey": "party-1"
}
EOF{
"msg": "OK",
"status": 200,
"result": {
"outcome": "created",
"relationship": {
"id": "6735a2d04f1e2b7a9c0d2f11",
"subjectProfileId": "6735a1c94f1e2b7a9c0d1e01",
"relatedProfileId": "6735a1c94f1e2b7a9c0d1e02",
"workspaceId": "6720f0aa3b9c4d5e6f708192",
"relationshipTypes": [
"ubo"
],
"relationshipLabel": "",
"ownershipPercent": 62.5,
"ownershipBasis": "direct",
"ownershipSource": "client_declared",
"verificationNote": "",
"verifiedBy": "",
"verifiedAt": null,
"thresholdAtCreation": 25,
"meetsThreshold": true,
"dedupDecision": "new_profile",
"dedupCandidateIds": null,
"source": "api",
"status": "active",
"addNote": "Declared on the client's beneficial ownership form dated 2026-11-12.",
"createdBy": "application-id",
"createdAt": "2026-11-13T15:04:05.123Z",
"updatedBy": "application-id",
"updatedAt": "2026-11-13T15:04:05.123Z",
"endedBy": "",
"endedAt": null,
"endReason": "",
"endNote": ""
},
"party": {
"id": "6735a1c94f1e2b7a9c0d1e02",
"name": "Margaret Ostrander",
"kind": "individual",
"status": "no_flags",
"monitored": "monitored",
"archived": false
},
"screeningStatus": "completed",
"clientKey": "party-1"
}
}Add a related party
Beta: available on request. Contact your Minerva representative or support@gominerva.com to enable related parties for your organization. Until they are enabled, this endpoint returns HTTP 403 with profile_relationships.not_enabled.
Adds one related party to an organization profile: link an existing profile (party.profileId or party.externalId) or create a new one (party.profile). A new party is screened and monitored when it is created; if screening cannot run, the party is still created and the response says so in screeningStatus. Linking an existing profile does not screen it or change its monitoring. The call can take up to about a minute while a new party is screened.
Send one request per party. To add the owners of a related organization, call this endpoint on that organization’s own profile.
A repeat of a completed request with the same X-Idempotency-Key returns 200 with the original result and adds nothing. The key is tied to only some fields of the request (see X-Idempotency-Key), so use a new key for each party, and a new key for any change to a request that succeeded.
curl --request POST \
--url https://api.gominerva.com/clm/v1/profiles/{profileId}/relationships \
--header 'Content-Type: application/json' \
--header 'X-Idempotency-Key: <x-idempotency-key>' \
--header 'x-api-key: <api-key>' \
--data @- <<EOF
{
"party": {
"profile": {
"kind": "individual",
"name": "Margaret Ostrander",
"dateOfBirth": "1971-04-22",
"address1": "14 Lighthouse Lane",
"addressCity": "Halifax",
"addressState": "NS",
"addressPostalCode": "B3H 1Z9",
"country": "Canada",
"nationality": "Canada",
"externalId": "NHL-UBO-001"
}
},
"relationshipTypes": [
"ubo"
],
"ownershipPercent": 62.5,
"ownershipBasis": "direct",
"addNote": "Declared on the client's beneficial ownership form dated 2026-11-12.",
"clientKey": "party-1"
}
EOF{
"msg": "OK",
"status": 200,
"result": {
"outcome": "created",
"relationship": {
"id": "6735a2d04f1e2b7a9c0d2f11",
"subjectProfileId": "6735a1c94f1e2b7a9c0d1e01",
"relatedProfileId": "6735a1c94f1e2b7a9c0d1e02",
"workspaceId": "6720f0aa3b9c4d5e6f708192",
"relationshipTypes": [
"ubo"
],
"relationshipLabel": "",
"ownershipPercent": 62.5,
"ownershipBasis": "direct",
"ownershipSource": "client_declared",
"verificationNote": "",
"verifiedBy": "",
"verifiedAt": null,
"thresholdAtCreation": 25,
"meetsThreshold": true,
"dedupDecision": "new_profile",
"dedupCandidateIds": null,
"source": "api",
"status": "active",
"addNote": "Declared on the client's beneficial ownership form dated 2026-11-12.",
"createdBy": "application-id",
"createdAt": "2026-11-13T15:04:05.123Z",
"updatedBy": "application-id",
"updatedAt": "2026-11-13T15:04:05.123Z",
"endedBy": "",
"endedAt": null,
"endReason": "",
"endNote": ""
},
"party": {
"id": "6735a1c94f1e2b7a9c0d1e02",
"name": "Margaret Ostrander",
"kind": "individual",
"status": "no_flags",
"monitored": "monitored",
"archived": false
},
"screeningStatus": "completed",
"clientKey": "party-1"
}
}Authorizations
Headers
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.
200Body
The related party and the relationship.
Adds one related party to an organization profile.
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.
1ubo, shareholder, controlling_person, senior_managing_officer, director_officer, signing_authority, trustee, settlor, trust_beneficiary, parent_company, ultimate_parent, subsidiary, other ["ubo"]
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.
200"party-1"