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 agents 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:

Authorization: api-key YOUR_API_KEY

Create keys in Settings → API Keys. Partner integrations can also use OAuth 2.0. See Authentication for key types, scopes, and the OAuth flow.

Quick example

Create a person. Passing match_on set to email_addresses (the unique field for people) makes the request an upsert: if a record with that email already exists, Clarify updates it instead of creating a duplicate. Without match_on, a colliding email is rejected. See how records match for the unique field on each object.

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 '{
    "match_on": "email_addresses",
    "data": {
      "type": "person",
      "attributes": {
        "name": { "first_name": "Jane", "last_name": "Doe" },
        "email_addresses": { "items": ["jane@example.com"] }
      }
    }
  }'

Explore