oToK REST API (1.6.0)

Send a workspace API key as a bearer token on every request:

Authorization: Bearer otok_live_...

Keys are created in Settings → Developers in the oToK app and are shown exactly once. A revoked key is indistinguishable from an unknown key — both return 401 "Invalid API key". The REST API requires a plan with API access (Growth or higher); other plans receive 403.

Endpoint groups that mirror a plan-gated product area additionally require that feature on the workspace's plan — deals/pipelines (deals), payments and contact documents (payments), payment requests (workspace_payments), orders (orders), campaigns (campaigns), email campaigns (email_marketing), newsletters (newsletters), bookings/meeting-types (booking). Every route in a gated group answers 403 with error_code: "FEATURE_NOT_INCLUDED_IN_PLAN" (a body without a statusCode field) when the plan lacks the feature. Note the two distinct payment gates: /v1/payments* and GET /v1/contacts/{id}/documents require the payments feature (the payments ledger), while /v1/payment-requests* requires workspace_payments (collecting money through the workspace's own connected payment provider) — a workspace can hold either feature without the other, and the 403 message embeds whichever feature id is missing. The suppression list (/v1/suppressions*) and the sender-profile listing (GET /v1/sender-profiles) require the email_marketing feature. Contacts (including consent), notes, tags, contact groups, templates, products, audiences, emails, and webhook endpoints require only plan-wide API access.

The API uses two error body shapes:

1. Domain errors (email, email-campaign, newsletter, webhook-endpoint, consent, suppression, and product APIs, and POST /v1/campaigns/{id}/execute failures) use a structured envelope: {"error": {"code", "message"}} — key on error.code.
2. Framework errors (validation, auth, rate limiting, most resource errors) use {"statusCode", "message", "error"}, where message is a string or an array of per-field validation messages. Some 4xx responses extend this shape with a machine-readable error_code field (deals, payments, orders, bookings, contacts).

Request bodies are strictly validated: unknown body properties are rejected with 400. Path :id parameters must be UUIDs; a non-UUID id returns 400 (except DELETE /v1/webhook-endpoints/{id}, which returns 404).

The API never deletes customer data — contacts, deals, products, payments, orders, campaigns, tags, and contact groups have no DELETE routes (deactivate a product with is_active: false instead). The only DELETE endpoints are for resources the API owns: DELETE /v1/notes/{id}, DELETE /v1/webhook-endpoints/{id}, DELETE /v1/suppressions/{id} (which lifts a send-time block — it deletes no contact data and resubscribes no one), and DELETE /v1/newsletter-issues/{id} (drafts and scheduled issues only — published issues are never deletable).

Exceeding a limit returns HTTP 429 with a Retry-After header. The per-key bucket is shared across all source IPs using that key.

Most list endpoints return { "data", "total", "limit", "offset" } with limit default 50 (hard cap 500). GET /v1/deals, GET /v1/payments, GET /v1/payment-requests, GET /v1/orders, and the email-campaign/newsletter/audience/sender-profile lists use dedicated query parameters with limit default 25 (cap 100); absent or empty limit/offset values default. On deals, payments, payment requests, and the email-campaign/newsletter/audience/sender-profile lists, malformed values return 400 ("Invalid limit: must be a non-negative integer"); on orders, paging never returns 400 — malformed or zero values silently default and out-of-range values are clamped. Unrecognized enum filter values on deals/payments/orders are silently ignored; GET /v1/payment-requests, GET /v1/email-campaigns, and GET /v1/newsletters/{id}/issues instead reject an unknown status with 400 (as does GET /v1/audiences for an unknown kind).

• Contacts upsert by phone/email.
• Deals, payments, and orders upsert by external_reference; products upsert by external_id.
• Email campaigns and newsletter issues upsert by external_reference — a replay updates content/fields while the record is still editable and never touches status, scheduled_at, or an issue's number.
• Suppression adds are idempotent per address (re-adding answers duplicate: true).
• Order refunds are idempotent per external_refund_id — only when you supply one.
• Emails require an explicit idempotency_key.
• Booking creation is idempotent per slot + meeting type + contact (server-derived, no key).
• Payment requests have NO idempotency key — POST /v1/payment-requests is not idempotent: a repeat POST mints a second, independently payable link. Cancel extras with POST /v1/payment-requests/{id}/cancel.

Idempotent create responses carry a top-level boolean duplicate field — false on a fresh create, true when the call matched an existing record — with one exception: POST /v1/orders returns the same full order body for both outcomes and no duplicate marker (compare created_at, or pre-check with GET /v1/orders?external_reference=...); the order refund endpoint does return { "duplicate", "order" }. Status codes are 201 for both outcomes everywhere except POST /v1/emails, which answers 201 fresh / 200 replay.

