Introduction

The Clarify API lets you manage your CRM data — people, companies, deals, meetings, and custom objects. It follows the JSON:API spec.

AI agents

Give your AI assistant full Clarify API context — every endpoint, field type, and best practice:

npx skills add clarifyhq/skills

Works with Claude Code, Cursor, and any agent that supports skills. See AI assistants for more.

Base URL

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

Your workspace slug is in the URL when you log in, or click your avatar in the app to find it.

Authentication

Pass your API key in the Authorization header:

curl -H "Authorization: api-key YOUR_API_KEY" \
  "https://api.clarify.ai/v1/workspaces/acme/objects/person/resources"

Use api-key, not Bearer. To create a key, go to Settings > API Keys in your workspace (admin only).

For partner integrations, Clarify also supports OAuth 2.0.

Quick example

Create a person:

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

The create endpoint auto-upserts — if a person with that email already exists, it updates instead of creating a duplicate.

Upsert behavior

Each object type has a unique field used for matching:

Key concepts

• Objects — Standard types (person, company, deal, meeting) plus custom objects
• Records — Individual entries within an object type
• Schemas — Field definitions per object, available via GET /schemas
• Collection fields — Multi-value fields like email_addresses and domains use { items: [...] } format
• Relationships — Links between records (person to company, deal to company, etc.)
• JSON:API format — Requests and responses use { data: { type, id, attributes } } structure

What's not in the API

A few things you can do in the Clarify UI aren't currently surfaced via the public API:

• Email content — message bodies, threads, and attachments aren't exposed; sensitive fields are redacted by design.
• Meeting notes — the notes field on meeting records is visible in the UI but not writable via the API yet. It's on the roadmap.
• Direct mailbox actions — sending email through the API isn't supported. Use campaigns for outbound, and the email tooling inside Clarify for replies.
• Webhooks — outbound webhook subscriptions aren't available yet. See webhooks for the near-real-time alternatives.

If you're trying to do something here and there isn't an obvious workaround, reach out — there's a good chance it's on the roadmap.