oToK REST API (1.10.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), sales (sales), campaigns (campaigns), email campaigns (email_marketing), newsletters (newsletters), bookings/meeting-types (booking), customer tickets (customer_tickets). 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*) requires the email_marketing feature. Contacts (including consent), notes, tags, contact groups, templates, products, audiences, product cycles, shared report listing, emails, sender profiles, and webhook endpoints require only plan-wide API access. Report runs additionally check the dataset feature.

The API uses two error body shapes:

1. Domain errors (email, email-campaign, newsletter, webhook-endpoint, consent, suppression, product, and ticket 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 manual_status: "archived" 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). DELETE /v1/sales/{id} (an unfunded, unlinked sale) and DELETE /v1/sales/{id}/allocations/{allocationId} additionally need the Allow permanent deletion through the API key capability (allow_hard_delete), granted per key by the workspace owner — 403 HARD_DELETE_OWNER_ONLY otherwise.

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/sales, 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.
• Sales are idempotent by external_reference — a replay writes nothing and returns the original sale with duplicate: true. Sale refunds are idempotent per idempotency_key — only when you supply one.
• 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).
• Tickets open idempotently by external_reference (a replay changes nothing and answers the original ticket); ticket replies are idempotent per idempotency_key. Both answer 201 fresh / 200 replay.
• 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, POST /v1/tickets, and POST /v1/tickets/{id}/replies, which answer 201 fresh / 200 replay.

• New Sales resource group (/v1/sales*): record sales with line items, link payments to them, cancel, reinstate, refund, reassign the owner and link a deal. Gated by the sales plan feature; refunds need an API key with refund access.
• New Tickets resource group (/v1/tickets*): open, read, answer and triage customer tickets. Gated by the customer_tickets plan feature.
• Saved cards: GET /v1/contacts/{id}/payment-methods and POST /v1/contacts/{id}/charges (requires an API key with the charges capability; idempotency_key required).
• Payment requests: POST /v1/payment-requests/{id}/send-link, /document and /refund; product_id, sale_id and an optional idempotency_key on create.
• POST /v1/payments/{id}/refund now takes a required reason and mode and returns the refund result (payment, entry, outcome, duplicate).
• Orders and payments take an optional sale_id.
• Events: collect_payment_on_registration, and registrations carry a payment block. Bookings carry a deposit block.
• Products and product cycles: dynamic_pricing, recurring_sale_policy and rearm_date_triggers.
• New opt-in webhook events: payment.refunded, sale.recorded, sale.paid, sale.refunded and ticket.*.
• GET /v1/sender-profiles no longer needs a plan feature.

• Events: event_type_id and event_type_name on POST /v1/events link the event to a saved event — a reusable event definition managed in the oToK app (Events → Saved events). Resolve-only: the API never creates a saved event. An unknown id or name answers 400 event_type_not_found; an id and a name that disagree answer 400 event_type_mismatch. The event object carries event_type_id and an event_type block ({id, name}, or null), and GET /v1/events filters on event_type_id.

• New Events resource group (/v1/events*, PATCH /v1/attendances/{id}) — events and their registrations. A registration made here fires exactly what an in-app one fires: the event automations, the event.attendance.changed webhook, lead scoring, and the Zoom registrant push that produces the attendee's personal join link. Gated by the events plan feature.
• New GET /v1/contacts/{id}/acquisitions — the per-submission record behind the in-app Journey, newest first. Gated by the attribution plan feature.
• Contacts: first_touch and last_touch on the contact object — the contact's first and most recent acquisition, in the same shape as an acquisitions row, or null. Both keys are absent (not null) without the attribution feature.
• Schema correction for existing consumers: the event.attendance.changed webhook's status and previous_status were documented as registered | attending | attended | no_show | cancelled. The values the API has always emitted are registered | attended | no_show | waitlist | unregistered: attending never existed, cancelled is accepted only as a write-time alias for unregistered, and waitlist / unregistered were missing. Nothing changed on the wire — but a consumer branching on the documented spelling was never matching those two states.

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

Product cohorts, runs and versions.

Discover and run shared saved reports.

Events and their registrations.

Event registrations, moved by id.

A contact's per-submission acquisition record.

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