Contacts

Manage workspace contacts and their notes. Contacts are the core record most other resources (deals, payments, bookings, campaigns) attach to.

All endpoints require authentication. There is no DELETE endpoint for contacts on the API.

Consent lives on its own page. A contact's WhatsApp/email marketing consent — the recorded decision, its legal basis, deliverability, and the composed send-time suppression verdict — is read and written through the consent endpoints, documented in Consent & Suppressions.

The contact object

Responses return the full contact record plus computed fields:

• tags — array of tag ids (strings)
• groups — array of group ids
• event_attendances — [{id, event_id, status, registered_at, attended_at, unregistered_at}]
• whatsapp_subscribed, email_subscribed (booleans), whatsapp_deliverability, email_deliverability — per-channel consent state (contacts without a subscription record report false / "unknown")
• national_id — normalized national ID, or null.
• owner_user_id and owner — the owning member id and { id, name, email }, or null when unowned.
• first_touch and last_touch — the contact's first and most recent acquisition, each the same object shape as a row from GET /api/v1/contacts/:id/acquisitions, or null when the contact has no recorded touch. Present only on plans with Attribution — without it the two keys are absent entirely, which is how you tell "not entitled" from "no touches yet".
• score_band — read-only lead-scoring band: "cold", "warm", "hot", or null

Round-trip warning — tags/groups are NAMES on input, IDS on output. POST/PATCH accept tag and group names; GET returns ids. Never echo the ids from a GET back into a write: unrecognized names are auto-created, so a UUID sent as a "name" creates a brand-new tag literally named like that UUID. Map ids back to names first (see Tags & Contact Groups).

GET /api/v1/contacts

Standard list conventions apply (filter, sort, limit default 50 / cap 500, offset, search).

search matches name, first_name, last_name, email, phone, company_name (case-insensitive substring), plus an exact match on the E.164-normalized form of the term and the contact's historical phone/email identifiers.

curl -G "https://app.otok.io/api/v1/contacts" \
  -H "Authorization: Bearer otok_live_abc123..." \
  --data-urlencode 'filter={"lifecycle_stage":"customer"}' \
  --data-urlencode 'sort=-updated_at' \
  --data-urlencode 'limit=25'

Response 200 — { data, total, limit, offset }.

GET /api/v1/contacts/:id

Response 200 — a single contact object (same enrichment as list).

POST /api/v1/contacts — upsert

Creates a contact, or updates the existing contact that the given phone/email resolves to. This is the recommended way to write contacts from external systems — including changing a contact’s phone or email.

Request body

Every field is optional. Unknown fields → 400.

Changing a contact's owner also transfers eligible live records held by the previous owner, including open deals, tasks and inquiries, draft/sent quotes, and upcoming bookings.

An impossible incoming phone does not replace an existing valid phone. Send an empty string to explicitly clear it; inspect the returned phone after writing.

Marketing metadata

The following native fields appear in the contact's Marketing section. They are optional strings accepted by both POST /api/v1/contacts and PATCH /api/v1/contacts/:id, and returned with contact records (nullable when unset). Supply them as top-level properties, alongside the UTM fields.

Example request body:

{
  "email": "jane@example.com",
  "source_page_url": "https://example.com/signup",
  "source_page_title": "Newsletter signup",
  "referrer": "https://example.com/blog",
  "user_agent": "Mozilla/5.0",
  "affiliate": "partner-123"
}

Acquisition events and inquiry capture (POST only)

Use acquisition for an actual submission, including a returning contact submitting a new form. It is a request option, not a stored contact profile field.

The event's source values take precedence over corresponding top-level fields. Top-level marketing fields alone create acquisition context only when a contact is first created; ordinary profile updates do not add another acquisition event. Capture is best-effort: a successful profile write does not guarantee that attribution was recorded.

The top-level inquiry option controls the inquiry queue:

