Clarify Record Relationships API

openapi: 3.2.0
info:
  title: Clarify Record Relationships API
  description: The Clarify API OpenAPI documentation
  version: '0.1'
  contact: {}
servers:
- url: https://api.clarify.ai/v1
security:
- apiKey: []
tags:
- name: RecordRelationships
paths:
  /workspaces/{workspace}/objects/{object}/records/{id}/relationships/{relationship}:
    get:
      description: Returns the records linked to a record through the given relationship, e.g. the deals related to a person.
      operationId: getRecordRelationships
      parameters:
      - name: workspace
        required: true
        in: path
        description: The workspace slug — the `{slug}` segment of your Clarify workspace URL.
        schema:
          type: string
      - name: object
        required: true
        in: path
        description: 'The object type: a built-in entity (`person`, `company`, `deal`, …) or a custom object (`c_*`).'
        schema:
          type: string
      - name: id
        required: true
        in: path
        description: The unique ID of the record.
        schema:
          type: string
      - name: relationship
        required: true
        in: path
        description: The relationship field name as defined in the object’s schema, e.g. `people` or `companies`.
        schema:
          type: string
      - name: page
        required: false
        in: query
        description: Offset pagination, e.g. `page[offset]=0&page[limit]=100`.
        schema:
          properties:
            offset:
              default: 0
              type: number
              minimum: 0
              description: The number of records to skip before the first result.
              required: false
            limit:
              default: 500
              type: number
              minimum: 1
              maximum: 500
              description: The maximum number of records to return per page (up to 500).
              required: false
          default:
            offset: 0
            limit: 500
          type: object
      - name: sortOrder
        required: false
        in: query
        description: Sort order, e.g. `sortOrder[column]=_created_at&sortOrder[dir]=DESC`.
        schema:
          properties:
            column:
              description: The field name to sort by.
              type: string
              minLength: 1
              required: true
            dir:
              type: string
              enum:
              - ASC
              - DESC
              description: The sort direction.
              required: true
          type: object
      - name: include
        required: false
        in: query
        description: Comma-separated list of nested relationship paths to resolve, relative to the parent record, e.g. `include=companies.deals`.
        schema:
          type: string
      responses:
        '200':
          description: The related records.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListOfRecordsResponse'
              example:
                links:
                  next: null
                  prev: null
                meta:
                  total_records: 1
                  total_pages: 1
                  offset: 0
                  limit: 500
                data:
                - type: deal
                  id: e7c9a1f4-2b8d-4c6e-9f0a-5d3b7e1c8a42
                  attributes:
                    _id: e7c9a1f4-2b8d-4c6e-9f0a-5d3b7e1c8a42
                    name: Acme Renewal Q1
                    stage: In progress
                    amount: 50000
                    close_date: '2026-03-31'
                    company_id: c0a80121-7ac0-4b1c-8b6d-3e5f9a2d4c88
                    _created_at: '2026-01-15T09:30:00.000Z'
                    _updated_at: '2026-02-01T17:45:00.000Z'
      summary: List related records
      tags:
      - RecordRelationships
    patch:
      description: 'Replaces the linked records for to-one and many-to-many relationships with the records in `data`: links not listed are removed. For one-to-many relationships the listed records are linked additively; pass `id: null` to unlink every related record first.'
      operationId: updateRecordRelationship
      parameters:
      - name: workspace
        required: true
        in: path
        description: The workspace slug — the `{slug}` segment of your Clarify workspace URL.
        schema:
          type: string
      - name: object
        required: true
        in: path
        description: 'The object type: a built-in entity (`person`, `company`, `deal`, …) or a custom object (`c_*`).'
        schema:
          type: string
      - name: id
        required: true
        in: path
        description: The unique ID of the record.
        schema:
          type: string
      - name: relationship
        required: true
        in: path
        description: The relationship field name as defined in the object’s schema, e.g. `people` or `companies`.
        schema:
          type: string
      - name: silent
        in: query
        required: false
        schema:
          type: boolean
        description: When true, suppresses in-app and Slack notifications for this mutation.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateRelationshipDto'
            examples:
              replace:
                summary: Set a person’s deals
                value:
                  data:
                  - type: deal
                    id: e7c9a1f4-2b8d-4c6e-9f0a-5d3b7e1c8a42
      responses:
        '200':
          description: The relationship was replaced. The response body is empty.
          content:
            application/json:
              example: {}
      summary: Replace related records
      tags:
      - RecordRelationships
    delete:
      description: Removes the links to the records in `data` from the given relationship. The records themselves are not deleted.
      operationId: deleteRecordRelationship
      parameters:
      - name: workspace
        required: true
        in: path
        description: The workspace slug — the `{slug}` segment of your Clarify workspace URL.
        schema:
          type: string
      - name: object
        required: true
        in: path
        description: 'The object type: a built-in entity (`person`, `company`, `deal`, …) or a custom object (`c_*`).'
        schema:
          type: string
      - name: id
        required: true
        in: path
        description: The unique ID of the record.
        schema:
          type: string
      - name: relationship
        required: true
        in: path
        description: The relationship field name as defined in the object’s schema, e.g. `people` or `companies`.
        schema:
          type: string
      - name: silent
        in: query
        required: false
        schema:
          type: boolean
        description: When true, suppresses in-app and Slack notifications for this mutation.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateRelationshipDto'
            examples:
              unlink:
                summary: Unlink a deal from a person
                value:
                  data:
                  - type: deal
                    id: e7c9a1f4-2b8d-4c6e-9f0a-5d3b7e1c8a42
      responses:
        '200':
          description: The links were removed. The response body is empty.
          content:
            application/json:
              example: {}
      summary: Unlink related records
      tags:
      - RecordRelationships
components:
  schemas:
    ListOfRecordsResponse:
      type: object
      properties:
        links:
          type: object
          properties:
            next:
              type: string
              nullable: true
              description: URL of the next page, or `null` on the last page.
            prev:
              type: string
              nullable: true
              description: URL of the previous page, or `null` on the first page.
          required:
          - next
          - prev
          description: Pagination links.
        meta:
          type: object
          properties:
            total_records:
              type: number
              description: Total number of records across all pages.
            total_pages:
              type: number
              description: Total number of pages at the current page size.
          required:
          - total_records
          - total_pages
          description: Pagination metadata.
        data:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                enum:
                - resource
                description: The resource type; matches the `object` path parameter.
              id:
                type: string
                description: The unique ID of the resource.
              attributes:
                type: object
                properties: {}
                description: Field values keyed by field name; available fields depend on the object’s schema.
              relationships:
                type: object
                properties: {}
                description: Related resources keyed by relationship name, present when requested via `include`.
            required:
            - type
            - id
            - attributes
          description: The page of resources.
      required:
      - links
      - meta
      - data
    UpdateRelationshipDto:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                description: The object type of the related record, e.g. `person`.
              id:
                type: string
                nullable: true
                description: The unique ID of the related record, or `null` to clear a to-one relationship.
            required:
            - type
            - id
          description: The related records to link.
      required:
      - data
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: Authorization
      description: 'API key authentication. Send your key in the Authorization header as: `api-key <your-api-key>`.'
    bearer:
      type: http
      scheme: bearer
      description: 'User access token authentication for endpoints that act across workspaces. Send a WorkOS access token in the Authorization header as: `Bearer <token>`.'