Deals & Pipelines

Manage sales deals on your workspace's pipelines. A deal belongs to exactly one contact and one pipeline stage, and carries an open / won / lost status that is separate from its stage — closing a deal stamps closed_at and keeps its last stage.

All endpoints require authentication. Deals cannot be deleted via the API.

Plan feature required: every route on this page (including GET /v1/pipelines) requires the Deals feature on the workspace's plan, in addition to API access. Without it, all calls return 403 with error_code: "FEATURE_NOT_INCLUDED_IN_PLAN" — see feature-gated resource groups.

GET /api/v1/pipelines

Returns a JSON array (no pagination envelope) of the workspace's pipelines, ordered by position, each with its ordered stages. Use this to map stage ids before creating or moving deals.

curl "https://app.otok.io/api/v1/pipelines" \
  -H "Authorization: Bearer otok_live_abc123..."

[
  {
    "id": "aa11bb22-3344-5566-7788-99aabbccddee",
    "workspace_id": "…",
    "name": "Sales",
    "description": null,
    "is_default": true,
    "position": 0,
    "created_by": "…",
    "created_at": "2026-01-05T09:00:00.000Z",
    "updated_at": "2026-01-05T09:00:00.000Z",
    "stages": [
      { "id": "st-1111…", "pipeline_id": "aa11bb22-…", "name": "New", "color": "#3b82f6", "position": 0, "win_probability": 10, "created_at": "…", "updated_at": "…" },
      { "id": "st-2222…", "pipeline_id": "aa11bb22-…", "name": "Negotiation", "color": "#f59e0b", "position": 1, "win_probability": 60, "created_at": "…", "updated_at": "…" }
    ]
  }
]

Exactly one pipeline per workspace has is_default: true. A stage's win_probability is an integer 0–100 (null behaves as 100%) used for forecasting.

The deal object

Deal responses include all deal fields — id, workspace_id, pipeline_id, stage_id, contact_id, product_id, owner_user_id, title, amount, currency, status, lost_reason, expected_close_at, closed_at, stage_entered_at, position, note, external_reference, source, created_by, created_at, updated_at.

GET /v1/deals, GET /v1/deals/:id, POST /v1/deals, and PATCH /v1/deals/:id additionally join the contact's identity: contact_name, contact_phone, contact_email. The /stage and /status action routes return the bare deal row without these joined fields.

amount serializes as a JSON number rounded to 2 decimals (e.g. 3600), in both requests and responses. (Earlier revisions of this page showed a decimal string "3600.00" in the response example — that was a documentation error; the API has always returned a number.)

GET /api/v1/deals

This route uses dedicated query parameters (not the generic filter), and its own pagination defaults — see where deals and payments differ.

Results are ordered newest-first.

curl -G "https://app.otok.io/api/v1/deals" \
  -H "Authorization: Bearer otok_live_abc123..." \
  --data-urlencode 'status=open' \
  --data-urlencode 'pipeline_id=aa11bb22-3344-5566-7788-99aabbccddee'

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

GET /api/v1/deals/:id

Response 200 — the deal + contact_name/contact_phone/contact_email. 404 — "Deal not found". Non-UUID id → 400.

POST /api/v1/deals

Creates a deal — or, when external_reference matches an existing deal, updates it (idempotent upsert; see below).

Request body

Contact resolution

Shared with the contacts upsert:

• contact_id wins when present.
• Otherwise phone/email are upserted exactly like POST /v1/contacts: normalized phone match wins, email is the fallback; a match updates that contact, no match creates one.
• Phone resolving to one contact and email to a different one → 409 CONTACT_MERGE_REQUIRED (a merge request is parked; see contacts).
• Neither contact_id nor phone/email → 400 "Provide contact_id, or a phone/email to attach the deal to a contact".

Product attachment and title lock

A product reference is resolved in order: product_id → product_sku → product_external_id (first provided wins). While a product is attached:

• The deal's title is derived from the product name — any client-sent title is ignored.
• A missing amount defaults to the product's price.
• Only active products can be attached to new records (a product already attached to the deal stays valid even if deactivated).

Idempotent upsert via external_reference