With acquisition.event_id, both the touch and its inquiry are deduplicated on that id across the whole workspace — so a retry that resolves to a different contact (an identifier that turned out to belong to someone else) still records one touch, not two. Send the same event id when retrying.

Example body (all values are illustrative):

{
  "email": "jane@example.com",
  "acquisition": {
    "event_id": "signup-example-001",
    "landing_url": "https://example.com/signup",
    "utm_source": "newsletter",
    "utm_campaign": "autumn-course",
    "form_name": "Course interest"
  }
}

Both acquisition and inquiry are rejected on PATCH with 400. PATCH is a profile edit and never opens an inquiry.

Upsert resolution

1. phone, email, and national_id are normalized.
2. The API looks up the current owner of each identifier — resolution is history-aware: a phone/email that was moved off a contact still resolves to its most recent holder if no current owner exists.
3. Matching precedence is phone → email → national ID. Split matches follow the rules below. Always use the contact id returned by the API.
4. Match found → update: scalar fields overwrite, custom_fields shallow-merge, and tags/groups are added to the existing set (never removed by this route).
5. No match → create. Concurrent creates of the same identity are safe — the loser of the race is retried as an update of the winner.

The response is 201 in both cases (create and update) with the full contact object, plus a top-level boolean duplicate field: false when this request created the contact, true when it matched and updated an existing one.

Identity conflict — 409 CONTACT_MERGE_REQUIRED

When incoming identifiers resolve to different current contacts, POST can automatically merge complementary records: every non-empty phone, email and national ID must agree across the records and the incoming payload. Blanks can be filled. A phone-only record and a compatible email-only record can therefore become one contact; the response returns the surviving id with duplicate: true.

Conflicting identifiers, historical split matches, and pairs awaiting or preserving a human review decision still require in-app resolution. In that case the API opens a merge request and responds:

{
  "statusCode": 409,
  "error": "Conflict",
  "error_code": "CONTACT_MERGE_REQUIRED",
  "merge_request_id": "3a2b1c0d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
  "message": "The provided identifiers belong to different existing contacts. A merge request has been opened — resolve it in the app, then retry."
}

The non-identity fields of your request are parked with the merge request and applied when it is resolved. Retry after the merge request is resolved in the app. Repeated conflicting requests for the same pair reuse the same merge request.

Retrying after "Keep separate". When someone resolves the conflict in the app by keeping the contacts separate and choosing which one the submission belongs to, your retry of the same submission is applied to that chosen contact (201, duplicate: true) instead of opening another merge request. None of the submitted identifiers are moved onto it — the phone, email and national ID stay with the contacts that hold them — but the rest of the request (fields, tags, groups, acquisition, inquiry) lands on the chosen contact. If the identifiers point at contacts for which no such choice was made, the request still answers 409 CONTACT_MERGE_REQUIRED.

Example

curl -X POST "https://app.otok.io/api/v1/contacts" \
  -H "Authorization: Bearer otok_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+972501234567",
    "email": "dana@example.com",
    "first_name": "Dana",
    "last_name": "Levi",
    "lifecycle_stage": "lead",
    "tags": ["VIP", "Newsletter"],
    "custom_fields": { "plan_interest": "pro" }
  }'

Response 201:

{
  "id": "9c2f1a4e-3b7d-4e2a-9f0c-1d2e3f4a5b6c",
  "phone": "+972501234567",
  "email": "dana@example.com",
  "name": "Dana Levi",
  "first_name": "Dana",
  "last_name": "Levi",
  "lifecycle_stage": "lead",
  "tags": ["b1a2c3d4-0000-0000-0000-000000000001", "b1a2c3d4-0000-0000-0000-000000000002"],
  "groups": [],
  "custom_fields": { "plan_interest": "pro" },
  "whatsapp_subscribed": true,
  "email_subscribed": false,
  "score_band": null,
  "duplicate": false,
  "created_at": "2026-07-14T10:00:00.000Z",
  "updated_at": "2026-07-14T10:00:00.000Z"
}

Errors

