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

# Add a related party

> **Beta: available on request.** Contact your Minerva representative or [support@gominerva.com](mailto: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.



## OpenAPI

````yaml /api-reference/profiles.json post /profiles/{profileId}/relationships
openapi: 3.1.0
info:
  title: Profiles API
  version: 1.0.0
  description: >-
    Customer-facing API endpoints for managing screening profiles and updating
    potential match review workflows.
servers:
  - description: The production API server for managing Minerva screening profiles.
    url: https://api.gominerva.com/clm/v1
security: []
tags:
  - name: Profile Management
    description: Create, list, update, and comment on screening workflow profiles.
  - name: Potential Matches
    description: Update review workflow state for potential matches returned by searches.
externalDocs:
  description: ''
  url: ''
paths:
  /profiles/{profileId}/relationships:
    post:
      tags:
        - Profile Management
      summary: Add a related party
      description: >-
        **Beta: available on request.** Contact your Minerva representative or
        [support@gominerva.com](mailto: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.
      parameters:
        - description: ID of the organization profile.
          example: 6735a1c94f1e2b7a9c0d1e01
          in: path
          name: profileId
          required: true
          schema:
            type: string
        - description: >-
            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.
          example: nhl-0001-party-1
          in: header
          name: X-Idempotency-Key
          required: true
          schema:
            type: string
            maxLength: 200
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/clm.ProfileRelationshipCreateRequest'
            examples:
              newIndividual:
                summary: Create and screen a new beneficial owner
                value:
                  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
              linkExisting:
                summary: Link an existing organization as parent company
                value:
                  party:
                    profileId: 6735a1c94f1e2b7a9c0d1e03
                  relationshipTypes:
                    - parent_company
                  ownershipPercent: 37.5
                  ownershipBasis: direct
                  clientKey: party-2
              createDespiteDuplicates:
                summary: Create after reviewing possible duplicates
                value:
                  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
                  onMatch: create
              newDirector:
                summary: Add a director with split name fields
                value:
                  party:
                    profile:
                      kind: individual
                      firstName: Daniel
                      lastName: Okafor
                      dateOfBirth: '1980-09-03'
                  relationshipTypes:
                    - director_officer
                  clientKey: party-3
        description: The related party and the relationship.
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/clm.CreateProfileRelationshipResponse'
              examples:
                replay:
                  summary: Replayed result
                  value:
                    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
          description: >-
            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.
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/clm.CreateProfileRelationshipResponse'
              examples:
                createdAndScreened:
                  summary: New party created and screened
                  value:
                    msg: Created
                    status: 201
                    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
                linkedExisting:
                  summary: Existing profile linked
                  value:
                    msg: Created
                    status: 201
                    result:
                      outcome: linked_existing
                      relationship:
                        id: 6735a2d04f1e2b7a9c0d2f12
                        subjectProfileId: 6735a1c94f1e2b7a9c0d1e01
                        relatedProfileId: 6735a1c94f1e2b7a9c0d1e03
                        workspaceId: 6720f0aa3b9c4d5e6f708192
                        relationshipTypes:
                          - parent_company
                        relationshipLabel: ''
                        ownershipPercent: 37.5
                        ownershipBasis: direct
                        ownershipSource: client_declared
                        verificationNote: ''
                        verifiedBy: ''
                        verifiedAt: null
                        thresholdAtCreation: 25
                        meetsThreshold: true
                        dedupDecision: linked_existing
                        dedupCandidateIds: null
                        source: api
                        status: active
                        addNote: ''
                        createdBy: application-id
                        createdAt: '2026-11-13T15:06:41.507Z'
                        updatedBy: application-id
                        updatedAt: '2026-11-13T15:06:41.507Z'
                        endedBy: ''
                        endedAt: null
                        endReason: ''
                        endNote: ''
                      party:
                        id: 6735a1c94f1e2b7a9c0d1e03
                        name: Ellison Maritime Holdings Ltd.
                        kind: organization
                        status: accepted
                        monitored: monitored
                        archived: false
                      screeningStatus: not_applicable
                      clientKey: party-2
                createdNotScreened:
                  summary: New party created, not screened
                  value:
                    msg: Created
                    status: 201
                    result:
                      outcome: created
                      relationship:
                        id: 6735a2d04f1e2b7a9c0d2f13
                        subjectProfileId: 6735a1c94f1e2b7a9c0d1e01
                        relatedProfileId: 6735a1c94f1e2b7a9c0d1e04
                        workspaceId: 6720f0aa3b9c4d5e6f708192
                        relationshipTypes:
                          - director_officer
                        relationshipLabel: ''
                        ownershipPercent: null
                        ownershipBasis: ''
                        ownershipSource: client_declared
                        verificationNote: ''
                        verifiedBy: ''
                        verifiedAt: null
                        thresholdAtCreation: 25
                        meetsThreshold: false
                        dedupDecision: new_profile
                        dedupCandidateIds: null
                        source: api
                        status: active
                        addNote: ''
                        createdBy: application-id
                        createdAt: '2026-11-13T15:08:12.880Z'
                        updatedBy: application-id
                        updatedAt: '2026-11-13T15:08:12.880Z'
                        endedBy: ''
                        endedAt: null
                        endReason: ''
                        endNote: ''
                      party:
                        id: 6735a1c94f1e2b7a9c0d1e04
                        name: Daniel Okafor
                        kind: individual
                        status: not_screened
                        monitored: not_monitored
                        archived: false
                      screeningStatus: screening_unavailable
                      clientKey: party-3
                  description: >-
                    Screening could not run. The party exists and is linked, but
                    it is not monitored until it is screened.
          description: Related party added.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/clm.ErrorResponse'
              examples:
                missingKey:
                  summary: Missing idempotency key
                  value:
                    msg: >-
                      profile_relationships.idempotency_key_required:
                      X-Idempotency-Key is required (at most 200 characters)
                    status: 400
                subjectNotOrganization:
                  summary: Subject is not an organization
                  value:
                    msg: >-
                      profile_relationships.subject_not_organization:
                      relationships can only be added to an organization profile
                    status: 400
                selfLink:
                  summary: Party is the same profile
                  value:
                    msg: >-
                      profile_relationships.self_link: a profile cannot be
                      related to itself
                    status: 400
                validation:
                  summary: Validation error
                  value:
                    msg: >-
                      ownershipBasis is required with ownershipPercent and must
                      be direct or indirect_declared
                    status: 400
          description: >-
            Invalid request. `profile_relationships.idempotency_key_required`:
            the header is missing or longer than 200 bytes.
            `profile_relationships.subject_not_organization`: relationships can
            only be added to organization profiles.
            `profile_relationships.self_link`: a profile cannot be related to
            itself. Other validation errors return a message, without a code,
            that describes the problem. A malformed `x-api-key` value, for
            example one that contains a space such as `Bearer <key>`, returns
            `400` with `msg` `Bad Request` and no code.
        '401':
          description: The `x-api-key` header is missing.
        '403':
          description: >-
            The API key is invalid or not allowed, or related parties are not
            enabled for your organization (`profile_relationships.not_enabled`).
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/clm.ErrorResponse'
              examples:
                externalIdNotFound:
                  summary: No profile with that externalId
                  value:
                    msg: >-
                      profile_relationships.not_found: no profile with that
                      externalId in this workspace
                    status: 404
          description: >-
            `profile_relationships.not_found`: the organization profile, or the
            party named by `profileId` or `externalId`, does not exist in your
            workspace. A `404` whose `msg` doesn't start with
            `profile_relationships.not_found` means the API key wasn't
            recognised.
        '409':
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: >-
                      #/components/schemas/clm.ProfileRelationshipNeedsReviewResponse
                  - $ref: >-
                      #/components/schemas/clm.ProfileRelationshipDuplicateActiveResponse
                  - $ref: '#/components/schemas/clm.ErrorResponse'
              examples:
                needsReview:
                  summary: Possible duplicate
                  value:
                    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
                duplicateActive:
                  summary: Already related
                  value:
                    msg: >-
                      profile_relationships.duplicate_active: an active
                      relationship between these profiles already exists
                    status: 409
                    result:
                      relationshipId: 6735a2d04f1e2b7a9c0d2f12
                subjectArchived:
                  summary: Organization archived
                  value:
                    msg: >-
                      profile_relationships.profile_archived: the subject
                      profile is archived
                    status: 409
                partyArchived:
                  summary: Party archived
                  value:
                    msg: >-
                      profile_relationships.profile_archived: the related
                      profile is archived
                    status: 409
          description: >-
            Conflict. `profile_relationships.needs_review`: possible duplicates;
            nothing was created. `profile_relationships.duplicate_active`: these
            two profiles already have an active relationship.
            `profile_relationships.profile_archived`: the organization or the
            party is archived. A `409` with an empty body means another request
            used the same `externalId` for a new profile at the same time. A
            `409` whose `msg` doesn't start with a code can mean a later retry
            with the same `X-Idempotency-Key` took over this request, or that
            the party could not be added. In each of these cases, list the
            relationships with `GET` before you send the request again.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/clm.ErrorResponse'
              examples:
                keyReused:
                  summary: Key reused
                  value:
                    msg: >-
                      profile_relationships.idempotency_key_reused: this
                      idempotency key was used for a different request
                    status: 422
          description: >-
            `profile_relationships.idempotency_key_reused`: this
            `X-Idempotency-Key` was already used for this organization with a
            different party, `relationshipTypes`, `ownershipPercent`,
            `ownershipBasis` or `onMatch`. Differences in other fields do not
            return `422` (see `X-Idempotency-Key`).
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/clm.ErrorResponse'
              examples:
                inFlight:
                  summary: Still in progress
                  value:
                    msg: >-
                      profile_relationships.in_flight: a request with this
                      idempotency key is still in progress
                    status: 429
          description: >-
            `profile_relationships.in_flight`: a request with this
            `X-Idempotency-Key` is still running. A `429` without a code means
            the new party could not be saved because another change was being
            saved at the same time. In both cases, wait for `Retry-After`
            seconds, then retry with the same key.
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
              example: 12
        '500':
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: >-
                      #/components/schemas/clm.ProfileRelationshipNeedsReconcileResponse
                  - $ref: '#/components/schemas/clm.ErrorResponse'
              examples:
                needsReconcile:
                  summary: Party profile may need checking
                  value:
                    msg: >-
                      profile_relationships.needs_reconcile: the party may have
                      been screened without being saved; check the profile
                      before adding the party again
                    status: 500
                    result:
                      outcome: needs_reconcile
                      partyProfileId: 6735a1c94f1e2b7a9c0d1e02
          description: >-
            `profile_relationships.needs_reconcile`: the relationship may not
            have been saved, and a profile may have been created and screened
            for the new party under `result.partyProfileId`. Sending the request
            again with the same key normally returns this error again. Do not
            send the party again yet. First list the relationships with `GET`.
            If the party is listed, the relationship was saved: linking it again
            returns `409` with `profile_relationships.duplicate_active` and the
            existing `relationshipId`. If it is not listed, check whether that
            profile exists, with `GET /profiles/{profileId}` or in the Minerva
            dashboard. If it exists, link it with `party.profileId` and a new
            `X-Idempotency-Key`. If it does not, contact 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. Other
            `500` responses are unexpected errors and can be retried with the
            same key.
        '503':
          description: >-
            A service needed to create the new party is temporarily unavailable.
            Nothing was created; retry with the same `X-Idempotency-Key`.
      security:
        - ApiKeyAuth: []
components:
  schemas:
    clm.ProfileRelationshipCreateRequest:
      description: Adds one related party to an organization profile.
      properties:
        addNote:
          description: Why the party was added, at most 2,000 characters.
          example: Declared on the client's beneficial ownership form dated 2026-11-12.
          maxLength: 2000
          type: string
        clientKey:
          description: >-
            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.
          example: party-1
          maxLength: 200
          type: string
        onMatch:
          description: >-
            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.
          enum:
            - create
          example: create
          type: string
        ownershipBasis:
          description: >-
            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).
          enum:
            - direct
            - indirect_declared
          example: direct
          type: string
        ownershipPercent:
          description: >-
            The declared ownership, from 0 to 100 with at most two decimal
            places. Requires `ownershipBasis`. Not accepted when the only
            relationship type is `subsidiary`.
          example: 62.5
          maximum: 100
          minimum: 0
          type: number
        party:
          $ref: '#/components/schemas/clm.ProfileRelationshipPartyRequest'
        relationshipLabel:
          description: >-
            What the relationship is, at most 200 characters. Required when
            `relationshipTypes` includes `other`, and rejected otherwise.
          example: Protector of the trust
          maxLength: 200
          type: string
        relationshipTypes:
          description: >-
            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`.
          example:
            - ubo
          items:
            enum:
              - ubo
              - shareholder
              - controlling_person
              - senior_managing_officer
              - director_officer
              - signing_authority
              - trustee
              - settlor
              - trust_beneficiary
              - parent_company
              - ultimate_parent
              - subsidiary
              - other
            type: string
          minItems: 1
          type: array
      required:
        - party
        - relationshipTypes
      type: object
    clm.CreateProfileRelationshipResponse:
      properties:
        msg:
          example: Created
          type: string
        result:
          properties:
            clientKey:
              description: >-
                The `clientKey` of the request that created this result, or an
                empty string. A repeat with the same `X-Idempotency-Key` returns
                the original `clientKey`.
              example: party-1
              type: string
            outcome:
              description: '`created` (a new profile was created) or `linked_existing`.'
              enum:
                - created
                - linked_existing
              example: created
              type: string
            party:
              $ref: '#/components/schemas/clm.ProfileRelationshipParty'
            relationship:
              $ref: '#/components/schemas/clm.ProfileRelationship'
            screeningStatus:
              description: >-
                `completed`: the new party was screened. `pending_credits`:
                created but not screened because your organization did not have
                enough Credits. `screening_unavailable`: created but not
                screened because screening could not run. `not_applicable`: an
                existing profile was linked, or screening is not configured for
                new profiles.
              enum:
                - completed
                - pending_credits
                - screening_unavailable
                - not_applicable
              example: completed
              type: string
          required:
            - outcome
            - relationship
            - party
            - screeningStatus
            - clientKey
          type: object
        status:
          example: 201
          type: integer
      type: object
    clm.ErrorResponse:
      description: Error response.
      properties:
        msg:
          description: >-
            What went wrong. For related-party errors it starts with a code, for
            example `profile_relationships.not_found: `. Base your error
            handling on the code, not on the sentence after it, which can
            change.
          example: >-
            profile_relationships.self_link: a profile cannot be related to
            itself
          type: string
        result:
          description: Extra detail for some errors.
          type: object
        status:
          description: The HTTP status.
          example: 400
          type: integer
      required:
        - msg
        - status
      type: object
    clm.ProfileRelationshipNeedsReviewResponse:
      description: >-
        Nothing was created. Resend the request with `party.profileId` set to a
        candidate, or with `onMatch: "create"`. You can reuse the same
        `X-Idempotency-Key`.
      properties:
        msg:
          example: >-
            profile_relationships.needs_review: the party may already have a
            profile in this workspace
          type: string
        result:
          properties:
            candidates:
              description: Up to 5 matching profiles.
              items:
                $ref: '#/components/schemas/clm.ProfileRelationshipCandidate'
              maxItems: 5
              type: array
            clientKey:
              example: party-1
              type: string
            outcome:
              enum:
                - needs_review
              example: needs_review
              type: string
            reason:
              description: >-
                `possible_duplicate`: a new party matched existing profiles by
                name and date of birth (individuals) or name and registration
                number (organizations). `external_id_exists`: the new party's
                `externalId` is already used. `external_id_ambiguous`: the
                `externalId` you linked matches more than one profile.
              enum:
                - possible_duplicate
                - external_id_exists
                - external_id_ambiguous
              example: possible_duplicate
              type: string
          required:
            - outcome
            - reason
            - candidates
            - clientKey
          type: object
        status:
          example: 409
          type: integer
      type: object
    clm.ProfileRelationshipDuplicateActiveResponse:
      properties:
        msg:
          example: >-
            profile_relationships.duplicate_active: an active relationship
            between these profiles already exists
          type: string
        result:
          properties:
            relationshipId:
              description: The existing active relationship, when it can be read.
              example: 6735a2d04f1e2b7a9c0d2f12
              type: string
          type: object
        status:
          example: 409
          type: integer
      type: object
    clm.ProfileRelationshipNeedsReconcileResponse:
      properties:
        msg:
          example: >-
            profile_relationships.needs_reconcile: the party may have been
            screened without being saved; check the profile before adding the
            party again
          type: string
        result:
          properties:
            outcome:
              enum:
                - needs_reconcile
              example: needs_reconcile
              type: string
            partyProfileId:
              description: >-
                The ID the new party's profile has if it was created. Check
                whether this profile exists before you send the party again.
              example: 6735a1c94f1e2b7a9c0d1e02
              type: string
          required:
            - outcome
            - partyProfileId
          type: object
        status:
          example: 500
          type: integer
      type: object
    clm.ProfileRelationshipPartyRequest:
      description: >-
        The related party. Send exactly one of `profileId`, `externalId` or
        `profile`.
      maxProperties: 1
      minProperties: 1
      properties:
        externalId:
          description: >-
            Link an existing profile in the same workspace by its `externalId`.
            If more than one profile has this `externalId`, the request is
            refused with `needs_review` (`external_id_ambiguous`).
          example: NHL-PARENT-01
          type: string
        profile:
          $ref: '#/components/schemas/clm.ProfileRelationshipNewParty'
        profileId:
          description: Link an existing profile in the same workspace by its Minerva ID.
          example: 6735a1c94f1e2b7a9c0d1e03
          type: string
      type: object
    clm.ProfileRelationshipParty:
      description: A summary of the related party's profile.
      properties:
        archived:
          example: false
          type: boolean
        id:
          description: The party's profile ID.
          example: 6735a1c94f1e2b7a9c0d1e02
          type: string
        kind:
          enum:
            - individual
            - organization
          example: individual
          type: string
        monitored:
          description: >-
            `monitored` or `not_monitored`. A party that could not be screened
            is `not_monitored` until it is screened.
          example: monitored
          type: string
        name:
          example: Margaret Ostrander
          type: string
        status:
          description: The profile's screening status.
          example: no_flags
          type: string
      type: object
      required:
        - archived
        - id
        - kind
        - monitored
        - name
        - status
    clm.ProfileRelationship:
      description: >-
        Beta: available on request. A relationship between an organization (the
        subject) and a related party. Relationships are never deleted: ending
        one keeps it as history.
      properties:
        addNote:
          description: The note sent when the party was added, or an empty string.
          example: Declared on the client's beneficial ownership form dated 2026-11-12.
          type: string
        createdAt:
          example: '2026-11-13T15:04:05.123Z'
          format: date-time
          type: string
        createdBy:
          description: The user or application that added the relationship.
          example: application-id
          type: string
        dedupCandidateIds:
          description: >-
            For `forced_create`, the possible duplicates that were found;
            otherwise `null`.
          example: null
          items:
            type: string
          type:
            - array
            - 'null'
        dedupDecision:
          description: >-
            How the party's profile was chosen: `new_profile` (a new profile was
            created), `linked_existing` (an existing profile was linked), or
            `forced_create` (a new profile was created with `onMatch: "create"`
            after possible duplicates were found).
          enum:
            - new_profile
            - linked_existing
            - forced_create
          example: new_profile
          type: string
        endNote:
          description: The end note, or an empty string.
          example: ''
          type: string
        endReason:
          description: Why it ended, or an empty string.
          enum:
            - no_longer_related
            - entered_in_error
            - duplicate_profile
            - other
            - ''
          example: ''
          type: string
        endedAt:
          description: When the relationship ended, or `null`.
          example: null
          format: date-time
          type:
            - string
            - 'null'
        endedBy:
          description: Who ended the relationship, or an empty string.
          example: ''
          type: string
        id:
          description: The relationship ID.
          example: 6735a2d04f1e2b7a9c0d2f11
          type: string
        meetsThreshold:
          description: >-
            Whether `ownershipPercent` is at or above `thresholdAtCreation` for
            a relationship type that carries ownership (`ubo`, `shareholder`,
            `parent_company`, `ultimate_parent`). Informational only.
          example: true
          type: boolean
        ownershipBasis:
          description: >-
            `direct` or `indirect_declared`, or an empty string when no
            ownership was recorded.
          enum:
            - direct
            - indirect_declared
            - ''
          example: direct
          type: string
        ownershipPercent:
          description: Declared ownership percentage, or `null`.
          example: 62.5
          type:
            - number
            - 'null'
        ownershipSource:
          description: '`client_declared` when added; `analyst_verified` after verification.'
          enum:
            - client_declared
            - analyst_verified
          example: client_declared
          type: string
        relatedProfileId:
          description: The related party's profile ID.
          example: 6735a1c94f1e2b7a9c0d1e02
          type: string
        relationshipLabel:
          description: The label for `other`, or an empty string.
          example: ''
          type: string
        relationshipTypes:
          description: What the related party is to the subject, sorted.
          example:
            - ubo
          items:
            enum:
              - ubo
              - shareholder
              - controlling_person
              - senior_managing_officer
              - director_officer
              - signing_authority
              - trustee
              - settlor
              - trust_beneficiary
              - parent_company
              - ultimate_parent
              - subsidiary
              - other
            type: string
          type: array
        source:
          description: >-
            Where the relationship was added. `api` for API keys; the Minerva
            dashboard records `kyb_onboarding` or `manual_link`.
          enum:
            - api
            - kyb_onboarding
            - manual_link
          example: api
          type: string
        status:
          description: '`active` or `ended`.'
          enum:
            - active
            - ended
          example: active
          type: string
        subjectProfileId:
          description: The organization the party is related to.
          example: 6735a1c94f1e2b7a9c0d1e01
          type: string
        thresholdAtCreation:
          description: >-
            The ownership threshold in force when the relationship was added
            (currently 25).
          example: 25
          type: number
        updatedAt:
          example: '2026-11-13T15:04:05.123Z'
          format: date-time
          type: string
        updatedBy:
          example: application-id
          type: string
        verificationNote:
          description: The verification note, or an empty string.
          example: ''
          type: string
        verifiedAt:
          description: When the ownership was verified, or `null`.
          example: null
          format: date-time
          type:
            - string
            - 'null'
        verifiedBy:
          description: Who verified the ownership, or an empty string.
          example: ''
          type: string
        workspaceId:
          description: The workspace the relationship belongs to.
          example: 6720f0aa3b9c4d5e6f708192
          type: string
      type: object
      required:
        - addNote
        - createdAt
        - createdBy
        - dedupCandidateIds
        - dedupDecision
        - endNote
        - endReason
        - endedAt
        - endedBy
        - id
        - meetsThreshold
        - ownershipBasis
        - ownershipPercent
        - ownershipSource
        - relatedProfileId
        - relationshipLabel
        - relationshipTypes
        - source
        - status
        - subjectProfileId
        - thresholdAtCreation
        - updatedAt
        - updatedBy
        - verificationNote
        - verifiedAt
        - verifiedBy
        - workspaceId
    clm.ProfileRelationshipCandidate:
      description: An existing profile in the workspace that may be the same party.
      properties:
        country:
          example: Canada
          type: string
        dateOfBirth:
          description: Individuals only.
          example: 1971/04/22
          type: string
        kind:
          example: individual
          type: string
        monitored:
          example: monitored
          type: string
        name:
          example: Margaret Ostrander
          type: string
        oldestOpenAlertAt:
          type:
            - string
            - 'null'
          format: date-time
          example: null
        profileId:
          example: 6735a1c94f1e2b7a9c0d1e05
          type: string
        registrationNumber:
          description: Organizations only.
          example: BC-0938112
          type: string
      type: object
    clm.ProfileRelationshipNewParty:
      description: >-
        A new profile to create for the related party. Minerva creates it,
        screens it and turns on monitoring. Fields not listed here, such as
        custom fields or profile groups, can be set afterwards with the profile
        update.
      properties:
        address1:
          description: Address line 1. For an individual, the residential address.
          example: 14 Lighthouse Lane
          type: string
        address2:
          description: Address line 2.
          example: Unit 3
          type: string
        addressCity:
          description: City.
          example: Halifax
          type: string
        addressPostalCode:
          description: Postal code.
          example: B3H 1Z9
          type: string
        addressState:
          description: Province or state.
          example: NS
          type: string
        country:
          description: Country.
          example: Canada
          type: string
        dateOfBirth:
          description: >-
            Date of birth (individuals) or incorporation date (organizations),
            as `YYYY-MM-DD`, `YYYY/MM/DD` or `YYYY`. For an individual it is
            also used to find possible duplicates.
          example: '1971-04-22'
          type: string
        email:
          description: Email address.
          example: m.ostrander@example.com
          type: string
        entityType:
          description: >-
            Organizations only. See the organization fields on the profile
            update.
          enum:
            - corporation
            - partnership
            - trust
            - non_profit
            - other
            - ''
          example: corporation
          type: string
        externalId:
          description: >-
            Your own reference for the new profile. If a profile with this
            `externalId` already exists in the workspace, the request is refused
            with `needs_review` (`external_id_exists`) so that you link that
            profile instead.
          example: NHL-UBO-001
          type: string
        firstName:
          description: >-
            First name. Combined with `middleName` and `lastName` when `name` is
            omitted.
          example: Margaret
          type: string
        incorporationCountry:
          description: Organizations only. ISO 3166-1 alpha-2 code.
          example: CA
          pattern: ^([A-Z]{2})?$
          type: string
        incorporationSubdivision:
          description: >-
            Organizations only. ISO 3166-2 code that belongs to
            `incorporationCountry`.
          example: CA-BC
          pattern: ^([A-Z]{2}-[A-Z0-9]{1,3})?$
          type: string
        kind:
          description: Required. `individual` or `organization`.
          enum:
            - individual
            - organization
          example: individual
          type: string
        lastName:
          description: Last name.
          example: Ostrander
          type: string
        middleName:
          description: Middle name.
          example: Anne
          type: string
        name:
          description: >-
            The full name. Required unless you send the name in parts
            (`firstName`, `middleName`, `lastName`).
          example: Margaret Ostrander
          type: string
        nationality:
          description: Nationality of an individual.
          example: Canada
          type: string
        phone:
          description: Phone number.
          example: +1 902 555 0147
          type: string
        registrationNumber:
          description: >-
            Organizations only. At most 200 characters. Used to find possible
            duplicates.
          example: BC-0938112
          maxLength: 200
          type: string
        sex:
          description: Sex of an individual.
          example: F
          type: string
        tradingNames:
          description: Organizations only. At most 20 names, each at most 200 characters.
          example:
            - Ellison Maritime
          items:
            type: string
            maxLength: 200
          type: array
      required:
        - kind
      type: object
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        The Minerva API key used for this integration. Manage API keys in the
        Minerva dashboard under Administration > Developers.

````

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