external_reference is unique per workspace. When a POST carries an external_reference that matches an existing deal, the deal is updated instead of created:

• Fields updated (only those present in the body): product_id (when a product reference resolves), title (still ignored while a product is attached), amount, currency, owner_user_id, expected_close_at, note.
• contact_id is always re-applied from the freshly resolved contact — a repeat POST with different phone/email re-points the deal to that contact (and the contact upsert side effects still run). Because contact resolution happens before the match check, every repeat POST must still carry contact_id or phone/email.
• stage_id, if present and different from the deal's current stage, moves the deal (with the same ledger/automation effects as POST /v1/deals/:id/stage).
• status is never touched on a match — use POST /v1/deals/:id/status.
• pipeline_id is ignored on a match (only stage moves apply).

The response is 201 in both cases, with a top-level boolean duplicate field: false when this request created the deal, true when the external_reference matched an existing deal (fields updated / stage moved, status untouched).

Example

curl -X POST "https://app.otok.io/api/v1/deals" \
  -H "Authorization: Bearer otok_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+972501234567",
    "email": "dana@example.com",
    "name": "Dana Levi",
    "title": "Annual plan — Dana Levi",
    "amount": 3600,
    "currency": "ILS",
    "expected_close_at": "2026-08-01T00:00:00.000Z",
    "external_reference": "crm-opp-10042"
  }'

Response 201:

{
  "id": "d3a1b2c4-5e6f-7081-92a3-b4c5d6e7f809",
  "pipeline_id": "aa11bb22-3344-5566-7788-99aabbccddee",
  "stage_id": "st-1111…",
  "contact_id": "9c2f1a4e-3b7d-4e2a-9f0c-1d2e3f4a5b6c",
  "title": "Annual plan — Dana Levi",
  "amount": 3600,
  "currency": "ILS",
  "status": "open",
  "expected_close_at": "2026-08-01T00:00:00.000Z",
  "external_reference": "crm-opp-10042",
  "source": "api",
  "contact_name": "Dana Levi",
  "contact_phone": "+972501234567",
  "contact_email": "dana@example.com",
  "duplicate": false,
  "created_at": "2026-07-14T10:00:00.000Z",
  "updated_at": "2026-07-14T10:00:00.000Z"
}

Errors

(error_code values appear as an error_code field on the response body.)

Side effects

A created deal enters at the top of its stage column, is recorded in the contact's activity timeline, fires the workspace's deal-created automations, and syncs to connected integrations (e.g. Salesforce). API writes are attributed to source api with no acting user.

PATCH /api/v1/deals/:id

Update deal fields. All fields optional.

Field updates do not write stage-history entries and do not fire deal automations — only the /stage and /status routes do.

Response 200 — the updated deal + joined contact fields.

POST /api/v1/deals/:id/stage

Move a deal to a stage (any stage in the workspace — cross-pipeline moves are supported; the deal's pipeline_id follows the target stage).

curl -X POST "https://app.otok.io/api/v1/deals/d3a1b2c4-5e6f-7081-92a3-b4c5d6e7f809/stage" \
  -H "Authorization: Bearer otok_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{ "stage_id": "st-2222…" }'

Response 201 — the updated deal row (no joined contact fields on this route).

A move to the deal's current stage is a pure reorder (position only — no history entry, no automations). A genuine stage change stamps stage_entered_at, records a stage-transition history entry and activity row, and fires deal-stage-changed automations.

POST /api/v1/deals/:id/status

Set the deal's status.

curl -X POST "https://app.otok.io/api/v1/deals/d3a1b2c4-5e6f-7081-92a3-b4c5d6e7f809/status" \
  -H "Authorization: Bearer otok_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{ "status": "won" }'

Response 201 — the updated deal row (no joined contact fields). If the deal already has the requested status, the current row is returned unchanged (no history entry, no automations).

Semantics:

• Closing (won/lost) stamps closed_at and keeps the deal on its last stage.
• Reopening clears closed_at and lost_reason.
• won / lost fire the corresponding deal automations (reopen fires none), and winning a deal triggers connected revenue/conversion integrations.