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

# List relationships

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

Lists a profile's relationships in both directions: its related parties (`direction: related_party`) and the organizations it is related to (`direction: subject`). Active relationships come first, then newest first. Ended relationships are included only with `include=ended`. At most 200 relationships are returned; `truncated` is `true` when there are more.



## OpenAPI

````yaml /api-reference/profiles.json get /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:
    get:
      tags:
        - Profile Management
      summary: List relationships
      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`.


        Lists a profile's relationships in both directions: its related parties
        (`direction: related_party`) and the organizations it is related to
        (`direction: subject`). Active relationships come first, then newest
        first. Ended relationships are included only with `include=ended`. At
        most 200 relationships are returned; `truncated` is `true` when there
        are more.
      parameters:
        - description: Profile ID. Either end of the relationship can be used.
          example: 6735a1c94f1e2b7a9c0d1e01
          in: path
          name: profileId
          required: true
          schema:
            type: string
        - description: Send `ended` to include ended relationships.
          in: query
          name: include
          required: false
          schema:
            enum:
              - ended
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/clm.ListProfileRelationshipsResponse'
              examples:
                organization:
                  summary: An organization with three related parties
                  value:
                    msg: OK
                    status: 200
                    result:
                      truncated: false
                      relationships:
                        - 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: ''
                          direction: related_party
                          counterparty:
                            id: 6735a1c94f1e2b7a9c0d1e04
                            name: Daniel Okafor
                            kind: individual
                            status: not_screened
                            monitored: not_monitored
                            archived: false
                            oldestOpenAlertAt: null
                            onboardingScreening:
                              status: skipped
                              outcome: screening_unavailable
                        - 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: ''
                          direction: related_party
                          counterparty:
                            id: 6735a1c94f1e2b7a9c0d1e03
                            name: Ellison Maritime Holdings Ltd.
                            kind: organization
                            status: accepted
                            monitored: monitored
                            archived: false
                            oldestOpenAlertAt: null
                        - 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: ''
                          direction: related_party
                          counterparty:
                            id: 6735a1c94f1e2b7a9c0d1e02
                            name: Margaret Ostrander
                            kind: individual
                            status: no_flags
                            monitored: monitored
                            archived: false
                            oldestOpenAlertAt: null
                            onboardingScreening:
                              status: completed
                              outcome: automatic_pass
          description: Relationships for the profile.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/clm.ErrorResponse'
              examples:
                invalidInclude:
                  summary: Invalid include
                  value:
                    msg: include must be "ended" when set
                    status: 400
          description: >-
            Invalid `include` value. 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':
          description: >-
            `profile_relationships.not_found`: the profile 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.
        '500':
          description: Unexpected error. Safe to retry.
      security:
        - ApiKeyAuth: []
components:
  schemas:
    clm.ListProfileRelationshipsResponse:
      properties:
        msg:
          example: OK
          type: string
        result:
          properties:
            relationships:
              items:
                $ref: '#/components/schemas/clm.ProfileRelationshipListItem'
              type: array
              description: Active relationships first, then newest first. At most 200.
            truncated:
              description: >-
                `true` when the profile has more than 200 relationships and only
                the first 200 are returned.
              example: false
              type: boolean
          required:
            - relationships
            - truncated
          type: object
        status:
          example: 200
          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.ProfileRelationshipListItem:
      allOf:
        - $ref: '#/components/schemas/clm.ProfileRelationship'
        - properties:
            counterparty:
              description: >-
                The profile on the other end of the relationship, or `null` if
                it can no longer be read.
              oneOf:
                - $ref: '#/components/schemas/clm.ProfileRelationshipCounterparty'
                - type: 'null'
            direction:
              description: >-
                How the counterparty relates to the profile in the path.
                `related_party`: the counterparty is a related party of this
                profile. `subject`: the counterparty is an organization that
                this profile is a related party of.
              enum:
                - related_party
                - subject
              example: related_party
              type: string
          required:
            - direction
            - counterparty
          type: object
    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.ProfileRelationshipCounterparty:
      allOf:
        - $ref: '#/components/schemas/clm.ProfileRelationshipParty'
        - properties:
            oldestOpenAlertAt:
              description: >-
                When the oldest open alert on this profile was raised, or `null`
                when it has none.
              example: null
              format: date-time
              type:
                - string
                - 'null'
            onboardingScreening:
              description: >-
                Present only for profiles created through onboarding, including
                new related parties.
              properties:
                outcome:
                  description: >-
                    Why screening was skipped (`pending_credits`,
                    `screening_unavailable`), or the screening outcome, for
                    example `automatic_pass` or `findings_require_review`.
                  example: screening_unavailable
                  type: string
                status:
                  description: >-
                    Onboarding screening status, for example `completed`, or
                    `skipped` when the profile was created without being
                    screened.
                  example: skipped
                  type: string
              type: object
          type: object
      description: The profile on the other end of the relationship.
    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
  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.