API reference

Version 1.0.0 · Base URL https://app.smartcontact.online/v1 · 120 operations · Download openapi.json

Account

PATCH /me

Update your name, profile photo (a small data:image URL, or null to remove it) or email notifications

Request body
FieldTypeNotes
first_name string Up to 60 characters.
last_name string Up to 60 characters.
avatar string or null Up to 81920 characters.
email_notifications boolean
204 Updated

No body.

GET /me/email-logging

Your personal address for logging emails: BCC it, or forward an email to it

200 Address
FieldTypeNotes
enabled boolean
address string or null

POST /me/password

Get a one-time link to change your password

200 OK
FieldTypeNotes
url string (uri)

Admin

POST /pipeline-stages

Add a stage to the end of a pipeline

Request body
FieldTypeNotes
pipeline_id required string (uuid)
name required string Up to 60 characters.
kind one of: open, won, lost, account Default "open".
201 Created (PipelineStageAdmin)
FieldTypeNotes
id string (uuid)
name string
position integer
kind one of: open, won, lost, account
probability integer or null
companies integer

POST /lead-sources

Add a lead source

Request body
FieldTypeNotes
name required string Up to 60 characters.
channel required one of: web, referral, event, outbound, social, email, phone, partner, ads, other
201 Created (LeadSourceAdmin)
FieldTypeNotes
id string (uuid)
name string
channel string
companies integer

GET /workspace

Workspace profile and settings

200 OK (Workspace)
FieldTypeNotes
id string (uuid)
slug string
name string
plan string
settings WorkspaceSettings

PATCH /workspace

Rename the workspace or change its settings (admins)

Request body
FieldTypeNotes
name string Up to 100 characters.
settings object
200 OK (Workspace)
FieldTypeNotes
id string (uuid)
slug string
name string
plan string
settings WorkspaceSettings

GET /pipelines

Pipelines with their stages and company counts

200 OK
FieldTypeNotes
data array of Pipeline

POST /pipelines

Create a pipeline, optionally with initial stages

Request body
FieldTypeNotes
name required string Up to 80 characters.
object one of: company, deal Default "company".
stages array of object Default [].
201 Created (Pipeline)
FieldTypeNotes
id string (uuid)
name string
object one of: company, deal
is_default boolean
position integer
stages array of PipelineStageAdmin

PATCH /pipelines/{id}

Rename a pipeline, make it the default, or reorder its stages

ParameterInTypeNotes
id required path string (uuid)
Request body
FieldTypeNotes
name string Up to 80 characters.
is_default one of: true
stage_order array of string (uuid) Every stage id of this pipeline, in the new order
200 OK (Pipeline)
FieldTypeNotes
id string (uuid)
name string
object one of: company, deal
is_default boolean
position integer
stages array of PipelineStageAdmin

DELETE /pipelines/{id}

Delete a pipeline that no company uses (not the default one)

ParameterInTypeNotes
id required path string (uuid)
204 Deleted

No body.

PATCH /pipeline-stages/{id}

Rename a stage or change its kind (e.g. mark the stage where a lead becomes an Account)

ParameterInTypeNotes
id required path string (uuid)
Request body
FieldTypeNotes
name string Up to 60 characters.
kind one of: open, won, lost, account
probability integer or null 0–100.
200 OK (PipelineStageAdmin)
FieldTypeNotes
id string (uuid)
name string
position integer
kind one of: open, won, lost, account
probability integer or null
companies integer

DELETE /pipeline-stages/{id}

Delete a stage. Companies in it must move: pass move_to (a stage id) when it is in use

ParameterInTypeNotes
id required path string (uuid)
move_to query string (uuid)
204 Deleted

No body.

PATCH /lead-sources/{id}

Rename a lead source

ParameterInTypeNotes
id required path string (uuid)
Request body
FieldTypeNotes
name string Up to 60 characters.
channel one of: web, referral, event, outbound, social, email, phone, partner, ads, other
200 OK (LeadSourceAdmin)
FieldTypeNotes
id string (uuid)
name string
channel string
companies integer

DELETE /lead-sources/{id}

Delete an unused lead source

ParameterInTypeNotes
id required path string (uuid)
204 Deleted

No body.

GET /custom-fields

Custom fields, in display order

ParameterInTypeNotes
object query one of: company, contact, deal
include_archived query one of: true, false Default "false".
200 Fields
FieldTypeNotes
data array of CustomField

POST /custom-fields

Add a custom field

Request body
FieldTypeNotes
object required one of: company, contact, deal
label required string Up to 60 characters.
type required one of: text, number, date, select, checkbox, url
options array of string
201 Created (CustomField)
FieldTypeNotes
id string (uuid)
object one of: company, contact, deal
key string
label string
type one of: text, number, date, select, checkbox, url
options array of string
position integer
archived boolean

PATCH /custom-fields/{id}

Rename, re-order, change choices, archive or restore a custom field (the key and type never change)

ParameterInTypeNotes
id required path string (uuid)
Request body
FieldTypeNotes
label string Up to 60 characters.
options array of string
position integer 0–1000.
archived boolean
200 Updated (CustomField)
FieldTypeNotes
id string (uuid)
object one of: company, contact, deal
key string
label string
type one of: text, number, date, select, checkbox, url
options array of string
position integer
archived boolean

GET /audit-log

Who did what: admin changes (settings, users, keys, billing, support access) and record changes, newest first

ParameterInTypeNotes
source query one of: all, admin, record Default "all".
before query string (date-time)
limit query integer Default 50.
offset query integer or null Default 0.
200 Entries
FieldTypeNotes
data array of AuditEntry
total integer
next_before string or null

POST /export

Export the whole workspace as a ZIP of CSV files (companies, contacts, deals, activities, tasks, meetings, users)

200 Download link (valid 10 minutes)
FieldTypeNotes
url string
size integer
file_name string

GET /web-forms

Web-to-lead forms

200 Forms
FieldTypeNotes
data array of WebForm

POST /web-forms

