Clarifymedical Record Attachments API

openapi: 3.2.0
info:
  title: Clarify Record Attachments API
  description: The Clarify API OpenAPI documentation
  version: '0.1'
  contact: {}
servers:
- url: https://api.clarify.ai/v1
security:
- apiKey: []
- bearer: []
tags:
- name: RecordAttachments
paths:
  /workspaces/{workspace}/objects/{object}/records/{id}/attachments:
    get:
      description: Returns the attachments on a record, both user uploads and files extracted from emails. Omit `page` to return all attachments.
      operationId: listRecordAttachments
      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: page
        required: false
        in: query
        description: Offset pagination, e.g. `page[offset]=0&page[limit]=100`. Omit to return all attachments.
        schema:
          properties:
            offset:
              default: 0
              type: number
              minimum: 0
              description: The number of attachments to skip before the first result.
              required: false
            limit:
              type: number
              minimum: 1
              description: The maximum number of attachments to return per page.
              required: true
          type: object
      responses:
        '200':
          description: The record’s attachments.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetRecordAttachmentsListResponse'
              example:
                links:
                  next: null
                  prev: null
                meta:
                  total_records: 1
                  total_pages: 1
                data:
                - _id: 3b9f5c7d-6e2a-4f8b-9d1c-0a7e5b3f9d24
                  name: proposal.pdf
                  _created_at: '2026-01-15T09:30:00.000Z'
                  _created_by: null
                  source: user
                  mime_type: application/pdf
                  size_bytes: 482133
      summary: List record attachments
      tags:
      - RecordAttachments
    post:
      description: Links a previously uploaded file (see the upload-URL endpoint) to the record and returns the updated record.
      operationId: addRecordAttachment
      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: 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/AddFileToRecordDto'
            examples:
              attach:
                summary: Attach an uploaded PDF
                value:
                  name: proposal.pdf
                  key: attachments/acme/person/3b9f5c7d-6e2a-4f8b-9d1c-0a7e5b3f9d24/proposal.pdf
                  attachmentId: 3b9f5c7d-6e2a-4f8b-9d1c-0a7e5b3f9d24
      responses:
        '201':
          description: The record with the new attachment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordResponse'
              example:
                data:
                  type: person
                  id: 5f8b7d2e-9c4a-4e1b-8f3d-2a6c9e0b4d71
                  attributes:
                    _id: 5f8b7d2e-9c4a-4e1b-8f3d-2a6c9e0b4d71
                    name:
                      first_name: Jane
                      last_name: Doe
                    email_addresses:
                      items:
                      - jane@acme.com
                    job_title: VP of Marketing
                    company_id: c0a80121-7ac0-4b1c-8b6d-3e5f9a2d4c88
                    _created_at: '2026-01-15T09:30:00.000Z'
                    _updated_at: '2026-02-01T17:45:00.000Z'
      summary: Attach an uploaded file to a record
      tags:
      - RecordAttachments
    put:
      description: Returns a pre-signed URL for uploading a file. Upload the file contents to `signedUrl` via HTTP PUT, then attach it to the record by POSTing the returned `key` and `attachmentId` to the attachments endpoint.
      operationId: getSignedUrlForRecordAttachmentUpload
      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: 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/CreateRecordFileDto'
            examples:
              upload:
                summary: Request an upload URL for a PDF
                value:
                  name: proposal.pdf
      responses:
        '200':
          description: The pre-signed upload URL and the keys to attach the file.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSignedUrlForRecordAttachmentUploadResponse'
              example:
                data:
                  signedUrl: https://storage.clarify.ai/attachments/acme/person/3b9f5c7d-6e2a-4f8b-9d1c-0a7e5b3f9d24/proposal.pdf?signature=...
                  key: attachments/acme/person/3b9f5c7d-6e2a-4f8b-9d1c-0a7e5b3f9d24/proposal.pdf
                  attachmentId: 3b9f5c7d-6e2a-4f8b-9d1c-0a7e5b3f9d24
                  entity: person
                  _id: 5f8b7d2e-9c4a-4e1b-8f3d-2a6c9e0b4d71
      summary: Request an attachment upload URL
      tags:
      - RecordAttachments
  /workspaces/{workspace}/objects/{object}/records/{id}/attachments/{attachmentId}:
    get:
      description: Returns a short-lived signed URL for downloading the attachment contents.
      operationId: getRecordAttachment
      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: attachmentId
        required: true
        in: path
        description: The unique ID of the attachment.
        schema:
          type: string
      responses:
        '200':
          description: The signed download URL.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetRecordAttachmentResponse'
              example:
                data:
                  url: https://storage.clarify.ai/attachments/acme/person/3b9f5c7d-6e2a-4f8b-9d1c-0a7e5b3f9d24/proposal.pdf?signature=...
      summary: Get an attachment download URL
      tags:
      - RecordAttachments
    delete:
      description: Removes an attachment from the record and returns the updated record. This cannot be undone.
      operationId: deleteRecordAttachment
      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: attachmentId
        required: true
        in: path
        description: The unique ID of the attachment.
        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:
        '200':
          description: The record without the deleted attachment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordResponse'
              example:
                data:
                  type: person
                  id: 5f8b7d2e-9c4a-4e1b-8f3d-2a6c9e0b4d71
                  attributes:
                    _id: 5f8b7d2e-9c4a-4e1b-8f3d-2a6c9e0b4d71
                    name:
                      first_name: Jane
                      last_name: Doe
                    email_addresses:
                      items:
                      - jane@acme.com
                    job_title: VP of Marketing
                    company_id: c0a80121-7ac0-4b1c-8b6d-3e5f9a2d4c88
                    _created_at: '2026-01-15T09:30:00.000Z'
                    _updated_at: '2026-02-01T17:45:00.000Z'
      summary: Delete a record attachment
      tags:
      - RecordAttachments