• New Email campaigns resource group (/v1/email-campaigns*) — author, estimate, launch, and schedule broadcast email campaigns: idempotent create via external_reference, PATCH while draft/scheduled, GET …/estimate through the send path's audience resolver, and send/schedule/unschedule riding the exact in-app launch gates. Requires the email_marketing plan feature. A/B testing is deliberately not exposed — create A/B campaigns in-app.
• New Newsletters resource group (/v1/newsletters* + /v1/newsletter-issues*) — list/create newsletters (rows carry active subscriber counts) and author their issues: idempotent issue create via external_reference, publish/schedule/unschedule with publish-time issue numbering, and deletion for never-published issues. Requires the newsletters plan feature.
• Shared content authoring contract on both new surfaces: exactly one of markdown (CommonMark subset + ::button[Label](https://url) / ::snippet[name-or-uuid] directives + [[…]] personalization tokens), typed blocks, or a raw design_json document — compiled at write time, with the result reported in the response's compile: {ok, errors, warnings} envelope.
• Two new read-only targeting-selector discovery endpoints: GET /v1/audiences lists the saved audiences campaigns accept as audience_id (rows carry the summary columns and advisory size cache — never the stored definition), and GET /v1/sender-profiles lists the email from-identities email campaigns accept as sender_profile_id, each with a verified send-readiness signal (requires the email_marketing plan feature; audiences need only plan-wide API access). Neither resource is writable through the public API.

• New GET /v1/meeting-types/{id}/embed — website-embed material for a meeting type: the hosted booking page URL, the workspace's publishable embed key (bk_…, safe in page HTML — not the secret API key), and a ready-to-paste snippet. Requires the booking plan feature.

• New consent endpoints on contacts: GET /v1/contacts/{id}/consent reads both channels' stored consent decision + provider-owned deliverability (email adds the composed send-time suppressed verdict), and PUT /v1/contacts/{id}/consent/{channel} records a subscribed/unsubscribed decision with its provenance (evidence trail included; a channel with a spam complaint on record answers 409 consent_sticky_complained).
• New Suppressions resource group (/v1/suppressions*) — list, idempotently add, and remove workspace email-suppression rows. Requires the email_marketing plan feature. Suppression and consent deliberately compose at send time: adding a suppression does not change consent, and removing one resubscribes no one.
• New Products resource group (/v1/products*) — the workspace product catalog shared by deals and payments: list/get/create/update with an idempotent POST upsert via external_id and no DELETE (deactivate with is_active: false).
• Fifteen new webhook event types across six opt-in families, riding the existing endpoint registry, signing, and retry policy: contact lifecycle + consent (contact.created, contact.updated, contact.deleted, contact.consent_changed), inbound messages (message.received), deal lifecycle (deal.created, deal.stage_changed, deal.won, deal.lost), booking lifecycle (booking.created, booking.rescheduled, booking.cancelled, booking.reassigned), event attendance (event.attendance.changed), and form submissions (form.submitted). All are opt-in by listing — the default subscription is unchanged, and a pre-existing endpoint never starts receiving a new family unasked.

• New Payment requests resource group (/v1/payment-requests*) — hosted pay-links collected through the workspace's own connected payment provider (Cardcom / Sumit) — and the four payment_request.* webhook event types (opt-in by listing, like the order events). Gated by the workspace_payments plan feature (distinct from the payments ledger gate).
• New GET /v1/contacts/{id}/documents — read-only listing of a contact's financial documents (invoices, receipts, credit documents), with an opt-in ?live=true provider lookup. Gated by the payments feature.
• Payments: POST /v1/payments and PATCH /v1/payments/{id} accept a vat_mode + vat_rate pair (recurring plans only, always together) and a free-form metadata object (≤ 2048 bytes serialized; replace-on-write, null clears on PATCH). Payment and payment-entry response fields are now fully documented, including the recurring auto-charging/dunning fields, the stored VAT pair, and entry-level refund/credit-document fields.

• New Orders resource group (/v1/orders*) and the five order.* webhook event types.
• Schema correction for existing consumers: deal and payment response money — Deal.amount, Payment.total_amount, and payment entry amount/recognized_amount — is now typed as a JSON number. Spec versions up to 1.1.0 incorrectly documented these response fields as decimal strings (e.g. "3600.00"); the API has always returned JSON numbers (e.g. 3600), so nothing changed on the wire — but clients generated from the earlier schema will see these declared types change from string to number on regeneration.

Contact upsert & update, plus the merge-conflict contract. There is no DELETE endpoint for contacts.

Plain-text notes on a contact. API note payloads are text only.

Tag CRUD (no delete). Names are unique per workspace (case-insensitive).

Contact group CRUD (no delete). Names are unique per workspace (case-insensitive).