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.

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