clarify-api

Summary

The Clarify API is a RESTful workspace-scoped API for programmatically managing CRM records, schemas, and meeting data. Use it to create, read, update, and delete records, manage schemas, ingest or sync meeting transcripts and metadata, and build integrations or dashboards that operate on a per-workspace (slug) basis. The API supports API key authentication for admin-level programmatic access (read/write/delete with redacted email metadata) and OAuth 2.0 (Authorization Code, PKCE, Refresh Token) for partner integrations. Key features include a consistent root URL pattern, documented auth endpoints, standard pagination and filtering for list operations, and safeguards around sensitive fields. Typical use cases: syncing calendar/meeting data to CRM, automating record creation, embedding Clarify data in analytics tools, and building secure third-party integrations. Advantage: secure, workspace-scoped access with flexible auth and schema control.

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:
   • They have access to records within the workspace and can read, write, and delete data
   • They only have access to redacted email metadata, sensitive fields like bodies are not available
   • They have the same permissions for viewing meeting data as other users
2. 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}

2. 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}

3. 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