Skip to main content
Use related parties when you onboard a business (know your business, or KYB). You create a profile for the business, record its organization details, and then add the people and companies connected to it: beneficial owners, shareholders, directors and officers, signing authorities, trustees, parent companies, and others. Each related party is a profile of its own, so it is screened and monitored like any other profile, and the business’s profile shows who is connected to it and how.
Beta: available on request. Related parties must be enabled for your organization before you can use these endpoints and fields. Contact your Minerva representative or support@gominerva.com to enable them. Until then, the relationship endpoints, and any profile update that includes an organization field, return HTTP 403 with profile_relationships.not_enabled.

Before you start

You need an application API key for the workspace you onboard into. Send it in the x-api-key header. See API Keys for how keys are created and scoped. A request without the x-api-key header returns HTTP 401. A key that isn’t valid returns HTTP 403 or HTTP 404, and a malformed key value, for example one that contains a space such as Bearer <key>, returns HTTP 400 with msg Bad Request. On the relationship endpoints (/profiles/{profileId}/relationships and the paths under it), a 404 for a profile or relationship that doesn’t exist has a msg that starts with profile_relationships.not_found, so a 404 whose msg doesn’t start with it means the key wasn’t recognised. On the profile endpoints, such as GET /profiles/{profileId}, an unknown profile and an unrecognised key both return a 404 without a code. The examples use https://api.gominerva.com/clm/v1 and read your key from the MINERVA_API_KEY environment variable:
All profiles in a relationship must be in the workspace of your API key. You can’t relate profiles across workspaces.

Steps

1. Create the organization profile

Create the business as an organization profile with POST /onboarding/profiles, which creates the profile and screens it. Keep the returned result.profile.id.
To create it without screening, use POST /profiles instead. Neither call saves the organization fields in step 2: they’re ignored without an error, so add them with an update. If a profile with the same externalId already exists in the workspace, POST /profiles updates that profile instead of creating a new one. To relate a profile that already exists, link it with party.externalId instead of creating it again; see Link an existing profile or create a new one.

2. Add the organization details

Update the profile with its organization details. Every field is optional, and a field you omit is left unchanged.
To clear a field, send "", or [] for tradingNames. These fields can only be set on organization profiles; on an individual’s profile the update returns HTTP 400. Add each related party with its own request. A party is either a new profile, which Minerva creates and screens, or a profile you already have.
A successful call returns HTTP 201 with the outcome, the new relationship, a summary of the party’s profile, and the screening status:
In the response, the business is the subject (subjectProfileId) and the party is the related profile (relatedProfileId). The relationship object is shortened here; the endpoint reference lists every field. When a call creates a new party, it also screens it, so the call can take up to a minute. Set your client timeout to allow for it, and see Retries and idempotency before you retry. Repeat step 3 for each party. To see everything you’ve added, call GET /profiles/{profileId}/relationships.

Relationship types

relationshipTypes says what the party is to the business. Send one or more: ownershipPercent is optional: a number from 0 to 100 with at most two decimal places. When you send it, also send ownershipBasis: direct, or indirect_declared for ownership held through another company, as declared by your client. Minerva doesn’t calculate indirect ownership. Ownership can’t be recorded when the only type is subsidiary. meetsThreshold in the response is true when the party owns 25% or more through ubo, shareholder, parent_company, or ultimate_parent. It is informational and doesn’t block anything. Relationships can only be added to organization profiles. Adding one to an individual’s profile returns HTTP 400 with profile_relationships.subject_not_organization. The party object takes exactly one of: Linking an existing profile creates nothing new: the profile isn’t screened again and its monitoring settings don’t change. The response has outcome: "linked_existing". A new party is created with screening and ongoing monitoring turned on. Custom fields, profile groups, and other profile settings aren’t accepted here; set them afterwards with PATCH /profiles/{profileId}.

Possible duplicates

Before it creates a new party, Minerva looks for a profile in your workspace that may be the same party: the same name and date of birth for an individual, or the same name and registration number for an organization. If it finds one, nothing is created and the call returns HTTP 409 with profile_relationships.needs_review and up to five candidates:
Then do one of the following:
  • Send the request again with "party": { "profileId": "<candidate profileId>" } to link the existing profile.
  • Send the same request again with "onMatch": "create" to create a new profile anyway. The relationship records that you chose to create it.
