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

# Verify a relationship's ownership

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

Records that the declared ownership was confirmed: `ownershipSource` becomes `analyst_verified`, with who and when. Verifying a relationship that is already verified returns it unchanged. Ended relationships cannot be verified.



## OpenAPI

````yaml /api-reference/profiles.json post /profiles/{profileId}/relationships/{relationshipId}/verify
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/{relationshipId}/verify:
    post:
      tags:
        - Profile Management
      summary: Verify a relationship's ownership
      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`.


        Records that the declared ownership was confirmed: `ownershipSource`
        becomes `analyst_verified`, with who and when. Verifying a relationship
        that is already verified returns it unchanged. Ended relationships
        cannot be verified.
      parameters:
        - description: Profile ID. Either end of the relationship can be used.
          example: 6735a1c94f1e2b7a9c0d1e01
          in: path
          name: profileId
          required: true
          schema:
            type: string
        - description: Relationship ID.
          example: 6735a2d04f1e2b7a9c0d2f11
          in: path
          name: relationshipId
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/clm.ProfileRelationshipVerifyRequest'
            examples:
              withNote:
                summary: Verify with a note
                value:
                  verificationNote: Confirmed against the shareholder register dated 2026-10-31.
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/clm.ProfileRelationshipResponse'
              examples:
                verified:
                  summary: Verified
                  value:
                    msg: OK
                    status: 200
                    result:
                      relationship:
                        id: 6735a2d04f1e2b7a9c0d2f11
                        subjectProfileId: 6735a1c94f1e2b7a9c0d1e01
                        relatedProfileId: 6735a1c94f1e2b7a9c0d1e02
                        workspaceId: 6720f0aa3b9c4d5e6f708192
                        relationshipTypes:
                          - ubo
                        relationshipLabel: ''
                        ownershipPercent: 62.5
                        ownershipBasis: direct
                        ownershipSource: analyst_verified
                        verificationNote: >-
                          Confirmed against the shareholder register dated
                          2026-10-31.
                        verifiedBy: application-id
                        verifiedAt: '2026-11-14T09:30:00.000Z'
                        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-14T09:30:00.000Z'
                        endedBy: ''
                        endedAt: null
                        endReason: ''
                        endNote: ''
          description: The verified relationship.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/clm.ErrorResponse'
              examples:
                tooLong:
                  summary: Note too long
                  value:
                    msg: verificationNote is too long
                    status: 400
          description: >-
            Invalid request, for example `verificationNote` is longer than 2,000
            characters. 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 or relationship does
            not exist in your workspace, or the relationship does not involve
            this profile. A `404` whose `msg` doesn't start with
            `profile_relationships.not_found` means the API key wasn't
            recognised.
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/clm.ErrorResponse'
              examples:
                ended:
                  summary: Relationship ended
                  value:
                    msg: >-
                      profile_relationships.relationship_ended: an ended
                      relationship cannot be verified
                    status: 409
          description: >-
            `profile_relationships.relationship_ended`: the relationship has
            ended.
        '500':
          description: Unexpected error. Safe to retry.
      security:
        - ApiKeyAuth: []
components:
  schemas:
    clm.ProfileRelationshipVerifyRequest:
      description: The request body is optional.
      properties:
        verificationNote:
          description: How the declared ownership was confirmed, at most 2,000 characters.
          example: Confirmed against the shareholder register dated 2026-10-31.
          maxLength: 2000
          type: string
      type: object
    clm.ProfileRelationshipResponse:
      properties:
        msg:
          example: OK
          type: string
        result:
          properties:
            relationship:
              $ref: '#/components/schemas/clm.ProfileRelationship'
          required:
            - relationship
          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.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
  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.