Create a web-to-lead form; paste embed_html into your website

Request body
FieldTypeNotes
name required string Up to 100 characters.
fields array of one of: company, first_name, last_name, email, phone, job_title, message
require_consent boolean
consent_text string or null Up to 500 characters.
owner_id string (uuid) or null
source_id string (uuid) or null
campaign_id string (uuid) or null Campaign credited with new leads, unless the page's ?utm_campaign= matches another
redirect_url string or null
enabled boolean
201 Created (WebForm)
FieldTypeNotes
id string (uuid)
name string
public_key string
fields array of one of: company, first_name, last_name, email, phone, job_title, message
require_consent boolean
consent_text string or null
owner_id string (uuid) or null
source_id string (uuid) or null
campaign_id string (uuid) or null
redirect_url string or null
enabled boolean
submissions integer
last_submission_at string or null
created_at string
action_url string
embed_html string

PATCH /web-forms/{id}

Change, disable or re-enable a web form

ParameterInTypeNotes
id required path string (uuid)
Request body
FieldTypeNotes
name string Up to 100 characters.
fields array of one of: company, first_name, last_name, email, phone, job_title, message
require_consent boolean
consent_text string or null Up to 500 characters.
owner_id string (uuid) or null
source_id string (uuid) or null
campaign_id string (uuid) or null Campaign credited with new leads, unless the page's ?utm_campaign= matches another
redirect_url string or null
enabled boolean
200 Updated (WebForm)
FieldTypeNotes
id string (uuid)
name string
public_key string
fields array of one of: company, first_name, last_name, email, phone, job_title, message
require_consent boolean
consent_text string or null
owner_id string (uuid) or null
source_id string (uuid) or null
campaign_id string (uuid) or null
redirect_url string or null
enabled boolean
submissions integer
last_submission_at string or null
created_at string
action_url string
embed_html string

GET /roles

Roles and their permissions

200 OK
FieldTypeNotes
data array of Role
permissions array of string

POST /roles

Create a custom role

Request body
FieldTypeNotes
name required string Up to 40 characters.
permissions required array of one of: companies:read, companies:write, contacts:read, contacts:write, activities:write, tasks:read, tasks:write, settings:manage, users:manage, privacy:override
201 Created (Role)
FieldTypeNotes
id string (uuid)
name string
permissions array of string
is_system boolean
members integer

PATCH /roles/{id}

Edit a custom role (built-in roles are fixed)

ParameterInTypeNotes
id required path string (uuid)
Request body
FieldTypeNotes
name string Up to 40 characters.
permissions array of one of: companies:read, companies:write, contacts:read, contacts:write, activities:write, tasks:read, tasks:write, settings:manage, users:manage, privacy:override
200 OK (Role)
FieldTypeNotes
id string (uuid)
name string
permissions array of string
is_system boolean
members integer

DELETE /roles/{id}

Delete an unused custom role

ParameterInTypeNotes
id required path string (uuid)
204 Deleted

No body.

PATCH /members/{id}

Change a member's role or disable/enable them

ParameterInTypeNotes
id required path string (uuid)
Request body
FieldTypeNotes
role_id string (uuid)
status one of: active, disabled
204 Updated

No body.

GET /invitations

Pending invitations

200 OK
FieldTypeNotes
data array of Invitation

POST /invitations

Invite someone by email; they join with the chosen role when they accept

Request body
FieldTypeNotes
email required string (email) Up to 254 characters.
role_id required string (uuid)
201 Invited (Invitation)
FieldTypeNotes
id string (uuid)
email string
role string
status string
created_at string

DELETE /invitations/{id}

Revoke a pending invitation

ParameterInTypeNotes
id required path string (uuid)
204 Revoked

No body.

API keys

GET /api-keys

List workspace API keys (secrets are never returned)

200 Keys
FieldTypeNotes
data array of ApiKey

POST /api-keys

Create an API key. The key is returned once and cannot be shown again.

Request body (ApiKeyCreate)
FieldTypeNotes
name required string Up to 100 characters.
kind required one of: agent, integration agent: an AI agent (labelled as an agent, cannot delete). integration: your own scripts and private apps.
role string Role name the key acts with: "Agent (read only)", "Agent (read & write)", or any other role except Owner/Admin Default "Agent (read only)".
expires_in_days integer 1–730.
201 Created (any)
FieldTypeNotes
id string (uuid)
name string
kind one of: agent, integration
prefix string Public part of the key, safe to show
role string
created_by string (uuid)
created_at string
expires_at string or null
last_used_at string or null
revoked_at string or null
key string

DELETE /api-keys/{id}

Revoke an API key immediately

ParameterInTypeNotes
id required path string (uuid)
204 Revoked

No body.

Billing

GET /billing

Plan, seats, subscription and invoices (admins)

200 Billing
FieldTypeNotes
plan string
seats integer
limits object
has_billing_account boolean
complimentary_until string or null Standard is free until this date (granted by SmartContact); add payment details to stay on Standard
subscription any
invoices array of any

POST /billing/checkout

Start upgrading to Standard: returns a Stripe Checkout URL

Request body
FieldTypeNotes
interval one of: month, year Default "month".
200 Checkout
FieldTypeNotes
url string (uri)

POST /billing/portal

Open the Stripe Customer Portal: card, billing details, VAT number, invoices, cancel

200 Portal
FieldTypeNotes
url string (uri)

Companies

GET /companies

List companies (leads and accounts)

ParameterInTypeNotes
limit query integer Default 25.
cursor query string
q query string Matches name, domain, account number or postcode
owner query one of: me or one of: none or string (uuid)
custom query string Records whose custom fields contain these values (JSON object)
kind query one of: lead, account
stage_id query string (uuid)
pipeline_id query string (uuid)
source_id query string (uuid)
campaign_id query string (uuid)
deleted query one of: true, false true lists the recycle bin Default "false".
sort query one of: created_desc, created_asc, name_asc, name_desc, updated_desc Default "created_desc".
offset query integer or null Offset paging (returns total); use instead of cursor
200 A page of companies
FieldTypeNotes
data array of Company
next_cursor string or null
total integer

