Before you start
You need an application API key for the workspace you onboard into. Send it in thex-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:
Steps
1. Create the organization profile
Create the business as anorganization profile with POST /onboarding/profiles, which creates the profile and screens it. Keep the returned result.profile.id.
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.
3. Add the related parties
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.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.
Link an existing profile or create a new one
Theparty 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 withprofile_relationships.needs_review and up to five candidates:
- 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.
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
EveryPOST /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
profileIdorexternalIdwhen you link a profile. For a new party, itskindandexternalId, or, if it has noexternalId, itskind, name, and date of birth or registration number. relationshipTypes,ownershipPercent,ownershipBasis, andonMatch.
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:
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}/relationshipson 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}/relationshipsreturns up to 200 relationships, active first, and setstruncated: truewhen there are more.- Text fields:
relationshipLabelup to 200 characters;addNote,endNote,verificationNote,exemptReason, andconclusionStepsup to 2,000 characters. - The ownership threshold for
meetsThresholdis 25%.