Clarifymedical Record Access API

openapi: 3.2.0
info:
  title: Clarify Record Access API
  description: The Clarify API OpenAPI documentation
  version: '0.1'
  contact: {}
servers:
- url: https://api.clarify.ai/v1
security:
- apiKey: []
- bearer: []
tags:
- name: RecordAccess
paths:
  /workspaces/{workspace}/objects/{object}/records/{id}/access:
    get:
      description: Returns every access grant on a single record — a record entity (`deal`, `company`, `person`, or a custom object) or a `list`, `meeting`, or `message` — as a JSON:API collection. A grant shares the record with a single workspace member or the whole workspace at a given access level. Visible to anyone who can already read the record. Requires a user-backed API key; workspace-actor API keys are not supported.
      operationId: getGrants
      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 shareable object the record belongs to: a record entity (`deal`, `company`, `person`, `task`, a custom object) or `list` / `meeting` / `message`.'
        schema:
          type: string
      - name: id
        required: true
        in: path
        description: The unique ID of the shared record.
        schema:
          type: string
      responses:
        '200':
          description: The record’s access grants.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectRecordAccessListResponse'
              example:
                data:
                - type: object-record-access
                  id: 2f4a6c8e-0b1d-4a3f-8c5e-7a9b1c3d5e6f
                  attributes:
                    _id: 2f4a6c8e-0b1d-4a3f-8c5e-7a9b1c3d5e6f
                    object_id: 9d2c4e6f-8a1b-4c3d-9e5f-7a9b1c3d5e7f
                    grantee_type: user
                    grantee_id: 7d4e2f9a-1b3c-4d5e-8f6a-9c0b2d4e6f81
                    access_level: view
                    source: share
                    _created_at: '2026-01-15T09:30:00.000Z'
                    _created_by: 7d4e2f9a-1b3c-4d5e-8f6a-9c0b2d4e6f81
                    _updated_at: null
                    _updated_by: null
                meta:
                  viewerAccess: []
      summary: List record access grants
      tags:
      - RecordAccess
    post:
      description: Shares a single record — a record entity (`deal`, `company`, `person`, or a custom object) or a `list`, `meeting`, or `message` — with a user or the whole workspace at a given access level. Only the record’s owner or a workspace permission admin (records and lists), the record’s owner (messages), a participant (meetings), or the assignee or creator (tasks) can create grants. Requires a user-backed API key; workspace-actor API keys are not supported.
      operationId: createGrant
      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 shareable object the record belongs to: a record entity (`deal`, `company`, `person`, `task`, a custom object) or `list` / `meeting` / `message`.'
        schema:
          type: string
      - name: id
        required: true
        in: path
        description: The unique ID of the shared record.
        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/CreateObjectRecordAccessRequestDto'
            examples:
              user:
                summary: Share with a user
                value:
                  data:
                    type: object-record-access
                    attributes:
                      grantee_type: user
                      grantee_id: 7d4e2f9a-1b3c-4d5e-8f6a-9c0b2d4e6f81
                      access_level: view
      responses:
        '201':
          description: The created grant.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectRecordAccessResponse'
              example:
                data:
                  type: object-record-access
                  id: 2f4a6c8e-0b1d-4a3f-8c5e-7a9b1c3d5e6f
                  attributes:
                    _id: 2f4a6c8e-0b1d-4a3f-8c5e-7a9b1c3d5e6f
                    object_id: 9d2c4e6f-8a1b-4c3d-9e5f-7a9b1c3d5e7f
                    grantee_type: user
                    grantee_id: 7d4e2f9a-1b3c-4d5e-8f6a-9c0b2d4e6f81
                    access_level: view
                    source: share
                    _created_at: '2026-01-15T09:30:00.000Z'
                    _created_by: 7d4e2f9a-1b3c-4d5e-8f6a-9c0b2d4e6f81
                    _updated_at: null
                    _updated_by: null
      summary: Create a record access grant
      tags:
      - RecordAccess
  /workspaces/{workspace}/objects/{object}/records/{id}/access/bulk:
    post:
      description: Shares a single record with multiple users and/or the whole workspace in one request, up to 1000 grants per call. Only the record’s owner or a workspace permission admin (records and lists), the record’s owner (messages), a participant (meetings), or the assignee or creator (tasks) can create grants. Requires a user-backed API key; workspace-actor API keys are not supported.
      operationId: createGrantsBulk
      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 shareable object the record belongs to: a record entity (`deal`, `company`, `person`, `task`, a custom object) or `list` / `meeting` / `message`.'
        schema:
          type: string
      - name: id
        required: true
        in: path
        description: The unique ID of the shared record.
        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/CreateBulkObjectRecordAccessRequestDto'
            examples:
              bulk:
                summary: Share with a user and the workspace
                value:
                  data:
                  - type: object-record-access
                    attributes:
                      grantee_type: user
                      grantee_id: 7d4e2f9a-1b3c-4d5e-8f6a-9c0b2d4e6f81
                      access_level: view
                  - type: object-record-access
                    attributes:
                      grantee_type: workspace
                      grantee_id: null
                      access_level: edit
      responses:
        '201':
          description: The created grants.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectRecordAccessListResponse'
              example:
                data:
                - type: object-record-access
                  id: 2f4a6c8e-0b1d-4a3f-8c5e-7a9b1c3d5e6f
                  attributes:
                    _id: 2f4a6c8e-0b1d-4a3f-8c5e-7a9b1c3d5e6f
                    object_id: 9d2c4e6f-8a1b-4c3d-9e5f-7a9b1c3d5e7f
                    grantee_type: user
                    grantee_id: 7d4e2f9a-1b3c-4d5e-8f6a-9c0b2d4e6f81
                    access_level: view
                    source: share
                    _created_at: '2026-01-15T09:30:00.000Z'
                    _created_by: 7d4e2f9a-1b3c-4d5e-8f6a-9c0b2d4e6f81
                    _updated_at: null
                    _updated_by: null
                - type: object-record-access
                  id: 3a5b7d9f-1c2e-4b6a-8d0f-2e4c6a8b0d1f
                  attributes:
                    _id: 3a5b7d9f-1c2e-4b6a-8d0f-2e4c6a8b0d1f
                    object_id: 9d2c4e6f-8a1b-4c3d-9e5f-7a9b1c3d5e7f
                    grantee_type: workspace
                    grantee_id: null
                    access_level: edit
                    source: share
                    _created_at: '2026-01-15T09:30:00.000Z'
                    _created_by: 7d4e2f9a-1b3c-4d5e-8f6a-9c0b2d4e6f81
                    _updated_at: null
                    _updated_by: null
                meta:
                  viewerAccess: []
      summary: Create record access grants in bulk
      tags:
      - RecordAccess
  /workspaces/{workspace}/objects/{object}/records/{id}/access/{grantId}:
    patch:
      description: Changes the access level of an existing grant on a record. Only the record’s owner or a workspace permission admin (records and lists), the record’s owner (messages), a participant (meetings), or the assignee or creator (tasks) can manage grants. Requires a user-backed API key; workspace-actor API keys are not supported.
      operationId: updateGrant
      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 shareable object the record belongs to: a record entity (`deal`, `company`, `person`, `task`, a custom object) or `list` / `meeting` / `message`.'
        schema:
          type: string
      - name: id
        required: true
        in: path
        description: The unique ID of the shared record.
        schema:
          type: string
      - name: grantId
        required: true
        in: path
        description: The unique ID of the grant.
        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/UpdateObjectRecordAccessRequestDto'
            examples:
              update:
                summary: Upgrade to edit access
                value:
                  data:
                    type: object-record-access
                    attributes:
                      access_level: edit
      responses:
        '200':
          description: The updated grant.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectRecordAccessResponse'
              example:
                data:
                  type: object-record-access
                  id: 2f4a6c8e-0b1d-4a3f-8c5e-7a9b1c3d5e6f
                  attributes:
                    _id: 2f4a6c8e-0b1d-4a3f-8c5e-7a9b1c3d5e6f
                    object_id: 9d2c4e6f-8a1b-4c3d-9e5f-7a9b1c3d5e7f
                    grantee_type: user
                    grantee_id: 7d4e2f9a-1b3c-4d5e-8f6a-9c0b2d4e6f81
                    access_level: edit
                    source: share
                    _created_at: '2026-01-15T09:30:00.000Z'
                    _created_by: 7d4e2f9a-1b3c-4d5e-8f6a-9c0b2d4e6f81
                    _updated_at: null
                    _updated_by: null
      summary: Update a record access grant
      tags:
      - RecordAccess
    delete:
      description: Permanently removes an access grant from a record. Only the record’s owner or a workspace permission admin (records and lists), the record’s owner (messages), a participant (meetings), or the assignee or creator (tasks) can manage grants. Returns 202 Accepted with an empty body. Requires a user-backed API key; workspace-actor API keys are not supported.
      operationId: revokeGrant
      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 shareable object the record belongs to: a record entity (`deal`, `company`, `person`, `task`, a custom object) or `list` / `meeting` / `message`.'
        schema:
          type: string
      - name: id
        required: true
        in: path
        description: The unique ID of the shared record.
        schema:
          type: string
      - name: grantId
        required: true
        in: path
        description: The unique ID of the grant.
        schema:
          type: string
      - name: silent
        in: query
        required: false
        schema:
          type: boolean
        description: When true, suppresses in-app and Slack notifications for this mutation.
      responses:
        '202':
          description: The grant was revoked. The response body is empty.
          content:
            application/json:
              example: {}
      summary: Revoke a record access grant
      tags:
      - RecordAccess