POST /companies

Create a company

Request body (CompanyCreate)
FieldTypeNotes
name required string Up to 200 characters.
website string (uri) or null Up to 300 characters.
domain string or null Up to 253 characters.
phone string or null Up to 40 characters.
address object
country_code string or null Up to 2 characters.
industry string or null Up to 100 characters.
turnover_band string or null Up to 50 characters.
employee_count integer or null
account_number string or null Up to 50 characters.
company_number string or null Company registration number (e.g. Companies House) Up to 50 characters.
sic_codes array of string SIC codes the company operates in (UK SIC 2007 codes are 5 digits)
description string or null What the company does, in a sentence or two Up to 2000 characters.
owner_id string (uuid) or null
stage_id string (uuid) or null
source_id string (uuid) or null
campaign_id string (uuid) or null Marketing campaign that brought this lead in (Standard plan)
primary_contact_id string (uuid) or null
custom object
201 Created (Company)
FieldTypeNotes
id string (uuid)
name string or null
website string (uri) or null Up to 300 characters.
domain string or null Up to 253 characters.
phone string or null Up to 40 characters.
address object
country_code string or null Up to 2 characters.
industry string or null Up to 100 characters.
turnover_band string or null Up to 50 characters.
employee_count integer or null
account_number string or null Up to 50 characters.
company_number string or null Company registration number (e.g. Companies House) Up to 50 characters.
sic_codes array of string SIC codes the company operates in (UK SIC 2007 codes are 5 digits)
description string or null What the company does, in a sentence or two Up to 2000 characters.
owner_id string (uuid) or null
stage_id string (uuid) or null
source_id string (uuid) or null
campaign_id string (uuid) or null Marketing campaign that brought this lead in (Standard plan)
primary_contact_id string (uuid) or null
custom object
is_account boolean True when the stage kind is "account" (legacy Lead vs Account).
stage_name string or null
pipeline_id string (uuid) or null
owner_name string or null
source_name string or null
campaign_name string or null
deleted_at string or null
created_at string
updated_at string

GET /companies/counts

Counts for the navigation: all, leads, accounts, mine, unassigned, recycle bin

200 Counts
FieldTypeNotes
all number
leads number
accounts number
mine number
unassigned number
deleted number

POST /companies/bulk

Bulk move stage, reassign owner, delete or restore (people only, up to 200 at a time)

Request body
FieldTypeNotes
ids required array of string (uuid)
action required one of: move_stage, reassign, delete, restore
stage_id string (uuid)
owner_id string (uuid) or null
200 Updated
FieldTypeNotes
updated integer

GET /companies/{id}

Get a company

ParameterInTypeNotes
id required path string (uuid)
200 The company (Company)
FieldTypeNotes
id string (uuid)
name string or null
website string (uri) or null Up to 300 characters.
domain string or null Up to 253 characters.
phone string or null Up to 40 characters.
address object
country_code string or null Up to 2 characters.
industry string or null Up to 100 characters.
turnover_band string or null Up to 50 characters.
employee_count integer or null
account_number string or null Up to 50 characters.
company_number string or null Company registration number (e.g. Companies House) Up to 50 characters.
sic_codes array of string SIC codes the company operates in (UK SIC 2007 codes are 5 digits)
description string or null What the company does, in a sentence or two Up to 2000 characters.
owner_id string (uuid) or null
stage_id string (uuid) or null
source_id string (uuid) or null
campaign_id string (uuid) or null Marketing campaign that brought this lead in (Standard plan)
primary_contact_id string (uuid) or null
custom object
is_account boolean True when the stage kind is "account" (legacy Lead vs Account).
stage_name string or null
pipeline_id string (uuid) or null
owner_name string or null
source_name string or null
campaign_name string or null
deleted_at string or null
created_at string
updated_at string

PATCH /companies/{id}

Update company fields

ParameterInTypeNotes
id required path string (uuid)
Request body (CompanyUpdate)
FieldTypeNotes
name string Up to 200 characters.
website string (uri) or null Up to 300 characters.
domain string or null Up to 253 characters.
phone string or null Up to 40 characters.
address object
country_code string or null Up to 2 characters.
industry string or null Up to 100 characters.
turnover_band string or null Up to 50 characters.
employee_count integer or null
account_number string or null Up to 50 characters.
company_number string or null Company registration number (e.g. Companies House) Up to 50 characters.
sic_codes array of string SIC codes the company operates in (UK SIC 2007 codes are 5 digits)
description string or null What the company does, in a sentence or two Up to 2000 characters.
owner_id string (uuid) or null
stage_id string (uuid) or null
source_id string (uuid) or null
campaign_id string (uuid) or null Marketing campaign that brought this lead in (Standard plan)
primary_contact_id string (uuid) or null
custom object
200 Updated (Company)
FieldTypeNotes
id string (uuid)
name string or null
website string (uri) or null Up to 300 characters.
domain string or null Up to 253 characters.
phone string or null Up to 40 characters.
address object
country_code string or null Up to 2 characters.
industry string or null Up to 100 characters.
turnover_band string or null Up to 50 characters.
employee_count integer or null
account_number string or null Up to 50 characters.
company_number string or null Company registration number (e.g. Companies House) Up to 50 characters.
sic_codes array of string SIC codes the company operates in (UK SIC 2007 codes are 5 digits)
description string or null What the company does, in a sentence or two Up to 2000 characters.
owner_id string (uuid) or null
stage_id string (uuid) or null
source_id string (uuid) or null
campaign_id string (uuid) or null Marketing campaign that brought this lead in (Standard plan)
primary_contact_id string (uuid) or null
custom object
is_account boolean True when the stage kind is "account" (legacy Lead vs Account).
stage_name string or null
pipeline_id string (uuid) or null
owner_name string or null
source_name string or null
campaign_name string or null
deleted_at string or null
created_at string
updated_at string

