# Docs

- [Introduction](/docs): Build on Clarify: the public REST API for your CRM data
- Getting Started
  - [AI Agents](/docs/getting-started/ai-agents): Give your coding agent the context to build on Clarify
  - [Key Concepts](/docs/getting-started/key-concepts): The core vocabulary of the Clarify API: workspaces, objects, records, schemas, relationships, and lists
  - [Authentication](/docs/getting-started/authentication): API keys for direct integrations and OAuth 2.0 for partners
- API Basics
  - [Filtering and Search](/docs/api-basics/filtering): Query, filter, and order records
  - [Pagination](/docs/api-basics/pagination): Paginate through large result sets
  - [Errors](/docs/api-basics/errors): Common errors and how to fix them
  - [Rate limits](/docs/api-basics/rate-limits): API request limits, rate-limit headers, and retry guidance
- Guides
  - [Build a Workflow](/docs/guides/build-a-workflow): Run JavaScript on CRM events with the Clarify SDK
  - [Import CRM Data](/docs/guides/import-crm-data): Suggested API call sequences for bringing CRM data into Clarify
  - [Bulk Operations](/docs/guides/bulk-operations): Best practices for importing and updating data at scale
  - [Sync from a Warehouse](/docs/guides/sync-from-warehouse): Keep Clarify in sync with your data warehouse using reverse ETL
  - [Dynamic Lists](/docs/guides/dynamic-lists): Build SQL-driven list views with custom columns and filters
  - [Rich Text Fields](/docs/guides/rich-text): Write formatted content to fields that use Clarify's BlockNote format
  - [Schemas and Relationships](/docs/guides/schemas-and-relationships): Behaviors and gotchas when managing fields, relationships, and custom objects
  - [Webhooks](/docs/guides/webhooks): Trigger automations from inbound HTTP requests and call out to your systems
- Resources
  - [OpenAPI Spec](/docs/resources/openapi-spec): Machine-readable API specification
  - [Support](/docs/resources/support): Get help with the Clarify API
  - [FAQ](/docs/resources/faq): Answers to common Clarify API questions
