Authentication and conventions

Base URL

https://app.smartcontact.online/v1. All requests and responses are JSON over HTTPS. The full description is at /openapi.json (OpenAPI 3.1).

Authentication

Send a bearer token in the Authorization header:

Authorization: Bearer sc_ab12cd34.xxxxxxxxxxxxxxxxxxxxxxxx

API keys are created by workspace admins in Settings › API keys. Each key has a name, a type and a role, and can expire. The secret is shown once and stored only as a hash. Revoke a key at any time.
Integration keys are for your own systems. AI agent keys are for assistants, either read only or read & write.
AI assistants that support MCP can also sign in with OAuth instead of using a key.

Roles and permissions

A key acts as a workspace member with the role you give it, and sees only what that role allows. A request without the right permission gets 403. Keys can never have the Owner or Admin role.

AI agents have extra limits whatever their role: they never delete records, bulk-change records, export, or change settings, and everything they do is labelled as theirs.

Errors

Errors use a single shape:

{ "error": { "code": "validation_failed", "message": "name: Required" } }

Status	Code examples	Meaning
400	`validation_failed`, `invalid_cursor`	The request is malformed; the message names the field.
401	`unauthenticated`	Missing, invalid, expired or revoked key.
402	`plan_required`, `plan_limit`	A Standard-plan feature, or a Basic plan limit (users, companies, storage).
403	`forbidden`, `agent_forbidden`	The key's role, or the agent rules, don't allow it.
404	`not_found`	No such record in this workspace.
409	`duplicate`	A unique value (e.g. a campaign name) is already taken.
422	`invalid_reference`, `constraint_failed`	A referenced record doesn't exist, or a value isn't allowed.

Paging

Most lists return { "data": [...], "next_cursor": "…" }, newest first. Pass ?cursor= with the previous next_cursor until it is null. limit is up to 50.
Some lists (companies with offset, deals, campaigns, touchpoints) page by offset and return a total.

Dates, money and custom fields

Dates and times are ISO 8601. Date-only fields are YYYY-MM-DD; timestamps are UTC.
Money is in major units with a three-letter currency, e.g. "value": 1250.5, "currency": "GBP". Reports total money in the workspace currency only.
Custom fields live in each record's custom object, keyed by the field's key. Writing merges keys; null removes one. Values are validated against the field's type.
Idempotency: campaign spend and touchpoints with an external_ref are recorded once; re-sending updates or skips them.

Plans

Campaigns, Marketing ROI and the report builder are Standard-plan features. On Basic they answer 402 plan_required. Everything else in the API works on both plans, within Basic's limits.

Timeline and audit

Every write adds an entry to the record's timeline and to the workspace audit log, attributed to the key or agent that made it. Admins can see and export both.