You can reuse the same X-Idempotency-Key, because nothing was saved. needs_review is also returned when a new party’s externalId is already used by a profile in the workspace (reason: "external_id_exists"), and when a party.externalId matches more than one profile (reason: "external_id_ambiguous"). A party can have only one active relationship with the same business. Adding it again returns HTTP 409 with profile_relationships.duplicate_active and the existing relationshipId. To change the types or ownership of a relationship, end it and add it again.

Retries and idempotency

Every POST /profiles/{profileId}/relationships call needs an X-Idempotency-Key header of up to 200 bytes (200 ASCII characters). Use a new key for each party. After a call succeeds, use a new key for any change to it. If a call was refused and nothing was saved, you can fix it and send it again with the same key. Keys are scoped to the organization profile in the path. The key is tied to these fields:
  • The party: its profileId or externalId when you link a profile. For a new party, its kind and externalId, or, if it has no externalId, its kind, name, and date of birth or registration number.
  • relationshipTypes, ownershipPercent, ownershipBasis, and onMatch.
It isn’t tied to any other field, such as relationshipLabel, addNote, clientKey, or a new party’s address.
clientKey is your own label for a party. It’s returned in successful responses (HTTP 200 and 201) and in needs_review responses. A repeat with the same X-Idempotency-Key returns the original clientKey. It isn’t an idempotency key: only X-Idempotency-Key prevents duplicates.

Screening

A new party is screened as part of the call. screeningStatus in the response tells you what happened:
Created, not screened. With pending_credits or screening_unavailable, the party’s profile and relationship are saved. The party isn’t screened yet, and it isn’t monitored (monitored: "not_monitored") until it is. Screen it from its profile in the Minerva dashboard. Don’t add the party again to get it screened: the relationship already exists. A second call usually returns duplicate_active or needs_review, but if the new party has no externalId and no date of birth (individual) or registration number (organization), it creates and screens a second profile. Send an externalId with new parties, and list the relationships before you add a party again.

End a relationship or archive a profile

To record that a party is no longer related, end the relationship:
endReason is required: no_longer_related, entered_in_error, duplicate_profile, or other. With other, endNote is required. Ending a relationship doesn’t delete it. It stays in the history, with who ended it, when, and why, and GET returns it with include=ended. Ending only affects the relationship:
  • The party’s profile is unchanged and stays monitored. If you no longer need it, archive the party’s profile separately.
  • Archiving a profile doesn’t end its relationships. You can’t add relationships to an archived organization profile or link an archived party’s profile (HTTP 409, profile_relationships.profile_archived).

Record the ownership conclusion

When you’ve reviewed who owns the business, record your conclusion on the business’s profile:
conclusion is one of owners_identified, no_individual_meets_threshold, exempt (send exemptReason), or unable_to_obtain. Always send it: an ownershipConclusion without conclusion clears the recorded conclusion, even if you only meant to change conclusionSteps. To clear the conclusion, send "ownershipConclusion": { "conclusion": "" }; null leaves it unchanged. Minerva records who set the conclusion and when. The conclusion is a record only; it doesn’t change the profile’s status or risk rating. To record that you confirmed a party’s declared ownership, verify the relationship with POST /profiles/{profileId}/relationships/{relationshipId}/verify. Its ownershipSource changes from client_declared to analyst_verified, with who verified it and when.

Limits

  • One related party, and one relationship, per call.
  • To add the owners of a parent company, first add the parent company to the business, then call POST /profiles/{profileId}/relationships on the parent company’s own profile.
  • The API has no hard limit on how many related parties a business can have, or on how many levels of ownership you record. We currently recommend no more than 20 related parties per business.
  • GET /profiles/{profileId}/relationships returns up to 200 relationships, active first, and sets truncated: true when there are more.
  • Text fields: relationshipLabel up to 200 characters; addNote, endNote, verificationNote, exemptReason, and conclusionSteps up to 2,000 characters.
  • The ownership threshold for meetsThreshold is 25%.
Related parties are in Beta. To enable them for your organization, or to give feedback, contact your Minerva representative or support@gominerva.com.