> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gominerva.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Onboard a business with related parties (Beta)

> Create an organization profile, record its organization details, and add its beneficial owners, directors, and other related parties through the Profiles API.

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.

> [!WARNING]
>
> **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](mailto: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](https://docs.gominerva.com/api-reference/api-keys.md) 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:

```bash theme={null}
export MINERVA_API_KEY="YOUR_API_KEY"
```

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`.

```bash theme={null}
curl -X POST "https://api.gominerva.com/clm/v1/onboarding/profiles" \
  -H "x-api-key: $MINERVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "organization",
    "name": "Northwind Harbour Logistics Inc.",
    "address1": "88 Quayside Road",
    "addressCity": "Halifax",
    "addressState": "NS",
    "addressPostalCode": "B3J 0A1",
    "country": "Canada",
    "externalId": "NHL-0001"
  }'
```

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](#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.

```bash theme={null}
curl -X PATCH "https://api.gominerva.com/clm/v1/profiles/6735a1c94f1e2b7a9c0d1e01" \
  -H "x-api-key: $MINERVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entityType": "corporation",
    "tradingNames": ["Northwind Harbour", "NHL Freight"],
    "registrationNumber": "NS-4471029",
    "incorporationCountry": "CA",
    "incorporationSubdivision": "CA-NS"
  }'
```

| Field | Values |
| - | - |
| `entityType` | `corporation`, `partnership`, `trust`, `non_profit`, or `other` |
| `tradingNames` | Up to 20 trading or "doing business as" names, each up to 200 characters. Replaces the stored list. |
| `registrationNumber` | Up to 200 characters. Also used to find possible duplicates when the organization is itself added as a related party. |
| `incorporationCountry` | ISO 3166-1 alpha-2 code, for example `CA` |
| `incorporationSubdivision` | ISO 3166-2 code that belongs to the country, for example `CA-NS` |
| `ownershipConclusion` | Your beneficial-ownership conclusion. See [Record the ownership conclusion](#record-the-ownership-conclusion). |
| `relatedPartiesStatus` | Your own record of whether every related party has been processed: `all_processed` or `action_needed`. You set it; Minerva doesn't calculate it, and it isn't an approval decision. |

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.

```bash theme={null}
curl -X POST "https://api.gominerva.com/clm/v1/profiles/6735a1c94f1e2b7a9c0d1e01/relationships" \
  -H "x-api-key: $MINERVA_API_KEY" \
  -H "X-Idempotency-Key: nhl-0001-party-1" \
  -H "Content-Type: application/json" \
  -d '{
    "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",
    "clientKey": "party-1"
  }'
```

A successful call returns HTTP 201 with the outcome, the new relationship, a summary of the party's profile, and the screening status:

```json theme={null}
{
  "msg": "Created",
  "status": 201,
  "result": {
    "outcome": "created",
    "screeningStatus": "completed",
    "clientKey": "party-1",
    "party": {
      "id": "6735a1c94f1e2b7a9c0d1e02",
      "name": "Margaret Ostrander",
      "kind": "individual",
      "status": "no_flags",
      "monitored": "monitored",
      "archived": false
    },
    "relationship": {
      "id": "6735a2d04f1e2b7a9c0d2f11",
      "subjectProfileId": "6735a1c94f1e2b7a9c0d1e01",
      "relatedProfileId": "6735a1c94f1e2b7a9c0d1e02",
      "relationshipTypes": ["ubo"],
      "ownershipPercent": 62.5,
      "ownershipBasis": "direct",
      "ownershipSource": "client_declared",
      "meetsThreshold": true,
      "status": "active"
    }
  }
}
```

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](https://docs.gominerva.com/api-reference/profile-management/add-a-related-party.md) 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](#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:

| Type | Party can be |
| - | - |
| `ubo` (beneficial owner), `controlling_person`, `senior_managing_officer`, `signing_authority` | Individual only |
| `parent_company`, `ultimate_parent`, `subsidiary` | Organization only |
| `shareholder`, `director_officer`, `trustee`, `settlor`, `trust_beneficiary` | Individual or organization |
| `other` | Either. Also send `relationshipLabel` to say what the relationship is. |

`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