DELETE /companies/{id}

Move a company to the recycle bin (restorable for 30 days)

ParameterInTypeNotes
id required path string (uuid)
204 Deleted

No body.

POST /companies/{id}/merge

Merge other company records into this one: their timeline, tasks, files, contacts, deals and meetings move here, empty fields are filled in, and the others go to the recycle bin

ParameterInTypeNotes
id required path string (uuid)
Request body
FieldTypeNotes
source_ids required array of string (uuid)
200 Merged
FieldTypeNotes
merged integer

Contacts

GET /contacts

List contacts

ParameterInTypeNotes
limit query integer Default 25.
cursor query string
q query string Matches name or email
company_id query string (uuid)
reports_to_id query string (uuid) A manager's direct reports
owner query one of: me or string (uuid)
custom query string Records whose custom fields contain these values (JSON object)
deleted query one of: true, false true lists the recycle bin Default "false".
200 A page of contacts
FieldTypeNotes
data array of Contact
next_cursor string or null

POST /contacts

Create a contact

Request body (ContactCreate)
FieldTypeNotes
company_id string (uuid) or null
first_name string or null Up to 100 characters.
last_name string or null Up to 100 characters.
email string (email) or null Up to 254 characters.
phone string or null Up to 40 characters.
mobile string or null Up to 40 characters.
job_title string or null Up to 150 characters.
reports_to_id string (uuid) or null
owner_id string (uuid) or null
lawful_basis one of: legitimate_interest, consent, contract
custom object
201 Created (Contact)
FieldTypeNotes
id string (uuid)
company_id string (uuid) or null
first_name string or null Up to 100 characters.
last_name string or null Up to 100 characters.
email string (email) or null Up to 254 characters.
phone string or null Up to 40 characters.
mobile string or null Up to 40 characters.
job_title string or null Up to 150 characters.
reports_to_id string (uuid) or null
owner_id string (uuid) or null
lawful_basis one of: legitimate_interest, consent, contract
custom object
created_at string
updated_at string
deleted_at string or null

GET /contacts/{id}

Get a contact

ParameterInTypeNotes
id required path string (uuid)
200 The contact (Contact)
FieldTypeNotes
id string (uuid)
company_id string (uuid) or null
first_name string or null Up to 100 characters.
last_name string or null Up to 100 characters.
email string (email) or null Up to 254 characters.
phone string or null Up to 40 characters.
mobile string or null Up to 40 characters.
job_title string or null Up to 150 characters.
reports_to_id string (uuid) or null
owner_id string (uuid) or null
lawful_basis one of: legitimate_interest, consent, contract
custom object
created_at string
updated_at string
deleted_at string or null

PATCH /contacts/{id}

Update contact fields

ParameterInTypeNotes
id required path string (uuid)
Request body (ContactUpdate)
FieldTypeNotes
company_id string (uuid) or null
first_name string or null Up to 100 characters.
last_name string or null Up to 100 characters.
email string (email) or null Up to 254 characters.
phone string or null Up to 40 characters.
mobile string or null Up to 40 characters.
job_title string or null Up to 150 characters.
reports_to_id string (uuid) or null
owner_id string (uuid) or null
lawful_basis one of: legitimate_interest, consent, contract
custom object
200 Updated (Contact)
FieldTypeNotes
id string (uuid)
company_id string (uuid) or null
first_name string or null Up to 100 characters.
last_name string or null Up to 100 characters.
email string (email) or null Up to 254 characters.
phone string or null Up to 40 characters.
mobile string or null Up to 40 characters.
job_title string or null Up to 150 characters.
reports_to_id string (uuid) or null
owner_id string (uuid) or null
lawful_basis one of: legitimate_interest, consent, contract
custom object
created_at string
updated_at string
deleted_at string or null

DELETE /contacts/{id}

Move a contact to the recycle bin (restorable for 30 days)

ParameterInTypeNotes
id required path string (uuid)
204 Deleted

No body.

POST /contacts/{id}/restore

Restore a contact from the recycle bin

ParameterInTypeNotes
id required path string (uuid)
204 Restored

No body.

POST /contacts/{id}/merge

Merge other contact records into this one: their timeline, tasks, files, deals and meetings move here, empty fields are filled in, and the others go to the recycle bin

ParameterInTypeNotes
id required path string (uuid)
Request body
FieldTypeNotes
source_ids required array of string (uuid)
200 Merged
FieldTypeNotes
merged integer

Deals

GET /deals

List deals with totals (value and weighted value)

ParameterInTypeNotes
pipeline_id query string (uuid)
stage_id query string (uuid)
company_id query string (uuid)
campaign_id query string (uuid)
owner query one of: me or string (uuid)
custom query string Records whose custom fields contain these values (JSON object)
status query one of: open, won, lost
q query string
sort query one of: close_asc, value_desc, created_desc, updated_desc Default "created_desc".
limit query integer Default 50.
offset query integer or null Default 0.
200 Deals
FieldTypeNotes
data array of Deal
total integer
value number
weighted number

POST /deals

Create a deal (defaults to the first stage of the default deals pipeline)

Request body
FieldTypeNotes
name required string Up to 200 characters.
company_id string (uuid) or null
contact_id string (uuid) or null
value number Deal value in major units (e.g. 1250.50) 0–1000000000000.
currency string Up to 3 characters.
stage_id string (uuid)
probability integer or null 0–100.
expected_close string (date) or null
lost_reason string or null Up to 500 characters.
owner_id string (uuid) or null
source_id string (uuid) or null
campaign_id string (uuid) or null Campaign credited with this deal; defaults to the company's campaign
custom object
201 Created (Deal)
FieldTypeNotes
id string (uuid)
name string
company_id string (uuid) or null
company_name string or null
contact_id string (uuid) or null
contact_name string or null
value number
currency string
pipeline_id string (uuid)
stage_id string (uuid)
stage_name string
stage_kind string
probability integer or null Deal probability, or the stage default when unset
expected_close string or null
status one of: open, won, lost
closed_at string or null
lost_reason string or null
owner_id string (uuid) or null
owner_name string or null
source_id string (uuid) or null
campaign_id string (uuid) or null
campaign_name string or null
custom object
created_at string
updated_at string

