Introduction

The Clarify API lets you read and write your CRM data — people, companies, deals, meetings, and custom objects — programmatically. It follows the JSON:API specification, so requests and responses share a predictable shape across every endpoint.

AI agents

The fastest way to build against Clarify is to hand the docs to your coding agent. Install the Clarify skill, which works with Claude Code, Cursor, and any agent that supports skills:

npx skills add clarifyhq/skills

See AI assistants for MCP setup, example prompts, and tips.

Base URL

Every request is scoped to a workspace:

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

Your workspace slug appears in your Clarify login URL and under the user avatar menu.

Authentication

Send your API key in the Authorization header using the api-key scheme — not Bearer:

Authorization: api-key YOUR_API_KEY

Create keys in Settings → API Keys (workspace admins only). Partner integrations can also use OAuth 2.0 — see Authentication.

Quick example

Create a person. Because email_addresses is the unique field for people, this request upserts: if a record with that email already exists, Clarify updates it instead of creating a duplicate.

curl -X POST \
  https://api.clarify.ai/v1/workspaces/your-workspace/objects/person/records \
  -H "Authorization: api-key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "type": "record",
      "attributes": {
        "name": "Jane Doe",
        "email_addresses": { "items": ["jane@example.com"] }
      }
    }
  }'

Upsert behavior

When you create a record, Clarify matches on each object's unique field. A match updates the existing record; no match creates a new one.

Key concepts

• Objects — the entity types in your workspace: person, company, deal, meeting, task, plus any custom objects you define.
• Records — individual instances of an object (one person, one deal).
• Schemas — the fields defined on an object. Manage them via the Schemas endpoints.
• Collection fields — multi-value fields, written as { "items": [...] } (e.g. email_addresses, domains).
• Relationships — typed links between records (e.g. a person works at a company).
• JSON:API — the request/response envelope: a data object with type, id, attributes, and relationships.

What's not in the API

These are not yet available through the public API:

• Reading email content
• Reading or writing meeting notes
• Direct mailbox actions (sending mail, etc.)
• Webhooks — see Webhooks for current alternatives

Explore