components:
  schemas:
    AddFileToRecordDto:
      type: object
      properties:
        name:
          type: string
          description: The file name, including its extension.
        key:
          type: string
          description: The storage key returned by the signed-upload-URL request.
        attachmentId:
          type: string
          description: The attachment ID returned by the signed-upload-URL request.
      required:
      - name
      - key
      - attachmentId
    CreateRecordFileDto:
      type: object
      properties:
        name:
          type: string
          description: The file name, including its extension.
      required:
      - name
    GetRecordAttachmentsListResponse:
      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 attachments 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:
              _id:
                type: string
                description: The unique ID of the attachment.
              name:
                type: string
                description: The file name, including its extension.
              _created_at:
                type: string
                description: ISO 8601 timestamp of when the attachment was added.
              _created_by:
                type: string
                nullable: true
                description: The ID of the user who added the attachment, if known.
              source:
                type: string
                enum:
                - user
                - email
                description: 'How the attachment reached the record: uploaded by a user or extracted from an email.'
              mime_type:
                type: string
                nullable: true
                description: The MIME type of the file.
              size_bytes:
                type: integer
                nullable: true
                description: The file size in bytes, if known.
              messageRef:
                type: object
                properties:
                  _id:
                    type: string
                    description: The unique ID of the source email message.
                  _created_at:
                    type: string
                    description: ISO 8601 timestamp of the source email message.
                  received_at:
                    type: string
                    nullable: true
                    description: ISO 8601 timestamp when the source email was received (the true email date). Null if unknown.
                  account_email:
                    type: string
                    nullable: true
                    description: Email address of the connected account that ingested the source email. Null for messages ingested before provenance tracking.
                required:
                - _id
                - _created_at
                - received_at
                - account_email
                description: Reference to the email message the attachment came from; present for `email`-sourced attachments.
              sender:
                type: object
                properties:
                  personId:
                    type: string
                    nullable: true
                    description: The person record ID of the sender, if matched.
                  name:
                    type: string
                    nullable: true
                    description: The display name of the sender.
                required:
                - personId
                - name
                description: The sender of the source email; present for `email`-sourced attachments.
            required:
            - _id
            - name
            - _created_at
            - _created_by
            - source
            - mime_type
            - size_bytes
          description: The page of attachments.
      required:
      - links
      - meta
      - data
    RecordResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            type:
              type: string
              enum:
              - record
              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`.
            meta:
              type: object
              properties:
                effective_access_level:
                  type: string
                  enum:
                  - owner
                  - edit
                  - view
                  - none
                  description: The requesting user's effective access to this record (`owner`, `edit`, `view`, or `none`).
              description: Per-request metadata about the resource.
          required:
          - type
          - id
          - attributes
          description: The resource.
      required:
      - data
    GetSignedUrlForRecordAttachmentUploadResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            signedUrl:
              type: string
              description: Pre-signed URL to upload the file contents to via HTTP PUT.
            key:
              type: string
              description: The storage key to pass back when attaching the file.
            attachmentId:
              type: string
              description: The attachment ID to pass back when attaching the file.
            entity:
              type: string
              description: The object type of the target record.
            _id:
              type: string
              description: The unique ID of the target record.
          required:
          - signedUrl
          - key
          - attachmentId
          - entity
          - _id
          description: The signed upload URL and identifiers to attach the file.
      required:
      - data
    GetRecordAttachmentResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            url:
              type: string
              description: Short-lived signed URL to download the attachment contents.
          required:
          - url
          description: The download URL for the attachment.
      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. 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>`.'