GET /deals/forecast

Open pipeline, weighted forecast and won/lost totals for this month and quarter

ParameterInTypeNotes
pipeline_id query string (uuid)
owner query one of: me or string (uuid)
200 Forecast

No body.

GET /deals/{id}

Get a deal

ParameterInTypeNotes
id required path string (uuid)
200 Deal (Deal)
FieldTypeNotes
id string (uuid)
name string
company_id string (uuid) or null
company_name string or null
contact_id string (uuid) or null
contact_name string or null
value number
currency string
pipeline_id string (uuid)
stage_id string (uuid)
stage_name string
stage_kind string
probability integer or null Deal probability, or the stage default when unset
expected_close string or null
status one of: open, won, lost
closed_at string or null
lost_reason string or null
owner_id string (uuid) or null
owner_name string or null
source_id string (uuid) or null
campaign_id string (uuid) or null
campaign_name string or null
custom object
created_at string
updated_at string

PATCH /deals/{id}

Update a deal; moving it to a Won or Lost stage closes it

ParameterInTypeNotes
id required path string (uuid)
Request body
FieldTypeNotes
name string Up to 200 characters.
company_id string (uuid) or null
contact_id string (uuid) or null
value number Deal value in major units (e.g. 1250.50) 0–1000000000000.
currency string Up to 3 characters.
stage_id string (uuid)
probability integer or null 0–100.
expected_close string (date) or null
lost_reason string or null Up to 500 characters.
owner_id string (uuid) or null
source_id string (uuid) or null
campaign_id string (uuid) or null Campaign credited with this deal; defaults to the company's campaign
custom object
200 Updated (Deal)
FieldTypeNotes
id string (uuid)
name string
company_id string (uuid) or null
company_name string or null
contact_id string (uuid) or null
contact_name string or null
value number
currency string
pipeline_id string (uuid)
stage_id string (uuid)
stage_name string
stage_kind string
probability integer or null Deal probability, or the stage default when unset
expected_close string or null
status one of: open, won, lost
closed_at string or null
lost_reason string or null
owner_id string (uuid) or null
owner_name string or null
source_id string (uuid) or null
campaign_id string (uuid) or null
campaign_name string or null
custom object
created_at string
updated_at string

DELETE /deals/{id}

Delete a deal

ParameterInTypeNotes
id required path string (uuid)
204 Deleted

No body.

Documents

GET /documents

Files attached to a company or contact

ParameterInTypeNotes
target_type required query one of: company, contact
target_id required query string (uuid)
200 Files
FieldTypeNotes
data array of Document

POST /documents

Start an upload: returns the document and a 15-minute upload URL (HTTP PUT the file bytes to it)

Request body
FieldTypeNotes
target_type required one of: company, contact
target_id required string (uuid)
name required string Up to 255 characters.
content_type required string Up to 150 characters.
size_bytes required integer
201 Upload ready
FieldTypeNotes
document Document
upload_url string (uri)

GET /documents/usage

Storage used by the workspace and its plan quota (bytes)

200 Usage
FieldTypeNotes
used number
quota number

POST /documents/{id}/complete

Confirm an upload finished; the file then appears on the record

ParameterInTypeNotes
id required path string (uuid)
200 Ready (Document)
FieldTypeNotes
id string (uuid)
target_type one of: company, contact
target_id string (uuid)
name string
content_type string
size_bytes integer
status string
uploaded_by string (uuid)
uploaded_by_name string or null
created_at string

GET /documents/{id}/download

A 5-minute download link for a file

ParameterInTypeNotes
id required path string (uuid)
200 Link
FieldTypeNotes
url string (uri)

DELETE /documents/{id}

Delete a file (removed from storage immediately)

ParameterInTypeNotes
id required path string (uuid)
204 Deleted

No body.

Duplicates

GET /duplicates

Likely duplicate companies (same domain or name) or contacts (same email, or same name at the same company)

ParameterInTypeNotes
object required query one of: company, contact
200 Groups
FieldTypeNotes
data array of object

POST /duplicates/dismiss

Mark a group as not duplicates so it stops being suggested

Request body
FieldTypeNotes
object required one of: company, contact
key required string Up to 4000 characters.
204 Dismissed

No body.

Import

POST /import/companies

Import companies (and an optional contact each) from mapped CSV rows. Use dry_run first.

Request body
FieldTypeNotes
rows required array of object
duplicates one of: skip, update, create What to do when a company with the same domain or name exists Default "skip".
dry_run boolean Default false.
200 Import report
FieldTypeNotes
created integer
updated integer
skipped integer
contacts integer
errors array of object
dry_run boolean

Integrations

GET /integrations/calendar

Which calendars can be connected here, and which ones you have connected

200 Status
FieldTypeNotes
available array of one of: microsoft, google
included_in_plan boolean Calendar sync is part of the Standard plan
connections array of object

POST /integrations/calendar/{provider}/connect

Start connecting a calendar: open the returned URL to sign in with Microsoft or Google

ParameterInTypeNotes
provider required path one of: microsoft, google
200 Sign-in URL
FieldTypeNotes
url string

DELETE /integrations/calendar/{provider}

Disconnect a calendar (its tokens are deleted; events already created stay in your calendar)

ParameterInTypeNotes
provider required path one of: microsoft, google
204 Disconnected

No body.

Marketing

GET /campaigns

List marketing campaigns with spend, leads, deals and won value (Standard plan)

ParameterInTypeNotes
q query string
status query one of: planned, active, ended
source_id query string (uuid)
limit query integer Default 100.
offset query integer or null Default 0.
200 Campaigns
FieldTypeNotes
data array of Campaign
total integer

POST /campaigns

Create a campaign (currency defaults to the workspace currency)