- API Reference
  - [Overview](/docs/api-reference): Every endpoint, generated from Clarify's OpenAPI contract
  - Activities
    - [List record activities](/docs/api-reference/activities/getActivities): Returns the activity feed for a record: a paginated, reverse-chronological list of change events (field updates, comments, relationship changes) grouped into activities. Each activity bundles one or more related events.
  - Comments
    - [Create a comment](/docs/api-reference/comments/createComment): Creates a comment on a record. The comment body is rich text, and `owner_id` plus `entity` identify the record it is attached to. Returns the created comment row.
    - [Delete a comment](/docs/api-reference/comments/deleteComment): Permanently deletes a comment. A comment can be deleted by its author, by an admin, or by the owner of the agent that posted it. Returns the deleted comment. This cannot be undone.
    - [Get a comment](/docs/api-reference/comments/getComment): Returns a single comment by its ID.
    - [Update a comment](/docs/api-reference/comments/updateComment): Replaces the body of an existing comment. Only the comment’s author may edit it. Returns the updated comment.
  - List Rows
    - [Export a list’s rows as CSV](/docs/api-reference/listrows/getListRowsCsv): Streams the rows of a list as a `text/csv` file download. The first row is a header of field names. Pass a `sql` statement in the body to export a custom query instead of the list’s own rows.
  - Lists
    - [Create a list](/docs/api-reference/lists/createList): Creates a list on the given object type. A `dynamic` list derives its membership from the SQL `query`; a `static` list starts empty. Returns the created list.
    - [Delete a list](/docs/api-reference/lists/deleteList): Permanently deletes a list. The object’s default list and the last remaining list on an object cannot be deleted. This cannot be undone.
    - [Get a list](/docs/api-reference/lists/getList): Returns a single list by ID as a JSON:API resource.
    - [List an object’s lists](/docs/api-reference/lists/getLists): Returns the lists defined on an object type as a paginated JSON:API collection. Dynamic lists are excluded unless you pass a matching `filter`.
    - [List a workspace’s lists](/docs/api-reference/lists/getWorkspaceLists): Returns every list across all object types in the workspace as a paginated JSON:API collection. Filter by object type with `filter[entity]`. Dynamic lists are excluded unless you pass a matching `filter`.
    - [Publish a list](/docs/api-reference/lists/publishList): Publishes a draft list, making it visible to its audience. Returns the updated list.
    - [Unpublish a list](/docs/api-reference/lists/unpublishList): Reverts a published list to draft state. Returns the updated list.
    - [Update a list](/docs/api-reference/lists/updateList): Applies a partial update to a list: only the fields present in the body are changed. The object’s default list cannot be updated. Returns the updated list.
  - Meeting Recordings
    - [Confirm a recording media upload](/docs/api-reference/meetingrecordings/confirmMediaUpload): Finalizes a media upload after the file has been submitted to the presigned policy: validates the stored object and marks the recording complete. Returns the finalized recording.
    - [Disable meeting recording](/docs/api-reference/meetingrecordings/disableRecording): Turns off recording for a meeting so no notetaker bot joins the call. Returns the updated meeting record.
    - [Enable meeting recording](/docs/api-reference/meetingrecordings/enableRecording): Turns on recording for a meeting so a notetaker bot joins the call. Returns the updated meeting record.
    - [Get recording artifacts](/docs/api-reference/meetingrecordings/getRecordingArtifacts): Returns short-lived signed URLs for a recording’s video and transcript files. Either URL is `null` when that artifact is not available.
    - [Start a recording media upload](/docs/api-reference/meetingrecordings/initMediaUpload): Creates a pending recording on the meeting and returns a presigned S3 POST policy for uploading an audio or video file directly to storage. Uploaded media is stored for playback and is not transcribed. Optionally include a transcript in the same request so one recording carries both video and transcript. Submit the file to the returned policy, then confirm the upload. Pass `recordingId` to overwrite a completed manual-upload recording instead of creating a new one.
    - [Upload a recording transcript](/docs/api-reference/meetingrecordings/uploadRecordingTranscript): Creates a recording on the meeting from an externally captured transcript, so meetings recorded outside Clarify can be summarized and searched, and triggers summary generation. A meeting with a recording already gets a second recording. Pass `recordingId` to overwrite a completed manual-upload recording’s transcript instead. Returns the recording.
    - [Upload a meeting transcript](/docs/api-reference/meetingrecordings/uploadTranscript): Creates a recording for a meeting from an externally captured transcript, so meetings recorded outside Clarify can be summarized and searched. Returns the created recording.
  - Record Attachments
    - [Attach an uploaded file to a record](/docs/api-reference/recordattachments/addRecordAttachment): Links a previously uploaded file (see the upload-URL endpoint) to the record and returns the updated record.
    - [Delete a record attachment](/docs/api-reference/recordattachments/deleteRecordAttachment): Removes an attachment from the record and returns the updated record. This cannot be undone.
    - [Get an attachment download URL](/docs/api-reference/recordattachments/getRecordAttachment): Returns a short-lived signed URL for downloading the attachment contents.
    - [Request an attachment upload URL](/docs/api-reference/recordattachments/getSignedUrlForRecordAttachmentUpload): 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.
    - [List record attachments](/docs/api-reference/recordattachments/listRecordAttachments): Returns the attachments on a record, both user uploads and files extracted from emails. Omit `page` to return all attachments.
  - Record Relationships
    - [Unlink related records](/docs/api-reference/recordrelationships/deleteRecordRelationship): Removes the links to the records in `data` from the given relationship. The records themselves are not deleted.
    - [List related records](/docs/api-reference/recordrelationships/getRecordRelationships): Returns the records linked to a record through the given relationship, e.g. the deals related to a person.
    - [Replace related records](/docs/api-reference/recordrelationships/updateRecordRelationship): Replaces the full set of records linked through the given relationship with the records in `data`. Links not listed are removed; this is not additive.
  - Records
    - [Create records in bulk](/docs/api-reference/records/createBulkRecords): Creates multiple records of the given object type in one request. The request is validated as a whole: if any record fails validation, none are created. Pass `match_on` with the name of a unique field to upsert matching records instead of creating duplicates.
    - [Create a record](/docs/api-reference/records/createRecord): Creates a record of the given object type. Pass `match_on` with the name of a unique field to upsert: when an incoming value matches exactly one existing record, that record is updated instead of a new one being created.
    - [Delete a record](/docs/api-reference/records/deleteRecord): Permanently deletes a record. This cannot be undone.
    - [Delete records in bulk](/docs/api-reference/records/deleteRecords): Permanently deletes the records listed in `items`. This cannot be undone.
    - [Get a record](/docs/api-reference/records/getRecord): Returns a single record as a JSON:API resource. Use `include` to embed related records under `relationships`.
    - [Merge records](/docs/api-reference/records/mergeRecords): Merges the source records listed in `sources` into the target record. Field values and relationships are combined onto the target, and the source records are deleted. This cannot be undone.
    - [Update a record](/docs/api-reference/records/updateRecord): Applies a partial update to a record: only the fields present in `attributes` are changed, all other fields keep their current values.
    - [Update records in bulk](/docs/api-reference/records/updateRecords): Applies partial updates to multiple records in one request. Each entry names the record by `id` and lists only the fields to change.
  - Resources
    - [Create a resource](/docs/api-reference/resources/createResource): Creates a resource of the given object type. The `type` in the body must match the `object` path parameter. Returns the created resource as a JSON:API document.
    - [List resources in a list](/docs/api-reference/resources/getListResources): Returns a paginated JSON:API collection of the resources that belong to a specific list, applying the list’s membership on top of any `filter` you pass. Use `include` to embed related resources.
    - [Get a resource](/docs/api-reference/resources/getResource): Returns a single resource as a JSON:API document. Use `include` to embed related resources under `relationships` and return them in `included`.
    - [List resources](/docs/api-reference/resources/getResources): Returns a paginated JSON:API collection of an object’s resources. Use `include` to embed related resources and `filter` to narrow results by field — shorthand operators are parsed from the value (`filter[status]=active,pending`, `filter[amount]=>100`, `filter[name]=*Smith*`, `filter[assigned]=null`), or name them explicitly (`filter[start][Is on or after]=2025-01-01`). To filter on a relationship field, include that relationship: `filter[author.name]=John&include=author`.
  - Schemas
    - [Create a custom object](/docs/api-reference/schemas/createCustomObject): Creates a new custom object type in the workspace and returns its generated JSON Schema. The name is normalized to a `c_`-prefixed identifier (for example "Sales Order" becomes `c_sales_order`).
    - [Add object fields](/docs/api-reference/schemas/createSchemaProperties): Adds one or more non-relationship fields to an object type. Each key in `attributes` is a new field name mapped to its JSON Schema. Fields that already exist are rejected — this endpoint never overwrites. The change is applied asynchronously and the response body is empty.
    - [Add object relationships](/docs/api-reference/schemas/createSchemaRelationshipProperties): Creates relationship fields between object types. The `attributes` map is keyed first by object type, then by field name, and both sides of each relationship must be supplied together so the pairing is consistent. On `one-to-many` and `many-to-many` sides, the field must declare `"oneOf": [{ "$ref": "https://getclarify.ai/schemas/core/collectionOfIds" }, { "type": "null" }]` — the exact `$ref` string is required. The change is applied asynchronously and the response body is empty.
    - [Delete a custom object](/docs/api-reference/schemas/deleteCustomObject): Deletes a custom object type and all of its records. The deletion runs asynchronously: the response returns a task you can poll to track progress. Only custom (`c_*`) objects can be deleted. This cannot be undone.
    - [Delete an object relationship](/docs/api-reference/schemas/deleteSchemaRelationshipProperty): Deletes a relationship field from an object type, along with its counterpart field on the related object. The deletion runs asynchronously: the response returns a task you can poll to track progress. Deleting an already-removed relationship is a no-op that still returns a task.
    - [List schema activities](/docs/api-reference/schemas/getSchemaActivities): Returns the history of schema changes for an object type as a paginated list of activities. Each activity groups the change events for one modification, such as adding or editing a field.
    - [List object schemas](/docs/api-reference/schemas/getSchemas): Returns every object schema in the workspace as a cursor-paginated list of JSON:API resources. Each resource holds the full JSON Schema for one object type, including its fields, relationships, and presentation metadata.
    - [Add or remove enum field values](/docs/api-reference/schemas/patchEnumFieldValues): Adds or removes options on enum (single- and multi-select) fields for one object type. The request carries exactly one item in `data`; each field in `meta` names an `append` or `remove` operation. To modify several object types, send separate requests.
    - [Replace an object schema](/docs/api-reference/schemas/updateEntitySchema): Replaces the full JSON Schema for an object type. The request body is the complete schema document, and its `$id` must match the object in the path. The change is applied asynchronously: the response returns a task you can poll to track progress.
    - [Reorder object fields](/docs/api-reference/schemas/updateSchemaPropertyOrder): Sets the display order of an object type’s fields. The `order` array lists every field name in the desired order. The change is applied asynchronously and the response body is empty.
    - [Set object field visibility](/docs/api-reference/schemas/updateSchemaPropertyVisibility): Shows or hides an object type’s fields on the record detail view. The `hiddenInDetails` map keys each field name to a boolean, where `true` hides the field. The change is applied asynchronously and the response body is empty.
  - Users
    - [Get a user](/docs/api-reference/users/getUser): Returns a single workspace user as a JSON:API resource, including their roles and the time they were last active.
    - [List users](/docs/api-reference/users/getUsers): Returns the workspace’s users as a paginated JSON:API list. Each user includes their roles.
  - Workflows
    - [Create a workflow](/docs/api-reference/workflows/createWorkflow): Creates a workflow from a trigger and a set of blocks. Create it disabled and enable it once the automation graph is complete. Returns the created workflow.
    - [Delete a workflow](/docs/api-reference/workflows/deleteWorkflow): Deletes a workflow. The deletion is applied asynchronously and the response body is empty. This cannot be undone.
    - [Get a workflow](/docs/api-reference/workflows/getWorkflow): Returns a single workflow as a JSON:API resource, including its trigger and the blocks that make up its automation graph.
    - [List workflows](/docs/api-reference/workflows/getWorkflows): Returns the workspace’s workflows as an offset-paginated list of JSON:API resources. Use the `type` filter to return only sequences (campaigns) or general workflows.
    - [Update a workflow](/docs/api-reference/workflows/updateWorkflow): Applies a partial update to a workflow: only the fields present in `attributes` are changed. Use it to rename, enable or disable, or edit the trigger and blocks. Returns the updated workflow.
  - Workspace Settings
    - [Reset a workspace setting](/docs/api-reference/workspacesettings/deleteWorkspaceSetting): Removes the stored value of a workspace setting so it falls back to its default. Read-only settings are rejected, and some settings require admin permissions.
    - [List workspace settings](/docs/api-reference/workspacesettings/readAllWorkspaceSettings): Returns every workspace setting keyed by name, with defaults applied for settings the workspace has not overridden.
    - [Get a workspace setting](/docs/api-reference/workspacesettings/readWorkspaceSettings): Returns the value of a single workspace setting; the default value when the workspace has not overridden it.
    - [Write a workspace setting](/docs/api-reference/workspacesettings/writeWorkspaceSetting): Sets the value of a workspace setting by key. Read-only settings are rejected, and some settings require admin permissions.