Side effects

Creating or updating a contact via the API behaves like an in-app write: per-channel consent records are seeded (WhatsApp implied; email unknown when an email is provided, both attributed to source api), contact-change automations (tag/group/field triggers) fire, activity history is recorded, and connected integrations sync. block_state set to a non-none value without a blacklist match is recorded with an import block source.

PATCH /api/v1/contacts/:id

Update a contact by id. Same field set and validation as POST (all optional).

Semantics that differ from POST:

• tags/groups REPLACE the full set. The contact ends up with exactly the names you send; an empty array clears all tags/groups. (On POST they are additive.) Names still auto-create.
• custom_fields still shallow-merge — you cannot remove a key by omitting it; set it to null explicitly.
• name and first_name/last_name stay in sync: patching only first_name recombines it with the stored last_name; patching only name re-splits it on the first whitespace.
• block_state changes route through the consent/blocking subsystem; lifting a block re-evaluates blacklist rules, and global blocks cannot be lifted via the API.

Identity conflict — 409 CONTACT_MERGE_REQUIRED (PATCH)

Setting phone/email/national_id to an identifier that belongs to a different contact does not apply the write. Like the POST upsert's conflict path, the API opens a merge request for the workspace to resolve in-app and responds:

{
  "statusCode": 409,
  "error": "Conflict",
  "error_code": "CONTACT_MERGE_REQUIRED",
  "merge_request_id": "3a2b1c0d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
  "message": "This change would give the contact a phone or email that already belongs to another contact. A merge request was opened — resolve it (merge or dismiss) to apply the change."
}

The non-identity fields sent in the same PATCH are held on the merge request and applied when it is resolved (merge or dismiss).

The conflict check is history-aware. A PATCH that sets a phone/email no contact currently holds but that another contact previously held also parks a merge request and returns this 409 — matching the in-app editor's behavior.

curl -X PATCH "https://app.otok.io/api/v1/contacts/9c2f1a4e-3b7d-4e2a-9f0c-1d2e3f4a5b6c" \
  -H "Authorization: Bearer otok_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{ "lifecycle_stage": "customer", "tags": ["VIP"] }'

Response 200 — the updated contact object.

GET /api/v1/contacts/:id/acquisitions

Read-only listing of one contact's acquisition touches — the per-submission record behind the in-app Journey, newest first. One row per submission, never a rollup: use it to answer "how did this person actually reach us, and how many times".

Plan feature required: this endpoint requires the Attribution feature on the workspace's plan. Without it, calls return 403 with error_code: "FEATURE_NOT_INCLUDED_IN_PLAN" — see feature-gated resource groups. The same gate hides the first_touch / last_touch blocks on the contact object.

curl "https://app.otok.io/api/v1/contacts/9c2f1a4e-3b7d-4e2a-9f0c-1d2e3f4a5b6c/acquisitions?kind=api&limit=20" \
  -H "Authorization: Bearer otok_live_abc123..."

Response 200 — { data, total, limit, offset }, ordered by occurred_at descending:

{
  "data": [
    {
      "id": "b1d9c0f2-5a3e-4c18-9f77-2e6a8d4b0c31",
      "event_id": "signup-example-001",
      "kind": "api",
      "source": "form",
      "occurred_at": "2026-09-14T08:31:00.000Z",
      "visitor_id": "v_8fa31c2b9d40",
      "form_name": "Course interest",
      "landing_url": "https://example.com/autumn",
      "conversion_url": "https://example.com/autumn/signup",
      "landing_referrer": "https://www.google.com/",
      "referrer_url": "https://www.google.com/",
      "source_page_title": "Autumn course",
      "utm_source": "newsletter",
      "utm_medium": "email",
      "utm_campaign": "autumn-course",
      "utm_term": null,
      "utm_content": null,
      "gclid": null,
      "gbraid": null,
      "wbraid": null,
      "fbclid": null,
      "msclkid": null,
      "ttclid": null,
      "li_fat_id": null,
      "ctwa_clid": null,
      "platform_campaign_id": null,
      "params": { "plan": "pro" },
      "user_agent": "Mozilla/5.0 …",
      "ip": "203.0.113.9",
      "attendance_id": null,
      "form_id": null,
      "landing_page_id": null,
      "campaign_id": null,
      "email_campaign_id": null,
      "created_at": "2026-09-14T08:31:00.412Z"
    }
  ],
  "total": 3,
  "limit": 20,
  "offset": 0
}