components:
  schemas:
    ObjectRecordAccessResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            type:
              type: string
              enum:
              - object-record-access
              description: The resource type; matches the `object` path parameter.
            id:
              type: string
              description: The unique ID of the resource.
            attributes:
              type: object
              properties:
                _id:
                  type: string
                  description: The unique ID of the grant.
                object_id:
                  type: string
                  description: The unique ID of the shared record.
                grantee_type:
                  type: string
                  enum:
                  - user
                  - workspace
                  - group
                  - email
                  - public
                  description: 'Who the grant is for: `user` for a single workspace member, `workspace` for everyone in the workspace.'
                grantee_id:
                  type: string
                  nullable: true
                  description: The unique ID of the grantee. Set to the user’s ID for `user` grants; `null` for `workspace` grants.
                access_level:
                  type: string
                  enum:
                  - view
                  - edit
                  - manage
                  - owner
                  description: 'The level of access the grant confers: `view` read-only, `edit` read-write. `owner` marks the record’s owner — returned read-only to identify the owner; it cannot be granted, changed, or revoked through this API (use the reassign-owner endpoint).'
                source:
                  type: string
                  enum:
                  - share
                  - field
                  - delegated_send
                  description: 'Why the grant exists: `share` for a direct grant, `field` for a grant from a user field on the record, such as a deal’s owner, `delegated_send` for an email a delegate sent from the owner’s account, or a reply in a thread they started. Field grants follow the field and delegated-send grants follow the delegation; neither can be changed or revoked through this API. A user can hold a direct grant beside either one on the same record.'
                _created_at:
                  type: string
                  format: date-time
                  description: When the grant was created.
                _created_by:
                  type: string
                  nullable: true
                  description: The unique ID of the user who created the grant.
                _updated_at:
                  type: string
                  format: date-time
                  nullable: true
                  description: When the grant was last updated.
                _updated_by:
                  type: string
                  nullable: true
                  description: The unique ID of the user who last updated the grant.
              required:
              - _id
              - object_id
              - grantee_type
              - grantee_id
              - access_level
              - source
              - _created_at
              - _created_by
              - _updated_at
              - _updated_by
              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 resource.
      required:
      - data
    CreateObjectRecordAccessRequestDto:
      type: object
      properties:
        data:
          type: object
          properties:
            type:
              type: string
              enum:
              - object-record-access
            attributes:
              discriminator:
                propertyName: grantee_type
              oneOf:
              - type: object
                properties:
                  grantee_type:
                    type: string
                    enum:
                    - user
                    description: Share the record with a single workspace member.
                  grantee_id:
                    type: string
                    description: The unique ID of the user to share the record with.
                  access_level:
                    type: string
                    enum:
                    - view
                    - edit
                    description: 'The level of access to grant: `view` for read-only access, `edit` for read-write access.'
                  notify:
                    type: boolean
                    description: Whether to notify the grantee that the record was shared with them. Defaults to `true`. Ignored for `workspace` grants, which never notify.
                required:
                - grantee_type
                - grantee_id
                - access_level
              - type: object
                properties:
                  grantee_type:
                    type: string
                    enum:
                    - workspace
                    description: Share the record with everyone in the workspace.
                  grantee_id:
                    type: 'null'
                    description: Must be `null` for a workspace-wide grant.
                  access_level:
                    type: string
                    enum:
                    - view
                    - edit
                    description: 'The level of access to grant: `view` for read-only access, `edit` for read-write access.'
                  notify:
                    type: boolean
                    description: Whether to notify the grantee that the record was shared with them. Defaults to `true`. Ignored for `workspace` grants, which never notify.
                required:
                - grantee_type
                - grantee_id
                - access_level
          required:
          - type
          - attributes
          additionalProperties: false
      required:
      - data
    UpdateObjectRecordAccessRequestDto:
      type: object
      properties:
        data:
          type: object
          properties:
            type:
              type: string
              enum:
              - object-record-access
            attributes:
              description: Field values keyed by field name; available fields depend on the object’s schema. System fields (prefixed with a single `_`) cannot be set.
              type: object
              properties:
                access_level:
                  type: string
                  enum:
                  - view
                  - edit
                  description: 'The new access level for the grant: `view` for read-only access, `edit` for read-write access.'
              required:
              - access_level
              additionalProperties: true
          required:
          - type
          - attributes
          additionalProperties: false
          description: The resource to create.
      required:
      - data
    CreateBulkObjectRecordAccessRequestDto:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                enum:
                - object-record-access
              attributes:
                discriminator:
                  propertyName: grantee_type
                oneOf:
                - type: object
                  properties:
                    grantee_type:
                      type: string
                      enum:
                      - user
                      description: Share the record with a single workspace member.
                    grantee_id:
                      type: string
                      description: The unique ID of the user to share the record with.
                    access_level:
                      type: string
                      enum:
                      - view
                      - edit
                      description: 'The level of access to grant: `view` for read-only access, `edit` for read-write access.'
                    notify:
                      type: boolean
                      description: Whether to notify the grantee that the record was shared with them. Defaults to `true`. Ignored for `workspace` grants, which never notify.
                  required:
                  - grantee_type
                  - grantee_id
                  - access_level
                - type: object
                  properties:
                    grantee_type:
                      type: string
                      enum:
                      - workspace
                      description: Share the record with everyone in the workspace.
                    grantee_id:
                      type: 'null'
                      description: Must be `null` for a workspace-wide grant.
                    access_level:
                      type: string
                      enum:
                      - view
                      - edit
                      description: 'The level of access to grant: `view` for read-only access, `edit` for read-write access.'
                    notify:
                      type: boolean
                      description: Whether to notify the grantee that the record was shared with them. Defaults to `true`. Ignored for `workspace` grants, which never notify.
                  required:
                  - grantee_type
                  - grantee_id
                  - access_level
            required:
            - type
            - attributes
            additionalProperties: false
          minItems: 1
          maxItems: 1000
      required:
      - data
    ObjectRecordAccessListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                enum:
                - object-record-access
              id:
                type: string
              attributes:
                type: object
                properties:
                  _id:
                    type: string
                    description: The unique ID of the grant.
                  object_id:
                    type: string
                    description: The unique ID of the shared record.
                  grantee_type:
                    type: string
                    enum:
                    - user
                    - workspace
                    - group
                    - email
                    - public
                    description: 'Who the grant is for: `user` for a single workspace member, `workspace` for everyone in the workspace.'
                  grantee_id:
                    type: string
                    nullable: true
                    description: The unique ID of the grantee. Set to the user’s ID for `user` grants; `null` for `workspace` grants.
                  access_level:
                    type: string
                    enum:
                    - view
                    - edit
                    - manage
                    - owner
                    description: 'The level of access the grant confers: `view` read-only, `edit` read-write. `owner` marks the record’s owner — returned read-only to identify the owner; it cannot be granted, changed, or revoked through this API (use the reassign-owner endpoint).'
                  source:
                    type: string
                    enum:
                    - share
                    - field
                    - delegated_send
                    description: 'Why the grant exists: `share` for a direct grant, `field` for a grant from a user field on the record, such as a deal’s owner, `delegated_send` for an email a delegate sent from the owner’s account, or a reply in a thread they started. Field grants follow the field and delegated-send grants follow the delegation; neither can be changed or revoked through this API. A user can hold a direct grant beside either one on the same record.'
                  _created_at:
                    type: string
                    format: date-time
                    description: When the grant was created.
                  _created_by:
                    type: string
                    nullable: true
                    description: The unique ID of the user who created the grant.
                  _updated_at:
                    type: string
                    format: date-time
                    nullable: true
                    description: When the grant was last updated.
                  _updated_by:
                    type: string
                    nullable: true
                    description: The unique ID of the user who last updated the grant.
                required:
                - _id
                - object_id
                - grantee_type
                - grantee_id
                - access_level
                - source
                - _created_at
                - _created_by
                - _updated_at
                - _updated_by
            required:
            - type
            - id
            - attributes
        meta:
          type: object
          properties:
            viewerAccess:
              type: array
              items:
                type: object
                properties:
                  kind:
                    type: string
                    enum:
                    - public-link
                    - workspace-public
                    - legacy-delegate
                    - entity-wide-delegate
                    description: How the viewer reaches the record. `workspace-public` is deprecated and never returned.
                  grantee_id:
                    type: string
                    nullable: true
                  access_level:
                    type: string
                    enum:
                    - view
                    - edit
                    - manage
                    - owner
                    nullable: true
                  owners:
                    type: array
                    items:
                      type: object
                      properties:
                        owner_id:
                          type: string
                        access_level:
                          type: string
                          enum:
                          - view
                          - edit
                          - manage
                          - owner
                          nullable: true
                      required:
                      - owner_id
                      - access_level
                    description: The record owners whose delegation grants this viewer access, each with the access level that owner granted. Empty for paths with no delegating owner, such as public-link sharing.
                required:
                - kind
                - grantee_id
                - access_level
                - owners
          required:
          - viewerAccess
      required:
      - data
      - meta
  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. Every endpoint accepts it, and endpoints that act as a person accept only it. Send a WorkOS access token in the Authorization header as: `Bearer <token>`.'