Key Concepts

Clarify's data model has a small, consistent vocabulary. Learn these terms once and they apply across every endpoint.

Workspace

A workspace is the top-level container for a customer's CRM: its objects, records, schema, lists, and members. Every request is scoped to one workspace by its slug, which appears in the base URL:

https://api.clarify.ai/v1/workspaces/{slug}/*

Your slug appears in your Clarify login URL and under the user avatar menu. API keys are issued per workspace, so a key only ever reads or writes data in the workspace it belongs to.

Objects

Objects are the entity types in a workspace: the kinds of things you track. Clarify ships with a set of built-in objects:

You can also define custom objects to model anything else (support tickets, products, subscriptions). Custom object names are normalized to a c_ prefix: "Sales Order" becomes c_sales_order. They then use the same endpoints as built-in objects. See Schemas and Relationships.

The object name is the {object} path parameter on most endpoints:

/workspaces/{slug}/objects/person/records
/workspaces/{slug}/objects/c_sales_order/records

Records

A record is a single instance of an object: one person, one company, one deal. Each record has an id and a set of field values.

Each object has a unique field. Creating a record is a plain insert by default: a value that collides with an existing record's unique field is rejected. Pass match_on to upsert instead: a matching write updates the existing record rather than failing.

See how records match for the full table.

Records vs. resources

You'll see both /records and /resources paths in the API. They refer to the same underlying thing. A resource is simply the JSON:API representation of a record on the wire. As a rule of thumb:

• Query and list operations live under Resources (GET …/resources), where you can filter, paginate, sort, and include related records.
• Create, update, and delete operations live under Records (POST, PATCH, DELETE …/records).

Schemas and fields

A schema is the definition of an object: the set of fields (also called properties or attributes) available on it, their types, and their relationships. GET /schemas returns a flat list of every schema in the workspace, each identified by a schema URL; built-in objects and custom objects alike appear under .../entities/*. Manage schemas through the Schemas endpoints.

Collection fields

Some fields hold multiple values. These collection fields are written as an object with an items array, not a bare list:

{ "email_addresses": { "items": ["jane@example.com", "jane@work.com"] } }

Common examples are email_addresses on people and domains on companies. This shape is easy to miss. See the AI agents tips if you're handing the API to a coding agent.

Relationships

Relationships are typed links between records across objects: a person works at a company, a deal belongs to a company. You can set a relationship through a foreign-key field at creation time (e.g. company_id), or manage it explicitly through the Records Relationships endpoints.

To pull related records back in a read, expand them with the include parameter:

curl --globoff \
  -H "Authorization: api-key YOUR_API_KEY" \
  "https://api.clarify.ai/v1/workspaces/acme/objects/person/resources?include=company_id,deals"

Lists

A list is a collection of records of a single object, Clarify's saved-view and pipeline abstraction. Membership is defined by a query that re-evaluates automatically as your data changes, so records enter and leave the list as they start or stop matching (like an audience or segment).

Manage lists through the Lists endpoints; see the Dynamic Lists guide for authoring the query behind a list.

Activities and comments

The activity stream is the chronological timeline on a record: creations, field updates, and comments. Read it with GET …/records/{id}/activities.

Comments are created, updated, and deleted through their own Comments endpoints, but there is no separate "list comments" endpoint; they surface in the activity stream of the record they're attached to.

Workflows

Workflows automate actions inside a workspace on a "when X happens, do Y" basis. For example, when a deal moves to a stage, add it to a list or fire an outbound webhook. Manage them through the Workflows endpoints, and see Build a workflow for an end-to-end example.

The JSON:API envelope

Every request and response follows the JSON:API specification, so the shape is predictable across all endpoints. A single resource is wrapped in a data object with type, id, attributes, and optional relationships:

{
  "data": {
    "type": "person",
    "id": "5f8b7d2e-9c4a-4e1b-8f3d-2a6c9e0b4d71",
    "attributes": {
      "name": { "first_name": "Jane", "last_name": "Doe" },
      "email_addresses": { "items": ["jane@acme.com"] }
    }
  }
}

List endpoints return data as an array alongside meta (totals, paging) and links (next/previous). When you include related records, they appear in a top-level included array. See Pagination and Filtering for the query conventions.