Request body
FieldTypeNotes
name required string Up to 200 characters.
source_id string (uuid) or null
status one of: planned, active, ended
starts_on string (date) or null
ends_on string (date) or null
budget number or null Budget in major units 0–1000000000000.
currency string Up to 3 characters.
utm_campaign string or null Matches ?utm_campaign= on pages with your web forms
external_ref string or null ID in another system, e.g. a Klaviyo campaign id Up to 200 characters.
owner_id string (uuid) or null
notes string or null Up to 5000 characters.
201 Created (Campaign)
FieldTypeNotes
id string (uuid)
name string
source_id string (uuid) or null
source_name string or null
status one of: planned, active, ended
starts_on string or null
ends_on string or null
budget number or null
currency string
utm_campaign string or null
external_ref string or null
owner_id string (uuid) or null
owner_name string or null
notes string or null
spend number Total spend so far, in the campaign currency
leads integer Companies this campaign brought in
deals integer
won_value number Value of won deals credited to the campaign (campaign currency)
touchpoints integer
created_at string
updated_at string

GET /campaigns/{id}

Get a campaign with its totals

ParameterInTypeNotes
id required path string (uuid)
200 Campaign (Campaign)
FieldTypeNotes
id string (uuid)
name string
source_id string (uuid) or null
source_name string or null
status one of: planned, active, ended
starts_on string or null
ends_on string or null
budget number or null
currency string
utm_campaign string or null
external_ref string or null
owner_id string (uuid) or null
owner_name string or null
notes string or null
spend number Total spend so far, in the campaign currency
leads integer Companies this campaign brought in
deals integer
won_value number Value of won deals credited to the campaign (campaign currency)
touchpoints integer
created_at string
updated_at string

PATCH /campaigns/{id}

Update a campaign

ParameterInTypeNotes
id required path string (uuid)
Request body
FieldTypeNotes
name string Up to 200 characters.
source_id string (uuid) or null
status one of: planned, active, ended
starts_on string (date) or null
ends_on string (date) or null
budget number or null Budget in major units 0–1000000000000.
currency string Up to 3 characters.
utm_campaign string or null Matches ?utm_campaign= on pages with your web forms
external_ref string or null ID in another system, e.g. a Klaviyo campaign id Up to 200 characters.
owner_id string (uuid) or null
notes string or null Up to 5000 characters.
200 Updated (Campaign)
FieldTypeNotes
id string (uuid)
name string
source_id string (uuid) or null
source_name string or null
status one of: planned, active, ended
starts_on string or null
ends_on string or null
budget number or null
currency string
utm_campaign string or null
external_ref string or null
owner_id string (uuid) or null
owner_name string or null
notes string or null
spend number Total spend so far, in the campaign currency
leads integer Companies this campaign brought in
deals integer
won_value number Value of won deals credited to the campaign (campaign currency)
touchpoints integer
created_at string
updated_at string

DELETE /campaigns/{id}

Delete a campaign (records it brought in keep their link for reporting)

ParameterInTypeNotes
id required path string (uuid)
204 Deleted

No body.

GET /campaigns/{id}/spend

Spend lines, newest first

ParameterInTypeNotes
id required path string (uuid)
200 Spend
FieldTypeNotes
data array of CampaignSpend
total number

POST /campaigns/{id}/spend

Add spend lines (up to 1000). Lines with an external_ref replace the earlier line with the same ref

ParameterInTypeNotes
id required path string (uuid)
Request body
FieldTypeNotes
lines required array of object
200 Saved
FieldTypeNotes
created integer
updated integer

DELETE /campaigns/{id}/spend/{spend_id}

Remove a spend line

ParameterInTypeNotes
id required path string (uuid)
spend_id required path string (uuid)
204 Removed

No body.

GET /touchpoints

Touchpoints for a campaign, contact or company, newest first

ParameterInTypeNotes
campaign_id query string (uuid)
contact_id query string (uuid)
company_id query string (uuid)
limit query integer Default 50.
offset query integer or null Default 0.
200 Touchpoints
FieldTypeNotes
data array of Touchpoint
total integer

POST /touchpoints

Record touchpoints (up to 500). Identify the person by contact_id or email, or the company by company_id Touchpoints with an external_ref are recorded once per campaign; sending the same ref again is counted as a duplicate. Items whose contact or company cannot be found are skipped and listed in `unmatched` (by position).

Request body
FieldTypeNotes
touchpoints required array of object
200 Recorded
FieldTypeNotes
created integer
duplicates integer
unmatched array of integer

Meetings

GET /meetings

Meetings in a date range (default: the next 30 days), optionally for a company or only yours

ParameterInTypeNotes
from query string (date-time)
to query string (date-time)
company_id query string (uuid)
mine query one of: true, false Default "false".
limit query integer Default 100.
200 Meetings
FieldTypeNotes
data array of Meeting

POST /meetings

Schedule a meeting with colleagues and/or contacts