The `party` object takes exactly one of:

| Field | Use it to |
| - | - |
| `profileId` | Link a profile you already have, by its Minerva ID. |
| `externalId` | Link a profile you already have, by your own reference. |
| `profile` | Create a new profile for the party. |

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`:

```json theme={null}
{
  "msg": "profile_relationships.needs_review: the party may already have a profile in this workspace",
  "status": 409,
  "result": {
    "outcome": "needs_review",
    "reason": "possible_duplicate",
    "clientKey": "party-1",
    "candidates": [
      {
        "profileId": "6735a1c94f1e2b7a9c0d1e05",
        "name": "Margaret Ostrander",
        "kind": "individual",
        "country": "Canada",
        "monitored": "monitored",
        "oldestOpenAlertAt": null,
        "dateOfBirth": "1971/04/22"
      }
    ]
  }
}
```

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.

| What happens | Response | What to do |
| - | - | - |
| You retry a call that already succeeded, with the same key | HTTP 200 with the original result. Nothing is added twice. | Use the result. |
| You send a key again with a change only in fields the key isn't tied to, such as `relationshipLabel`, `addNote` or `clientKey`, after the first call succeeded | HTTP 200 with the original result, including the original `clientKey`. Your change isn't saved. | Send the changed request with a new key. |
| You retry while the first call is still running | HTTP 429 with `profile_relationships.in_flight` and a `Retry-After` header | Wait for `Retry-After` seconds and retry with the same key. |
| You send a key again with a different party, `relationshipTypes`, `ownershipPercent`, `ownershipBasis` or `onMatch` | HTTP 422 with `profile_relationships.idempotency_key_reused` | Use a new key. |
| The call was refused, for example HTTP 400, 404 or `needs_review` | Nothing was saved | Fix the request and send it again. The same key works. |
| HTTP 500 with `profile_relationships.needs_reconcile` | The relationship may not have been saved. A profile may have been created and screened for the party under `result.partyProfileId`. Sending the request again with the same key normally returns the same error. | Don't send the party again yet. First list the relationships with `GET /profiles/{profileId}/relationships`. If the party is listed, the relationship was saved: linking it again returns HTTP 409 with `profile_relationships.duplicate_active` and the existing `relationshipId`. If it isn't listed, check whether the profile in `result.partyProfileId` exists, with `GET /profiles/{profileId}` or in the Minerva dashboard. If it exists, link it with `party.profileId` and a new key. If it doesn't, contact [support@gominerva.com](mailto:support@gominerva.com) before you send the party again: the party may already have been screened, and sending it again could screen it a second time. |
| Any other HTTP 500 or a timeout | The outcome is unknown | Retry with the same key. |

> [!NOTE]
>
> `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:

| `screeningStatus` | Meaning |
| - | - |
| `completed` | The party was screened and is monitored. |
| `pending_credits` | Created, not screened: your organization didn't have enough Credits. |
| `screening_unavailable` | Created, not screened: screening couldn't run at the time. |
| `not_applicable` | No screening was needed, for example because you linked an existing profile. |

> [!WARNING]
>
> **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:

```bash theme={null}
curl -X DELETE "https://api.gominerva.com/clm/v1/profiles/6735a1c94f1e2b7a9c0d1e01/relationships/6735a2d04f1e2b7a9c0d2f13" \
  -H "x-api-key: $MINERVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "endReason": "no_longer_related", "endNote": "Resigned as director effective 2026-11-20." }'
```

`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:

```bash theme={null}
curl -X PATCH "https://api.gominerva.com/clm/v1/profiles/6735a1c94f1e2b7a9c0d1e01" \
  -H "x-api-key: $MINERVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ownershipConclusion": {
      "conclusion": "owners_identified",
      "conclusionSteps": "Reviewed the shareholder register dated 2026-10-31 and the client'"'"'s declaration."
    },
    "relatedPartiesStatus": "all_processed"
  }'
```

`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%.

> [!TIP]
>
> Related parties are in Beta. To enable them for your organization, or to give
> feedback, contact your Minerva representative or
> [support@gominerva.com](mailto:support@gominerva.com).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.