Reading a row.

• kind is the transport oToK observed (api for anything sent through this API). source is what the caller declared produced it. They answer different questions and are never mapped onto one another.
• landing_url is the first page of the session; conversion_url is the page that submitted. Embedded forms currently report the submitting page for both.
• params holds the raw query parameters the producer kept, minus the canonical UTM and click-id keys. It is readable here and nowhere else — not in exports, not on webhooks.
• ip and user_agent are the visitor's, exactly as the producer stated them, and are kept for the life of the touch.
• event_id is the producer's own submission id (workspace-unique for API touches). attendance_id links the touch to the event registration it produced, when there is one.
• The row carries no channel classification: that lives on the contact's first_touch_channel / last_touch_channel rollups.

GET /api/v1/contacts/:id/documents

Read-only listing of a contact's financial documents — invoices, receipts, and credit documents — aggregated from every stored document pointer on the contact's payments, payment entries, and payment requests, deduplicated, merged, and sorted date-descending (nulls last).

Plan feature required: unlike the rest of the contacts routes, this endpoint requires the Payments feature on the workspace's plan (the same gate as /v1/payments*). Without it, calls return 403 with error_code: "FEATURE_NOT_INCLUDED_IN_PLAN" — see feature-gated resource groups.

curl "https://app.otok.io/api/v1/contacts/9c2f1a4e-3b7d-4e2a-9f0c-1d2e3f4a5b6c/documents?live=true" \
  -H "Authorization: Bearer otok_live_abc123..."

Response 200:

{
  "documents": [
    {
      "key": "sumit:123456",
      "kind": "tax_invoice_receipt",
      "rawType": null,
      "isCredit": false,
      "provider": "sumit",
      "documentId": "123456",
      "number": "2043",
      "url": "https://app.sumit.co.il/…/document.pdf",
      "date": "2026-07-14T10:00:00.000Z",
      "amount": 350,
      "currency": "ILS",
      "origin": "merged",
      "sources": [
        { "type": "contact_payment", "id": "7b6a5c4d-…" },
        { "type": "provider", "provider": "sumit" }
      ]
    }
  ],
  "live": { "attempted": true, "ok": true, "complete": true, "error": null }
}

Document fields:

The live object reports the provider lookup: attempted (a live lookup ran), ok (false = it failed or timed out), complete (false = the live listing may be missing documents), error ("timeout", "provider_error", or null). With the default live=false, attempted is false and the listing is stored-only.

Saved cards and charges

A contact's saved cards are cards the payer agreed to keep on file — at checkout on a pay-link, or entered in the app — stored at the workspace's connected payment provider (Cardcom / Sumit). Through the API you can list them (masked) and charge one directly, without sending a pay-link. Card numbers never pass through the API: a stored card is charged by reference.

Plan feature required: both routes require the Workspace payments feature (workspace_payments) — the payment requests gate, not the payments ledger gate — and answer 403 FEATURE_NOT_INCLUDED_IN_PLAN without it.

GET /api/v1/contacts/:id/payment-methods

curl "https://app.otok.io/api/v1/contacts/9c2f1a4e-3b7d-4e2a-9f0c-1d2e3f4a5b6c/payment-methods" \
  -H "Authorization: Bearer otok_live_abc123..."

Response 200 — { payment_methods }, newest first:

{
  "payment_methods": [
    {
      "id": "5d6e7f80-9a1b-4c2d-8e3f-405162738495",
      "provider": "cardcom",
      "brand": "visa",
      "last4": "4242",
      "expiryMonth": 12,
      "expiryYear": 2028,
      "tokenExpiresAt": null,
      "status": "active",
      "isDefault": true,
      "consentSource": "checkout_optin",
      "consentedAt": "2026-07-14T10:00:00.000Z",
      "lastUsedAt": "2026-08-01T08:00:00.000Z",
      "createdAt": "2026-07-14T10:00:00.000Z"
    }
  ]
}

Unlike most API objects, saved-card fields are camelCase.

POST /api/v1/contacts/:id/charges

Charges one of the contact's saved cards through the connected payment provider — the same charge as the in-app Charge saved card button. The result is a payment request with charge_kind: "token" (no pay-link), recorded on the contact's payments ledger once paid, with the tax document auto-issued when configured.

Saved-card charge access (API key capability). This route requires the calling API key to carry saved-card charge access (allow_charges). It is off by default on every key; only the workspace owner can grant it, in Settings → Developers → API keys. A key without it gets 403 with error_code: "API_KEY_CHARGES_DISABLED" — checked before anything else, including the contact lookup.

Request body

Card fields of any kind are refused (unknown properties are rejected).

curl -X POST "https://app.otok.io/api/v1/contacts/9c2f1a4e-3b7d-4e2a-9f0c-1d2e3f4a5b6c/charges" \
  -H "Authorization: Bearer otok_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "idempotency_key": "plan-renewal-2026-08",
    "amount": 250,
    "title": "August membership",
    "method_selection": "default"
  }'

Outcomes

Charge idempotency

idempotency_key is required. Keys are scoped to the API key that sent them: a replay of the same key answers the original charge's outcome with duplicate: true and never charges twice — a paid charge replays 200, one still processing replays 202. Reusing a key with a different contact, amount or currency answers 409 IDEMPOTENCY_KEY_MISMATCH and charges nothing. A new charge attempt — for example after a decline — needs a new key.

Errors

A charge fires no payment_request.* webhooks (direct saved-card charges never do); a paid charge appears on the payments ledger and fires the payment-recorded automations like any other payment.

Notes

Notes are plain-text annotations on a contact. API note payloads are text only (rich-text and mentions are in-app features; sending them returns 400). Notes created via the API have no author user and are attributed to source api.

Note object:

{
  "id": "5e4d3c2b-...",
  "workspace_id": "...",
  "contact_id": "9c2f1a4e-...",
  "author_user_id": null,
  "author_name": null,
  "source": "api",
  "body": "Asked for a demo next week",
  "body_json": null,
  "mentioned_user_ids": null,
  "pinned_at": null,
  "conversation_id": null,
  "created_at": "2026-07-14T10:05:00.000Z",
  "updated_at": "2026-07-14T10:05:00.000Z"
}

(author_name is included on list responses only.)

GET /api/v1/contacts/:id/notes

Returns a JSON array of all the contact's notes — this endpoint is not paginated and takes no query parameters. Pinned notes come first (most recently pinned on top), then the rest newest-first.

POST /api/v1/contacts/:id/notes

curl -X POST "https://app.otok.io/api/v1/contacts/9c2f1a4e-3b7d-4e2a-9f0c-1d2e3f4a5b6c/notes" \
  -H "Authorization: Bearer otok_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{ "body": "Asked for a demo next week", "pinned": true }'

Response 201 — the created note.

PATCH /api/v1/notes/:id

Both fields are optional; sending neither returns the current note unchanged. A body change bumps updated_at (shows as "edited" in-app); a pin toggle alone does not. If the note is the contact's profile note, a body edit also updates the contact's notes field (and fires the corresponding field-change automations).

Response 200 — the note after the update.

DELETE /api/v1/notes/:id

Response 200:

{ "success": true }

Deleting the contact's profile note also clears the contact's notes field. A deletion breadcrumb is kept in the contact's activity timeline.