Request body
FieldTypeNotes
title required string Up to 300 characters.
starts_at required string (date-time)
ends_at required string (date-time)
location string or null Up to 300 characters.
notes string or null Up to 10000 characters.
company_id string (uuid) or null
status one of: scheduled, done, cancelled
outcome string or null Up to 5000 characters.
user_ids array of string (uuid)
contact_ids array of string (uuid)
online_meeting boolean Add a Teams / Google Meet link (needs the organiser's calendar connected)
send_invites boolean Send calendar invitations to attendees from the organiser's calendar
201 Created (Meeting)
FieldTypeNotes
id string (uuid)
title string
location string or null
notes string or null
starts_at string
ends_at string
company_id string (uuid) or null
company_name string or null
organiser_id string (uuid)
status one of: scheduled, done, cancelled
outcome string or null
attendees array of object
online_meeting boolean
join_url string or null Teams or Google Meet link, once synced to the organiser's calendar
external_provider one of: microsoft, google, null
sync_error string or null

GET /meetings/{id}

Get a meeting

ParameterInTypeNotes
id required path string (uuid)
200 Meeting (Meeting)
FieldTypeNotes
id string (uuid)
title string
location string or null
notes string or null
starts_at string
ends_at string
company_id string (uuid) or null
company_name string or null
organiser_id string (uuid)
status one of: scheduled, done, cancelled
outcome string or null
attendees array of object
online_meeting boolean
join_url string or null Teams or Google Meet link, once synced to the organiser's calendar
external_provider one of: microsoft, google, null
sync_error string or null

PATCH /meetings/{id}

Reschedule, edit, cancel or record the outcome of a meeting

ParameterInTypeNotes
id required path string (uuid)
Request body
FieldTypeNotes
title string Up to 300 characters.
starts_at string (date-time)
ends_at string (date-time)
location string or null Up to 300 characters.
notes string or null Up to 10000 characters.
company_id string (uuid) or null
status one of: scheduled, done, cancelled
outcome string or null Up to 5000 characters.
user_ids array of string (uuid)
contact_ids array of string (uuid)
online_meeting boolean Add a Teams / Google Meet link (needs the organiser's calendar connected)
send_invites boolean Send calendar invitations to attendees from the organiser's calendar
200 Updated (Meeting)
FieldTypeNotes
id string (uuid)
title string
location string or null
notes string or null
starts_at string
ends_at string
company_id string (uuid) or null
company_name string or null
organiser_id string (uuid)
status one of: scheduled, done, cancelled
outcome string or null
attendees array of object
online_meeting boolean
join_url string or null Teams or Google Meet link, once synced to the organiser's calendar
external_provider one of: microsoft, google, null
sync_error string or null

Notifications

GET /notifications

My notifications, newest first, with the unread count

ParameterInTypeNotes
limit query integer Default 30.
unread query one of: true, false
200 Notifications
FieldTypeNotes
data array of Notification
unread integer

POST /notifications/read

Mark notifications as read (all of them when no ids are given)

Request body
FieldTypeNotes
ids array of string (uuid)
200 Unread count after the change
FieldTypeNotes
unread integer

Privacy

GET /contacts/{id}/personal-data

Everything held about this person (for a subject access request), as JSON

ParameterInTypeNotes
id required path string (uuid)
200 Personal data (any)

No body.

POST /contacts/{id}/erase

Erase this person (right to erasure): irreversible Removes their name and contact details, their notes, emails and call notes, their files and meeting attendance, and their name or email wherever it appears in other timeline entries. Kept: that a contact existed (shown as "Erased contact") and an audit entry without personal data.

ParameterInTypeNotes
id required path string (uuid)
Request body
FieldTypeNotes
confirm required one of: ERASE
200 Erased
FieldTypeNotes
erased boolean
files_deleted integer

Reports

GET /reports/pipeline

Companies per pipeline stage (legacy "leads by stage" report)

200 Counts by stage, in pipeline order
FieldTypeNotes
data array of object

GET /reports/summary

Pipeline overview: companies by stage, owner and source, leads added per month (12 months), task health

ParameterInTypeNotes
pipeline_id query string (uuid)
200 Summary
FieldTypeNotes
by_stage array of object
by_owner array of object
by_source array of object
added_by_month array of object
tasks object
totals object

GET /reports/marketing

Marketing ROI: spend, leads, pipeline, revenue, CAC, ROI and ROAS by campaign, source or channel (Standard plan)

ParameterInTypeNotes
from query string (date) Start date (inclusive); default 12 months ago
to query string (date) End date (inclusive); default today
group query one of: campaign, source, channel Default "campaign".
model query one of: first, last, linear Attribution model for deals: first touch, last touch or linear Default "first".
campaign_id query string (uuid) Only this campaign
200 Report
FieldTypeNotes
period object
currency string
group one of: campaign, source, channel
model one of: first, last, linear
totals object
rows array of object
by_month array of object
other_currency object

GET /reports/fields

What custom reports can be built from: objects, group-by fields, date fields and measures

200 Catalog
FieldTypeNotes
data array of object

POST /reports/run

Run a report definition without saving it

Request body (ReportDefinition)
FieldTypeNotes
object required one of: company, contact, deal, activity, task, touchpoint, spend
group_by array of string Up to two fields, e.g. ["stage"] or ["created_at:month", "owner"] Default [].
measure string Default "count". Up to 60 characters.
filters array of object Keep records whose field is one of the values (null = not set) Default [].
date object Limit to records whose date field falls in the range (inclusive)
chart one of: table, bar, line Default "bar".
200 Result
FieldTypeNotes
object string
columns object
money boolean
currency string or null
rows array of object
truncated boolean

GET /reports/saved

Your reports and the ones shared with the workspace

200 Reports
FieldTypeNotes
data array of SavedReport

POST /reports/saved

Save a report (admins can share it with the workspace)

Request body
FieldTypeNotes
name required string Up to 80 characters.
definition required ReportDefinition
shared boolean Default false.
201 Saved (SavedReport)
FieldTypeNotes
id string (uuid)
name string
definition ReportDefinition
shared boolean
mine boolean
pinned boolean Pinned to your Home page
owner_name string or null
created_at string
updated_at string

PATCH /reports/saved/{id}

Rename, change or share a saved report

ParameterInTypeNotes
id required path string (uuid)
Request body
FieldTypeNotes
name string Up to 80 characters.
definition ReportDefinition
shared boolean
200 Saved (SavedReport)
FieldTypeNotes
id string (uuid)
name string
definition ReportDefinition
shared boolean
mine boolean
pinned boolean Pinned to your Home page
owner_name string or null
created_at string
updated_at string

DELETE /reports/saved/{id}

Delete a saved report

ParameterInTypeNotes
id required path string (uuid)
204 Deleted

No body.

POST /reports/records

The records behind one row of a report (newest first, up to 100)

Request body
FieldTypeNotes
definition required ReportDefinition
keys required array of string or null
200 Records
FieldTypeNotes
total integer
records array of object

PUT /reports/saved/{id}/pin

Pin a report to your Home page

ParameterInTypeNotes
id required path string (uuid)
204 Done

No body.

DELETE /reports/saved/{id}/pin

Unpin a report from your Home page

ParameterInTypeNotes
id required path string (uuid)
204 Done

No body.

GET /reports/saved/{id}/run

Run a saved report

ParameterInTypeNotes
id required path string (uuid)
200 Result
FieldTypeNotes
object string
columns object
money boolean
currency string or null
rows array of object
truncated boolean
name string

GET /reports/sales

Sales performance for a period: revenue, win rate, cycle, forecast, people, sources, funnel, lost reasons, activity

ParameterInTypeNotes
from query string (date) Start date (inclusive); default 12 months ago
to query string (date) End date (inclusive); default today
owner query one of: me or string (uuid)
200 Report

No body.

Saved views

GET /saved-views

Your saved views and the ones shared with the workspace

ParameterInTypeNotes
object query one of: company, contact, deal
200 Views
FieldTypeNotes
data array of SavedView

POST /saved-views

Save the current list filters as a view (shared views need workspace admin)

Request body
FieldTypeNotes
object required one of: company, contact, deal
name required string Up to 60 characters.
filters required object List filters, e.g. {"kind":"lead","owner":"me"}
shared boolean Default false.
201 Created (SavedView)
FieldTypeNotes
id string (uuid)
object one of: company, contact, deal
name string
filters object List filters, e.g. {"kind":"lead","owner":"me"}
shared boolean
owner_id string (uuid)
owner_name string or null
mine boolean The caller created it (and so can change or delete it)
created_at string

PATCH /saved-views/{id}

Rename a view, update its filters, or share / unshare it

ParameterInTypeNotes
id required path string (uuid)
Request body
FieldTypeNotes
name string Up to 60 characters.
filters object List filters, e.g. {"kind":"lead","owner":"me"}
shared boolean
200 Updated (SavedView)
FieldTypeNotes
id string (uuid)
object one of: company, contact, deal
name string
filters object List filters, e.g. {"kind":"lead","owner":"me"}
shared boolean
owner_id string (uuid)
owner_name string or null
mine boolean The caller created it (and so can change or delete it)
created_at string

DELETE /saved-views/{id}

Delete a view (yours, or a shared one if you are an admin)

ParameterInTypeNotes
id required path string (uuid)
204 Deleted

No body.

GET /recent

Records you viewed recently, newest first

200 Recent
FieldTypeNotes
data array of SearchHit

POST /recent

Record that you opened a record

Request body
FieldTypeNotes
type required one of: company, contact
id required string (uuid)
204 Recorded

No body.

Tasks

GET /tasks

List tasks (call-backs)

ParameterInTypeNotes
limit query integer Default 25.
cursor query string
assignee query one of: me or one of: any or string (uuid) Default "me".
status query one of: open, done, cancelled
target_type query one of: company, contact, deal
target_id query string (uuid)
200 A page of tasks
FieldTypeNotes
data array of Task
next_cursor string or null

POST /tasks

Create a task, optionally on a company or contact

Request body (TaskCreate)
FieldTypeNotes
title required string Up to 300 characters.
notes string Up to 5000 characters.
due_at string (date-time)
remind_at string (date-time)
target_type one of: company, contact, deal
target_id string (uuid)
assignee_id string (uuid)
201 Created (Task)
FieldTypeNotes
id string (uuid)
title string
notes string or null
due_at string or null
remind_at string or null
status one of: open, done, cancelled
target_type one of: company, contact, deal, null
target_id string (uuid) or null
assignee_id string (uuid) or null
created_by string (uuid) or null
completed_at string or null
created_at string

PATCH /tasks/{id}

Update or complete a task

ParameterInTypeNotes
id required path string (uuid)
Request body (TaskUpdate)
FieldTypeNotes
title string Up to 300 characters.
notes string or null Up to 5000 characters.
due_at string (date-time) or null
remind_at string (date-time) or null
status one of: open, done, cancelled
assignee_id string (uuid) or null
200 Updated (Task)
FieldTypeNotes
id string (uuid)
title string
notes string or null
due_at string or null
remind_at string or null
status one of: open, done, cancelled
target_type one of: company, contact, deal, null
target_id string (uuid) or null
assignee_id string (uuid) or null
created_by string (uuid) or null
completed_at string or null
created_at string

Timeline

GET /activities

Timeline for a company or contact, newest first

ParameterInTypeNotes
limit query integer Default 25.
cursor query string
target_type required query one of: company, contact, deal
target_id required query string (uuid)
include_contacts query one of: true, false For a company, also include activity on its contacts Default "true".
200 A page of activities
FieldTypeNotes
data array of Activity
next_cursor string or null

POST /activities

Add a note or log a call outcome

201 Created (Activity)
FieldTypeNotes
id string (uuid)
type one of: note, call, system, email, meeting, task, plugin
subject string or null
body string or null
outcome string or null
target_type string
target_id string (uuid)
actor_type one of: user, agent, app, system
actor_id string (uuid) or null
actor_label string or null
occurred_at string

Workspace

GET /onboarding/workspaces

Workspaces the signed-in person belongs to, so the app can switch the session to one of them

200 Workspaces
FieldTypeNotes
data array of object

POST /onboarding

Create a workspace for the signed-in user (first sign-in). Then switch the session to the returned organisation.

Request body
FieldTypeNotes
workspace_name required string Up to 100 characters.
201 Workspace created
FieldTypeNotes
workspace_id string (uuid)
slug string
organization_id string

GET /me

The signed-in user, workspace and permissions

200 Me (Me)
FieldTypeNotes
user object
workspace object
permissions array of string
actor_type one of: user, agent, app
support object or null

GET /pipeline-stages

Pipeline stages, in order

200 Stages
FieldTypeNotes
data array of PipelineStage

GET /lead-sources

Lead sources

200 Sources
FieldTypeNotes
data array of LeadSource

GET /members

Workspace members (for owner and assignee pickers)

200 Members
FieldTypeNotes
data array of Member