name: clarify-api
description: Guidelines for working with the Clarify CRM API - includes authentication, endpoints, pagination, filtering, and CRUD operations for records
author: clarify
version: 1.0.0

Clarify API

Note: The Clarify API is under active development and subject to breaking changes. Contact [email protected] with any questions.

Root URL

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

The slug is the workspace ID assigned to the customer's organization. You can find it in the URL when logging in or by clicking your avatar in the application.

Authentication

API Key Authentication

1. Generate a new API key from workspace settings. Generated keys have admin level permissions to your workspace:
2. They have access to records within the workspace and can read, write, and delete data
3. They only have access to redacted email metadata, sensitive fields like bodies are not available

4. They have the same permissions for viewing meeting data as other users

5. Include this API key in the Authorization header with the api-key scheme:

curl --header "Authorization: api-key $APIKEY" \
  https://api.clarify.ai/v1/workspaces/$WORKSPACE_SLUG/schemas

Partner OAuth 2.0 Authentication

Clarify uses OAuth and supports Authorization Code, Authorization Code with PKCE, and Refresh Token grants.

OAuth Endpoints:
- Authorization: https://auth1.clarify.ai/oauth2/authorize
- Token: https://auth1.clarify.ai/oauth2/token
- Refresh Token: https://auth1.clarify.ai/oauth2/token
- Scopes: openid profile email offline_access

OAuth Flow:

1. Get authorization code:

GET https://auth1.clarify.ai/oauth2/authorize?response_type=code&client_id={your_client_id}&scope=openid%20profile%20email%20offline_access&redirect_uri={your_redirect_url}

1. Exchange for tokens:

POST https://auth1.clarify.ai/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
code={your-code}
redirect_uri={your_redirect_uri}
client_id={your_client_id}
client_secret={your_client_secret}

1. Use access token in API calls:

Authorization: Bearer {access-token}

API Structure

The API follows the JSON:API spec.

Pagination

Maximum response size is 1000 items.

Request:
- page[limit]={number} — maximum number of items to return

Response fields:
- data — array of returned items
- meta — pagination metadata: total_records, total_pages, offset, limit
- links — URL references: prev (if available), next (if available)

Ordering

Control record order with the sortOrder query parameter:
- sortOrder[column] — field name to order by
- sortOrder[dir] — direction: ASC or DESC

Filtering

Filter records with filter query parameters. Conditions are always AND (OR not supported).

Basic syntax:

filter[{field_name}]={field_value}

Advanced syntax with operators:

filter[{field_name}][{operator}]={field_value}

Supported operators by field type:

Endpoints

Get Objects & Schemas

GET /schemas

Returns an array of schema JSONs:
- core/* — internal schemas referenced in other schemas
- entities/* — objects available: company, deal, meeting, meeting_recording, person, task, user

Each entity has its JSON Schema definition in the attributes field.

Get Records

GET /objects/{object}/resources

Parameters:
- sortOrder — field to order by with optional direction
- filters — one or more criteria to filter records
- include — comma-separated list of relationship fields to include

Create Record

POST /objects/{object}/records

Request body:

{
  "data": {
    "type": "{object}",
    "attributes": {
      "{field-name}": "{field-value}"
    }
  }
}

Unique fields for upsert behavior:

Get Record

GET /objects/{object}/records/{id}

Parameters:
- include — comma-separated list of relationship fields to include

Update Record

PATCH /objects/{object}/records/{id}

Request body:

{
  "data": {
    "id": "{id}",
    "type": "{object}",
    "attributes": {
      "{field-name}": "{field-value}"
    }
  }
}

Bulk Upsert Records

POST /objects/{object}/records/bulk

Request body:

{
  "data": [{
    "type": "{entity}",
    "attributes": {
      "{field-name}": "{field-value}"
    }
  }]
}

Bulk Delete Records

There is no way to bulk delete records today.

Set Relationship

PATCH /objects/{object}/records/{id}/relationships/{field-name}

Request body:

{
  "data": [
    {
      "id": "{id-of-record-to-associate}",
      "type": "{object}"
    }
  ]
}

Unset Relationship

DELETE /objects/{object}/records/{id}/relationships/{field-name}

Request body:

{
  "data": [
    {
      "id": "{id-of-record-to-disassociate}",
      "type": "{object}"
    }
  ]
}

Get Recording Artifacts

POST /meetings/{id}/recordings/{id}/artifacts

Response:

{
  "data": {
    "videoUrl": "{signed-video-url}",
    "transcriptionUrl": "{signed-transcription-url}"
  }
}

Swagger Documentation

Full API documentation: https://api.clarify.ai/swagger