CRM

Deals & pipelines

Pipelines and their stages, deals with contacts and line items, won / lost, forecasting fields.

A deal lives in a pipeline, at a stage. Its status follows the stage type (open, won, lost). Responses add computed fields: stage_name, stage_probability, weighted_amount, days_in_stage, is_rotting (stuck longer than the stage allows), is_overdue (past its close date), revenue ({ recurring, mrr, arr, term, one_time, tcv, acv }), amount_home / weighted_home / fx_rate / home_currency (the amount in the workspace’s home currency — a closed deal keeps the rate of the day it closed, custom.fx), approval_pending and, for open deals, score ({ value 0–100, level high | medium | low, basis learned | stage, factors[] } — the chance it is won, learned from the workspace’s deals closed in the last two years: furthest stage reached, size against the usual deal, source, owner, pipeline, type, repeat customer, next step, age; with fewer than 12 closed deals, the stage probability nudged by health). Every change of a tracked field (amount, close date, owner, stage, team, split…) is kept with who made it — GET /deals/{id}/history.

In a chat
Copy a ready promptPaste it in any AI: it reads the docs and follows the rules of the API.
Open in Claude or ChatGPTA new conversation with the prompt already written.
This page as MarkdownFor an AI that cannot open links: paste the text itself.
In your editor
Claude Code or CodexAdd this line to CLAUDE.md or AGENTS.md.Meetzy API reference (read before calling the API): https://www.meetzy.ai/llms-full.txt
CursorSettings › Indexing & Docs › Add Doc, then type @Meetzy in the chat.https://www.meetzy.ai/llms-full.txt
Connect Meetzy as tools (MCP)The AI can then read and change your CRM itself — Claude Code:claude mcp add --transport http meetzy https://app.meetzy.ai/api/mcp/mcp
Same for Codexcodex mcp add meetzy --url https://app.meetzy.ai/api/mcp/mcp
GET/pipelines

List pipelines

Every pipeline with its stages. Each sales cycle has its own pipeline (its deal board): sales_cycle gives that cycle ({ id, name }), null for a pipeline of your own. Renaming one renames the other.

Scope: read
Request
curl "https://app.meetzy.ai/api/v1/pipelines" \
  -H "Authorization: Bearer $MEETZY_API_KEY"
const res = await fetch("https://app.meetzy.ai/api/v1/pipelines", {
  headers: { Authorization: `Bearer ${process.env.MEETZY_API_KEY}` },
});
const data = await res.json();
import os, requests

res = requests.get(
    "https://app.meetzy.ai/api/v1/pipelines",
    headers={"Authorization": f"Bearer {os.environ['MEETZY_API_KEY']}"},
)
data = res.json()
Response200
{
  "pipelines": [
    {
      "id": "cacafee6-6c63-407f-a948-5d6570c20143",
      "user_from": "acme",
      "name": "Sales pipeline",
      "is_default": true,
      "position": 0,
      "stages": [
        {
          "id": "qualification",
          "name": "Qualification",
          "type": "open",
          "color": "#6366F1",
          "rot_days": 14,
          "probability": 10
        },
        {
          "id": "discovery",
          "name": "Discovery call",
          "type": "open",
          "color": "#3B82F6",
          "rot_days": 14,
          "probability": 20
        },
        {
          "id": "demo",
          "name": "Demo / Meeting",
          "type": "open",
          "color": "#06B6D4",
          "rot_days": 10,
          "probability": 40
        }
      ],
      "currency": "EUR",
      "created_at": "2026-10-07T13:09:25.305055+00:00",
      "updated_at": "2026-10-07T13:09:25.305055+00:00"
    }
  ]
}
POST/pipelines

Create a pipeline

Creates a pipeline. Each stage: name, probability (0–100), color, type (open, won, lost), rot_days (days before the deal counts as stuck), description (its playbook), required (what a deal needs to enter it — any of amount, close_date, next_step, contact, company, owner, and close_reason on a won / lost stage: the app asks for them on a move, bulk moves skip the deals missing them unless force), tasks (up to 5 { title, type, due_days } created for the owner when a deal enters it, once per deal), approval (true: a move into it by someone who is not the owner or an admin of the workspace becomes a request they approve — see POST /deals/{id}/approval) and, on the won / lost stage, reasons (the reasons offered when a deal closes there). A won and a lost stage are added when missing.

Scope: write

Body

namestringrequired
Pipeline name.
stagesobject[]
Stages in order. Default: the B2B template (Qualification → Negotiation).
currencystring
Currency of its deals. Default EUR.
Request
curl -X POST "https://app.meetzy.ai/api/v1/pipelines" \
  -H "Authorization: Bearer $MEETZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Partners",
    "currency": "EUR",
    "stages": [
      {
        "name": "New",
        "probability": 10
      },
      {
        "name": "Contract sent",
        "probability": 60,
        "rot_days": 10
      }
    ]
  }'
const res = await fetch("https://app.meetzy.ai/api/v1/pipelines", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.MEETZY_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "name": "Partners",
    "currency": "EUR",
    "stages": [
      {
        "name": "New",
        "probability": 10
      },
      {
        "name": "Contract sent",
        "probability": 60,
        "rot_days": 10
      }
    ]
  }),
});
const data = await res.json();
import os, requests

res = requests.post(
    "https://app.meetzy.ai/api/v1/pipelines",
    headers={"Authorization": f"Bearer {os.environ['MEETZY_API_KEY']}"},
    json={
        "name": "Partners",
        "currency": "EUR",
        "stages": [
            {
                "name": "New",
                "probability": 10
            },
            {
                "name": "Contract sent",
                "probability": 60,
                "rot_days": 10
            }
        ]
    },
)
data = res.json()
Response201
{
  "id": "d9b0bf57-c46d-451f-adc0-adb7d2d43938",
  "user_from": "acme",
  "name": "Partners",
  "is_default": false,
  "position": 1,
  "stages": [
    {
      "id": "new",
      "name": "New",
      "type": "open",
      "color": "#6366F1",
      "rot_days": null,
      "probability": 10
    },
    {
      "id": "proposal",
      "name": "Proposal",
      "type": "open",
      "color": "#6366F1",
      "rot_days": null,
      "probability": 50
    }
  ],
  "currency": "EUR",
  "created_at": "2026-10-07T13:22:29.376133+00:00",
  "updated_at": "2026-10-07T13:22:29.376133+00:00"
}
PATCH/pipelines/{id}

Update a pipeline

Rename, reorder, change stages or make it the default. Each stage: name, probability (0–100), color, type (open, won, lost), rot_days (days before the deal counts as stuck), description (its playbook), required (what a deal needs to enter it — any of amount, close_date, next_step, contact, company, owner, and close_reason on a won / lost stage: the app asks for them on a move, bulk moves skip the deals missing them unless force), tasks (up to 5 { title, type, due_days } created for the owner when a deal enters it, once per deal), approval (true: a move into it by someone who is not the owner or an admin of the workspace becomes a request they approve — see POST /deals/{id}/approval) and, on the won / lost stage, reasons (the reasons offered when a deal closes there). A won and a lost stage are added when missing.

Scope: write

Path parameters

idstringrequired
Id of the record (UUID).

Body

namestring
Name.
stagesobject[]
Full list of stages (replaces the current one).
currencystring
Currency.
positioninteger
Order among pipelines.
is_defaultboolean
true makes it the default pipeline.
Request
curl -X PATCH "https://app.meetzy.ai/api/v1/pipelines/e43414d6-f56f-42be-a64c-a836d6015efc" \
  -H "Authorization: Bearer $MEETZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Partners & resellers"
  }'
const res = await fetch("https://app.meetzy.ai/api/v1/pipelines/e43414d6-f56f-42be-a64c-a836d6015efc", {
  method: "PATCH",
  headers: { Authorization: `Bearer ${process.env.MEETZY_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "name": "Partners & resellers"
  }),
});
const data = await res.json();
import os, requests

res = requests.patch(
    "https://app.meetzy.ai/api/v1/pipelines/e43414d6-f56f-42be-a64c-a836d6015efc",
    headers={"Authorization": f"Bearer {os.environ['MEETZY_API_KEY']}"},
    json={
        "name": "Partners & resellers"
    },
)
data = res.json()
Response200
{
  "id": "d9b0bf57-c46d-451f-adc0-adb7d2d43938",
  "user_from": "acme",
  "name": "Partners",
  "is_default": false,
  "position": 1,
  "stages": [
    {
      "id": "new",
      "name": "New",
      "type": "open",
      "color": "#6366F1",
      "rot_days": null,
      "probability": 10
    },
    {
      "id": "proposal",
      "name": "Proposal",
      "type": "open",
      "color": "#6366F1",
      "rot_days": null,
      "probability": 50
    }
  ],
  "currency": "EUR",
  "created_at": "2026-10-07T13:22:29.376133+00:00",
  "updated_at": "2026-10-07T13:22:30.283636+00:00"
}
DELETE/pipelines/{id}

Delete a pipeline

Only an empty pipeline can be deleted (409 otherwise) — never the default one, nor the deal board of a sales cycle (delete the cycle instead, PUT /crm/cycles).

Scope: delete

Path parameters

idstringrequired
Id of the record (UUID).
Request
curl -X DELETE "https://app.meetzy.ai/api/v1/pipelines/e43414d6-f56f-42be-a64c-a836d6015efc" \
  -H "Authorization: Bearer $MEETZY_API_KEY"
const res = await fetch("https://app.meetzy.ai/api/v1/pipelines/e43414d6-f56f-42be-a64c-a836d6015efc", {
  method: "DELETE",
  headers: { Authorization: `Bearer ${process.env.MEETZY_API_KEY}` },
});
const data = await res.json();
import os, requests

res = requests.delete(
    "https://app.meetzy.ai/api/v1/pipelines/e43414d6-f56f-42be-a64c-a836d6015efc",
    headers={"Authorization": f"Bearer {os.environ['MEETZY_API_KEY']}"},
)
data = res.json()
Response200
{
  "deleted": true
}
GET/deals/sources

Deals from your ERP

With an ERP or shop connected, deals fill themselves from what it syncs, whatever the system: every open quote is a deal (amount, validity, customer, salesperson, products — won when an order follows, lost when it closes without one), and customers who buy regularly get an expected reorder deal when their next order is due (their usual amount, a probability from how regular they are; their next order closes it as won with its real amount). This returns the settings, where each kind of deal goes (routes), and counts per kind. Refreshes on its own when older than 15 minutes, and after every sync. Generated deals carry custom.auto (kind, ref…).

Scope: read

Query parameters

refreshstring
1 updates now, 0 never (default: when stale).
Request
curl "https://app.meetzy.ai/api/v1/deals/sources" \
  -H "Authorization: Bearer $MEETZY_API_KEY"
const res = await fetch("https://app.meetzy.ai/api/v1/deals/sources", {
  headers: { Authorization: `Bearer ${process.env.MEETZY_API_KEY}` },
});
const data = await res.json();
import os, requests

res = requests.get(
    "https://app.meetzy.ai/api/v1/deals/sources",
    headers={"Authorization": f"Bearer {os.environ['MEETZY_API_KEY']}"},
)
data = res.json()
Response200
{
  "connected": true,
  "provider": "sap_b1",
  "settings": {
    "enabled": true,
    "quotes": {
      "enabled": true,
      "pipeline_id": null,
      "stage_id": null,
      "max_age_days": 180
    },
    "reorders": {
      "enabled": true,
      "pipeline_id": null,
      "stage_id": null,
      "window_days": 30,
      "min_orders": 3,
      "lose_after_cycles": 2
    }
  },
  "routes": {
    "quotes": {
      "pipeline_id": "5f1e…",
      "stage_id": "proposal"
    },
    "reorders": {
      "pipeline_id": "5f1e…",
      "stage_id": "qualification"
    }
  },
  "counts": {
    "reorder": {
      "open": 53,
      "won": 12,
      "lost": 2,
      "open_amount": 822882
    },
    "quote": {
      "open": 1,
      "won": 4,
      "lost": 1,
      "open_amount": 20669
    }
  },
  "last_run_at": "2026-10-07T16:20:00Z"
}
PUT/deals/sources

Set what fills the deals

Turn each kind on or off, choose its pipeline and stage (null = automatic), the reorder window and how many orders it takes to know a customer’s rhythm. Saves, then updates the deals.

Scope: write

Body

enabledboolean
Deals from the ERP at all.
quotesobject
{ enabled, pipeline_id, stage_id, max_age_days }.
reordersobject
{ enabled, pipeline_id, stage_id, window_days, min_orders, lose_after_cycles }.

Returns the same as GET /deals/sources.

Request
curl -X PUT "https://app.meetzy.ai/api/v1/deals/sources" \
  -H "Authorization: Bearer $MEETZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reorders": {
      "window_days": 21,
      "min_orders": 4
    }
  }'
const res = await fetch("https://app.meetzy.ai/api/v1/deals/sources", {
  method: "PUT",
  headers: { Authorization: `Bearer ${process.env.MEETZY_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "reorders": {
      "window_days": 21,
      "min_orders": 4
    }
  }),
});
const data = await res.json();
import os, requests

res = requests.put(
    "https://app.meetzy.ai/api/v1/deals/sources",
    headers={"Authorization": f"Bearer {os.environ['MEETZY_API_KEY']}"},
    json={
        "reorders": {
            "window_days": 21,
            "min_orders": 4
        }
    },
)
data = res.json()
Response200

See the notes on the left.

POST/deals/sources/refresh

Update the deals from the ERP now

Creates the new ones, closes the ones whose order arrived (won) or whose quote closed without an order (lost), moves the others. A deal you deleted is never created again; an amount you changed by hand is kept.

Scope: write
Request
curl -X POST "https://app.meetzy.ai/api/v1/deals/sources/refresh" \
  -H "Authorization: Bearer $MEETZY_API_KEY"
const res = await fetch("https://app.meetzy.ai/api/v1/deals/sources/refresh", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.MEETZY_API_KEY}` },
});
const data = await res.json();
import os, requests

res = requests.post(
    "https://app.meetzy.ai/api/v1/deals/sources/refresh",
    headers={"Authorization": f"Bearer {os.environ['MEETZY_API_KEY']}"},
)
data = res.json()
Response201
{
  "created": 4,
  "updated": 2,
  "won": 1,
  "lost": 0,
  "skipped": 0
}
GET/deals

List deals

Deals with their company and primary contact, plus the pipelines (for stage names). Sorted by last update. Open deals also carry last_activity_at (last call, email, meeting or note on the deal or with its contact), next_task ({ title, due_at }) and health ({ level: good | attention | at_risk, score, reasons[] } — close date passed, stuck in stage, no activity, no next step, no amount, nobody on it).

Scope: read

Query parameters

pipeline_iduuid
One pipeline, or several separated by commas.
statusstring
open, won, lost or all (default: all).
stage_idstring
Stage id.
ownerstring
Owner email — also the deals where they are a collaborator (collaborating=false for owned ones only).
collaboratingstring
false: with owner, only the deals they own.
approvalstring
pending: only deals waiting for a manager’s approval.
company_iduuid
Deals of a company.
lead_iduuid
Deals where this contact is primary or linked.
prioritystring
Priority.
close_fromdate
Close date on or after.
close_todate
Close date on or before.
qstring
Search in the deal name.
sortstring
Column to sort by. Default updated_at.
orderstring
asc or desc (default).
limitinteger
Page size, 1–1000. Default 500.
offsetinteger
Rows to skip.
Request
curl "https://app.meetzy.ai/api/v1/deals?status=open&close_to=2026-12-31" \
  -H "Authorization: Bearer $MEETZY_API_KEY"
const res = await fetch("https://app.meetzy.ai/api/v1/deals?status=open&close_to=2026-12-31", {
  headers: { Authorization: `Bearer ${process.env.MEETZY_API_KEY}` },
});
const data = await res.json();
import os, requests

res = requests.get(
    "https://app.meetzy.ai/api/v1/deals?status=open&close_to=2026-12-31",
    headers={"Authorization": f"Bearer {os.environ['MEETZY_API_KEY']}"},
)
data = res.json()
Response200
{
  "deals": [
    {
      "id": "d74acfa5-9877-4d7f-a369-3a505bac042a",
      "user_from": "acme",
      "name": "Payfit — rollout",
      "pipeline_id": "cacafee6-6c63-407f-a948-5d6570c20143",
      "stage_id": "qualification",
      "status": "open",
      "amount": 12000,
      "currency": "EUR",
      "probability": null,
      "close_date": "2026-11-06",
      "owner_email": "olivia@acme.com",
      "company_id": "166c436d-a874-4730-a0d8-c8d7fa090268",
      "primary_lead_id": "8028ff76-1da4-451f-a0e7-dd91db772c20",
      "priority": "medium",
      "deal_type": "new_business",
      "source": null,
      "recurring": false,
      "mrr": null,
      "next_step": null,
      "next_step_date": null,
      "description": null,
      "lost_reason": null,
      "won_reason": null,
      "competitors": [],
      "tags": [],
      "custom": {},
      "stage_entered_at": "2026-10-07T13:22:48.038488+00:00",
      "stage_history": [],
      "closed_at": null,
      "last_activity_at": null,
      "created_by": "olivia@acme.com",
      "created_at": "2026-10-07T13:22:48.038488+00:00",
      "updated_at": "2026-10-07T13:22:48.038488+00:00",
      "stage_name": "Qualification",
      "stage_color": "#6366F1",
      "stage_probability": 10,
      "weighted_amount": 1200,
      "days_in_stage": 0,
      "is_rotting": false,
      "is_overdue": false,
      "company": {
        "id": "166c436d-a874-4730-a0d8-c8d7fa090268",
        "name": "Payfit",
        "domain": "payfit.com",
        "logo_url": null
      },
      "primary_contact": {
        "id": "8028ff76-1da4-451f-a0e7-dd91db772c20",
        "display_name": "Camille Laurent",
        "primary_email": "camille@payfit.com",
        "avatar_url": null,
        "title": "Head of Sales"
      }
    }
  ],
  "total": 1,
  "pipelines": [
    {
      "id": "cacafee6-6c63-407f-a948-5d6570c20143",
      "user_from": "acme",
      "name": "Sales pipeline",
      "is_default": true,
      "position": 0,
      "stages": [
        {
          "id": "qualification",
          "name": "Qualification",
          "type": "open",
          "color": "#6366F1",
          "rot_days": 14,
          "probability": 10
        },
        {
          "id": "discovery",
          "name": "Discovery call",
          "type": "open",
          "color": "#3B82F6",
          "rot_days": 14,
          "probability": 20
        },
        {
          "id": "demo",
          "name": "Demo / Meeting",
          "type": "open",
          "color": "#06B6D4",
          "rot_days": 10,
          "probability": 40
        }
      ],
      "currency": "EUR",
      "created_at": "2026-10-07T13:09:25.305055+00:00",
      "updated_at": "2026-10-07T13:09:25.305055+00:00"
    },
    {
      "id": "d9b0bf57-c46d-451f-adc0-adb7d2d43938",
      "user_from": "acme",
      "name": "Partners",
      "is_default": false,
      "position": 1,
      "stages": [
        {
          "id": "new",
          "name": "New",
          "type": "open",
          "color": "#6366F1",
          "rot_days": null,
          "probability": 10
        },
        {
          "id": "proposal",
          "name": "Proposal",
          "type": "open",
          "color": "#6366F1",
          "rot_days": null,
          "probability": 50
        },
        {
          "id": "won",
          "name": "Closed won",
          "type": "won",
          "color": "#10B981",
          "probability": 100
        }
      ],
      "currency": "EUR",
      "created_at": "2026-10-07T13:22:29.376133+00:00",
      "updated_at": "2026-10-07T13:22:30.283636+00:00"
    }
  ]
}
POST/deals/bulk

Change many deals at once

Up to 2,000 deals per call, each through the same path as PATCH /deals/{id} (stage history, workflows, CRM rules): move them to a stage — of their pipeline or another one —, assign, prioritise, set or push the close date, win, lose or reopen, tag — or delete them.

Scope: write

Body

idsuuid[]required
Deals to change.
pipeline_iduuid
With stage_id: the pipeline to move them to (default: the first deal’s).
stage_idstring
Stage to move them to.
patchobject
Fields to set: owner_email, priority, close_date, deal_type, next_step, next_step_date, probability.
shift_close_daysnumber
Push (or bring forward, negative) each close date by this many days.
forecast_categorystring
pipeline, best_case, commit, omitted, or empty for automatic.
forceboolean
Move them even when the stage asks for fields they lack (otherwise those deals are skipped, listed in skipped).
statusstring
won, lost or open (reopen).
reasonstring
Why they were won / lost (with status).
add_tagsstring[]
Tags to add.
add_collaboratorsstring[]
Teammates (emails) to add as collaborators.
add_followersstring[]
Teammates (emails) to add as followers.
followboolean
true / false: the key’s user follows or stops following them.
deleteboolean
true deletes them (a deal made from the ERP is not created again).

A move into a stage a manager approves becomes a request for each deal (counted in requested) when the caller is not the owner or an admin of the workspace.

Closing deals in a pipeline whose won / lost stage requires a reason needs reason.

Request
curl -X POST "https://app.meetzy.ai/api/v1/deals/bulk" \
  -H "Authorization: Bearer $MEETZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": [
      "9b1d0c6e-4f3a-4b8e-9a2d-1c5e7f8a9b0c"
    ],
    "pipeline_id": "70b6523f-75a9-4903-8163-1c9ae50f1db8",
    "stage_id": "order_form_sent"
  }'
const res = await fetch("https://app.meetzy.ai/api/v1/deals/bulk", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.MEETZY_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "ids": [
      "9b1d0c6e-4f3a-4b8e-9a2d-1c5e7f8a9b0c"
    ],
    "pipeline_id": "70b6523f-75a9-4903-8163-1c9ae50f1db8",
    "stage_id": "order_form_sent"
  }),
});
const data = await res.json();
import os, requests

res = requests.post(
    "https://app.meetzy.ai/api/v1/deals/bulk",
    headers={"Authorization": f"Bearer {os.environ['MEETZY_API_KEY']}"},
    json={
        "ids": ["9b1d0c6e-4f3a-4b8e-9a2d-1c5e7f8a9b0c"],
        "pipeline_id": "70b6523f-75a9-4903-8163-1c9ae50f1db8",
        "stage_id": "order_form_sent"
    },
)
data = res.json()
Response201
{
  "updated": 1,
  "failed": 0,
  "errors": [],
  "skipped": []
}
POST/deals

Create a deal

Creates a deal, links its contacts and line items and logs it on the timeline. When primary_lead_id is set, the deal joins that contact’s sales cycle pipeline and company.

Scope: write

Body

namestringrequired
Deal name.
amountnumber
Value of the deal. Computed from line_items when you send lines and no amount.
currencystring
ISO currency (EUR, USD…). Defaults to the pipeline currency.
pipeline_iduuid
Pipeline. Default: the contact’s sales cycle pipeline, else the default pipeline.
stage_idstring
Stage id in that pipeline (see GET /pipelines). Default: the first open stage. Moving to a won / lost stage sets status.
statusstring
open, won or lost. Setting it moves the deal to the matching stage. Winning a deal makes its contacts and company customers.
probabilityinteger
Win probability override (0–100). Default: the stage probability.
close_datedate
Expected close date (YYYY-MM-DD). Default: in 30 days.
owner_emailstring
Owner. Default: the key’s user.
company_iduuid
Company. Found from the primary contact when omitted.
primary_lead_iduuid
Main contact of the deal.
prioritystring
low, medium or high.
deal_typestring
e.g. new_business, upsell, renewal.
sourcestring
Where the deal came from.
recurringboolean
Recurring revenue deal.
mrrnumber
Monthly recurring revenue (computed from monthly / yearly line items).
next_stepstring
Next step.
next_step_datedate
When the next step is due.
descriptionstring
Notes about the deal.
lost_reasonstring
Why it was lost (see lost_reasons in the reference).
won_reasonstring
Why it was won.
competitorsstring[]
Competitors in the deal.
tagsstring[]
Free labels.
customobject
Custom properties.
forecast_categorystring
pipeline, best_case, commit or omitted (left out of the forecast); empty = from the probability. Kept in custom.forecast_category.
collaboratorsstring[]
Teammates (emails) who work the deal with its owner. They see it in their “Mine” views and owner= filters.
followersstring[]
Teammates told of every change on the deal (stage, outcome, amount, close date, owner).
followboolean
true / false: the key’s user follows or stops following the deal.
splitsobject[]
Who gets credit: [{ email, percent }] adding up to 100 (team forecast and reports count each person at their share). Empty = all to the owner. Kept in custom.splits.
contract_monthsinteger
Term of a recurring deal in months (default 12): TCV = MRR × term + one-off fees.
one_timenumber
One-off fees of a recurring deal (set up, installation…). Kept in custom.one_time.
custom_setobject
Custom properties one by one: { key: value } (null clears one) — the rest of custom is kept.
approval_notestring
With a move to a stage a manager approves: the note sent with the request.
contact_idsuuid[]
Other contacts to link.
line_itemsobject[]
Products of the deal. Each line: name, quantity, unit_price, optional product_id, discount_pct, tax_pct, billing (one_time, monthly, yearly).
Request
curl -X POST "https://app.meetzy.ai/api/v1/deals" \
  -H "Authorization: Bearer $MEETZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Payfit — rollout",
    "primary_lead_id": "e43414d6-f56f-42be-a64c-a836d6015efc",
    "close_date": "2026-11-30",
    "line_items": [
      {
        "name": "Licence",
        "quantity": 10,
        "unit_price": 1200,
        "billing": "yearly"
      }
    ]
  }'
const res = await fetch("https://app.meetzy.ai/api/v1/deals", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.MEETZY_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "name": "Payfit — rollout",
    "primary_lead_id": "e43414d6-f56f-42be-a64c-a836d6015efc",
    "close_date": "2026-11-30",
    "line_items": [
      {
        "name": "Licence",
        "quantity": 10,
        "unit_price": 1200,
        "billing": "yearly"
      }
    ]
  }),
});
const data = await res.json();
import os, requests

res = requests.post(
    "https://app.meetzy.ai/api/v1/deals",
    headers={"Authorization": f"Bearer {os.environ['MEETZY_API_KEY']}"},
    json={
        "name": "Payfit — rollout",
        "primary_lead_id": "e43414d6-f56f-42be-a64c-a836d6015efc",
        "close_date": "2026-11-30",
        "line_items": [
            {
                "name": "Licence",
                "quantity": 10,
                "unit_price": 1200,
                "billing": "yearly"
            }
        ]
    },
)
data = res.json()
Response201
{
  "id": "d74acfa5-9877-4d7f-a369-3a505bac042a",
  "user_from": "acme",
  "name": "Payfit — rollout",
  "pipeline_id": "cacafee6-6c63-407f-a948-5d6570c20143",
  "stage_id": "qualification",
  "status": "open",
  "amount": 12000,
  "currency": "EUR",
  "probability": null,
  "close_date": "2026-11-06",
  "owner_email": "olivia@acme.com",
  "company_id": "166c436d-a874-4730-a0d8-c8d7fa090268",
  "primary_lead_id": "8028ff76-1da4-451f-a0e7-dd91db772c20",
  "priority": "medium",
  "deal_type": "new_business",
  "source": null,
  "recurring": false,
  "mrr": null,
  "next_step": null,
  "next_step_date": null,
  "description": null,
  "lost_reason": null,
  "won_reason": null,
  "competitors": [],
  "tags": [],
  "custom": {},
  "stage_entered_at": "2026-10-07T13:22:48.038488+00:00",
  "stage_history": [],
  "closed_at": null,
  "last_activity_at": null,
  "created_by": "olivia@acme.com",
  "created_at": "2026-10-07T13:22:48.038488+00:00",
  "updated_at": "2026-10-07T13:22:48.038488+00:00",
  "stage_name": "Qualification",
  "stage_color": "#6366F1",
  "stage_probability": 10,
  "weighted_amount": 1200,
  "days_in_stage": 0,
  "is_rotting": false,
  "is_overdue": false
}
GET/deals/{id}

Get a deal

The deal with its pipeline, company, contacts (with role), line items, tasks, timeline and quotes — plus origin for a deal made from the ERP (the quote, or the customer’s buying rhythm for an expected reorder) and company_summary (bought in the last 12 months, last order, open quotes, unpaid).

Scope: read

Path parameters

idstringrequired
Id of the record (UUID).
Request
curl "https://app.meetzy.ai/api/v1/deals/e43414d6-f56f-42be-a64c-a836d6015efc" \
  -H "Authorization: Bearer $MEETZY_API_KEY"
const res = await fetch("https://app.meetzy.ai/api/v1/deals/e43414d6-f56f-42be-a64c-a836d6015efc", {
  headers: { Authorization: `Bearer ${process.env.MEETZY_API_KEY}` },
});
const data = await res.json();
import os, requests

res = requests.get(
    "https://app.meetzy.ai/api/v1/deals/e43414d6-f56f-42be-a64c-a836d6015efc",
    headers={"Authorization": f"Bearer {os.environ['MEETZY_API_KEY']}"},
)
data = res.json()
Response200
{
  "deal": {
    "id": "d74acfa5-9877-4d7f-a369-3a505bac042a",
    "user_from": "acme",
    "name": "Payfit — rollout",
    "pipeline_id": "cacafee6-6c63-407f-a948-5d6570c20143",
    "stage_id": "qualification",
    "status": "open",
    "amount": 12000,
    "currency": "EUR",
    "probability": null,
    "close_date": "2026-11-06",
    "owner_email": "olivia@acme.com",
    "company_id": "166c436d-a874-4730-a0d8-c8d7fa090268",
    "primary_lead_id": "8028ff76-1da4-451f-a0e7-dd91db772c20",
    "priority": "medium",
    "deal_type": "new_business",
    "source": null,
    "recurring": false,
    "mrr": null,
    "next_step": null,
    "next_step_date": null,
    "description": null,
    "lost_reason": null,
    "won_reason": null,
    "competitors": [],
    "tags": [],
    "custom": {},
    "stage_entered_at": "2026-10-07T13:22:48.038488+00:00",
    "stage_history": [],
    "closed_at": null,
    "last_activity_at": null,
    "created_by": "olivia@acme.com",
    "created_at": "2026-10-07T13:22:48.038488+00:00",
    "updated_at": "2026-10-07T13:22:48.038488+00:00",
    "stage_name": "Qualification",
    "stage_color": "#6366F1",
    "stage_probability": 10,
    "weighted_amount": 1200,
    "days_in_stage": 0,
    "is_rotting": false,
    "is_overdue": false
  },
  "pipeline": {
    "id": "cacafee6-6c63-407f-a948-5d6570c20143",
    "user_from": "acme",
    "name": "Sales pipeline",
    "is_default": true,
    "position": 0,
    "stages": [
      {
        "id": "qualification",
        "name": "Qualification",
        "type": "open",
        "color": "#6366F1",
        "rot_days": 14,
        "probability": 10
      },
      {
        "id": "discovery",
        "name": "Discovery call",
        "type": "open",
        "color": "#3B82F6",
        "rot_days": 14,
        "probability": 20
      },
      {
        "id": "demo",
        "name": "Demo / Meeting",
        "type": "open",
        "color": "#06B6D4",
        "rot_days": 10,
        "probability": 40
      }
    ],
    "currency": "EUR",
    "created_at": "2026-10-07T13:09:25.305055+00:00",
    "updated_at": "2026-10-07T13:09:25.305055+00:00"
  },
  "company": {
    "id": "166c436d-a874-4730-a0d8-c8d7fa090268",
    "user_from": "acme",
    "name": "Payfit",
    "domain": "payfit.com",
    "website": null,
    "industry": "Software",
    "employees": 42,
    "annual_revenue": null,
    "country": null,
    "city": null,
    "address": null,
    "phone": null,
    "linkedin_url": null,
    "description": null,
    "logo_url": null,
    "owner_email": "olivia@acme.com",
    "lifecycle_stage": "lead",
    "company_type": "prospect",
    "tier": "B",
    "health_score": null,
    "tags": [
      "api",
      "vip"
    ],
    "custom": {},
    "parent_company_id": null,
    "apollo_id": null,
    "last_activity_at": null,
    "created_by": "olivia@acme.com",
    "created_at": "2026-10-07T13:22:31.105534+00:00",
    "updated_at": "2026-10-07T13:22:37.766452+00:00"
  },
  "contacts": [
    {
      "id": "8028ff76-1da4-451f-a0e7-dd91db772c20",
      "display_name": "Camille Laurent",
      "first_name": "Camille",
      "last_name": "Laurent",
      "primary_email": "camille@payfit.com",
      "phone": "+33612345678",
      "title": "Head of Sales",
      "company": "Payfit",
      "company_id": "166c436d-a874-4730-a0d8-c8d7fa090268",
      "avatar_url": null,
      "lead_score": 40,
      "lead_status": "cold",
      "pipeline_stage": "new_leads",
      "lifecycle_stage": "mql",
      "assigned_to": null,
      "primary_source": "manual",
      "last_contact_at": null,
      "created_at": "2026-10-07T13:22:38.585893+00:00",
      "linkedin_profile_url": null,
      "country": null,
      "city": null,
      "tags": [
        "inbound"
      ],
      "role": "decision_maker",
      "is_primary": true
    }
  ],
  "line_items": [
    {
      "id": "f660389d-a1c3-409b-a31b-b6245997bed1",
      "deal_id": "d74acfa5-9877-4d7f-a369-3a505bac042a",
      "product_id": null,
      "name": "Licence",
      "quantity": 10,
      "unit_price": 1200,
      "discount_pct": 0,
      "tax_pct": 0,
      "billing": "one_time",
      "position": 0,
      "created_at": "2026-10-07T13:22:48.311396+00:00"
    }
  ],
  "tasks": [],
  "activities": [
    {
      "id": "d7d99f47-ec01-46ec-aaf8-128b52670227",
      "user_from": "acme",
      "type": "system",
      "subject": "Deal created: Payfit — rollout",
      "body": null,
      "outcome": null,
      "direction": null,
      "duration_sec": null,
      "occurred_at": "2026-10-07T13:22:48.418+00:00",
      "actor_email": "olivia@acme.com",
      "lead_id": "8028ff76-1da4-451f-a0e7-dd91db772c20",
      "deal_id": "d74acfa5-9877-4d7f-a369-3a505bac042a",
      "company_id": "166c436d-a874-4730-a0d8-c8d7fa090268",
      "metadata": {
        "amount": 12000
      },
      "created_at": "2026-10-07T13:22:48.454794+00:00"
    }
  ],
  "quotes": []
}
PATCH/deals/{id}

Update a deal — move, win, lose

Send only what changes. Move with stage_id; win or lose with status (or by moving to the won / lost stage). Stage moves are logged and the contact follows on the CRM board. A move into a stage a manager approves (approval on the stage), by someone who is not the owner or an admin of the workspace, does not move the deal: it answers with approval_requested: true and the request in custom.approval. Closing where the won / lost stage requires a reason answers 400 (reason_required) without won_reason / lost_reason.

Scope: write

Path parameters

idstringrequired
Id of the record (UUID).

Body

namestring
Deal name.
amountnumber
Value of the deal. Computed from line_items when you send lines and no amount.
currencystring
ISO currency (EUR, USD…). Defaults to the pipeline currency.
pipeline_iduuid
Pipeline. Default: the contact’s sales cycle pipeline, else the default pipeline.
stage_idstring
Stage id in that pipeline (see GET /pipelines). Default: the first open stage. Moving to a won / lost stage sets status.
statusstring
open, won or lost. Setting it moves the deal to the matching stage. Winning a deal makes its contacts and company customers.
probabilityinteger
Win probability override (0–100). Default: the stage probability.
close_datedate
Expected close date (YYYY-MM-DD). Default: in 30 days.
owner_emailstring
Owner. Default: the key’s user.
company_iduuid
Company. Found from the primary contact when omitted.
primary_lead_iduuid
Main contact of the deal.
prioritystring
low, medium or high.
deal_typestring
e.g. new_business, upsell, renewal.
sourcestring
Where the deal came from.
recurringboolean
Recurring revenue deal.
mrrnumber
Monthly recurring revenue (computed from monthly / yearly line items).
next_stepstring
Next step.
next_step_datedate
When the next step is due.
descriptionstring
Notes about the deal.
lost_reasonstring
Why it was lost (see lost_reasons in the reference).
won_reasonstring
Why it was won.
competitorsstring[]
Competitors in the deal.
tagsstring[]
Free labels.
customobject
Custom properties.
forecast_categorystring
pipeline, best_case, commit or omitted (left out of the forecast); empty = from the probability. Kept in custom.forecast_category.
collaboratorsstring[]
Teammates (emails) who work the deal with its owner. They see it in their “Mine” views and owner= filters.
followersstring[]
Teammates told of every change on the deal (stage, outcome, amount, close date, owner).
followboolean
true / false: the key’s user follows or stops following the deal.
splitsobject[]
Who gets credit: [{ email, percent }] adding up to 100 (team forecast and reports count each person at their share). Empty = all to the owner. Kept in custom.splits.
contract_monthsinteger
Term of a recurring deal in months (default 12): TCV = MRR × term + one-off fees.
one_timenumber
One-off fees of a recurring deal (set up, installation…). Kept in custom.one_time.
custom_setobject
Custom properties one by one: { key: value } (null clears one) — the rest of custom is kept.
approval_notestring
With a move to a stage a manager approves: the note sent with the request.
Request
curl -X PATCH "https://app.meetzy.ai/api/v1/deals/e43414d6-f56f-42be-a64c-a836d6015efc" \
  -H "Authorization: Bearer $MEETZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "won",
    "won_reason": "Best integration with SAP"
  }'
const res = await fetch("https://app.meetzy.ai/api/v1/deals/e43414d6-f56f-42be-a64c-a836d6015efc", {
  method: "PATCH",
  headers: { Authorization: `Bearer ${process.env.MEETZY_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "status": "won",
    "won_reason": "Best integration with SAP"
  }),
});
const data = await res.json();
import os, requests

res = requests.patch(
    "https://app.meetzy.ai/api/v1/deals/e43414d6-f56f-42be-a64c-a836d6015efc",
    headers={"Authorization": f"Bearer {os.environ['MEETZY_API_KEY']}"},
    json={
        "status": "won",
        "won_reason": "Best integration with SAP"
    },
)
data = res.json()
Response200
{
  "id": "d74acfa5-9877-4d7f-a369-3a505bac042a",
  "user_from": "acme",
  "name": "Payfit — rollout",
  "pipeline_id": "cacafee6-6c63-407f-a948-5d6570c20143",
  "stage_id": "proposal",
  "status": "open",
  "amount": 12000,
  "currency": "EUR",
  "probability": null,
  "close_date": "2026-11-06",
  "owner_email": "olivia@acme.com",
  "company_id": "166c436d-a874-4730-a0d8-c8d7fa090268",
  "primary_lead_id": "8028ff76-1da4-451f-a0e7-dd91db772c20",
  "priority": "medium",
  "deal_type": "new_business",
  "source": null,
  "recurring": false,
  "mrr": null,
  "next_step": null,
  "next_step_date": null,
  "description": null,
  "lost_reason": null,
  "won_reason": null,
  "competitors": [],
  "tags": [],
  "custom": {},
  "stage_entered_at": "2026-10-07T13:22:51.622676+00:00",
  "stage_history": [
    {
      "at": "2026-10-07T13:22:51.622676+00:00",
      "to": "proposal",
      "from": "qualification",
      "days_in_stage": 0.000041483657407407404
    }
  ],
  "closed_at": null,
  "last_activity_at": null,
  "created_by": "olivia@acme.com",
  "created_at": "2026-10-07T13:22:48.038488+00:00",
  "updated_at": "2026-10-07T13:22:51.622676+00:00",
  "stage_name": "Proposal sent",
  "stage_color": "#F59E0B",
  "stage_probability": 60,
  "weighted_amount": 7200,
  "days_in_stage": 0,
  "is_rotting": false,
  "is_overdue": false
}
DELETE/deals/{id}

Delete a deal

Deletes the deal with its line items and contact links.

Scope: delete

Path parameters

idstringrequired
Id of the record (UUID).
Request
curl -X DELETE "https://app.meetzy.ai/api/v1/deals/e43414d6-f56f-42be-a64c-a836d6015efc" \
  -H "Authorization: Bearer $MEETZY_API_KEY"
const res = await fetch("https://app.meetzy.ai/api/v1/deals/e43414d6-f56f-42be-a64c-a836d6015efc", {
  method: "DELETE",
  headers: { Authorization: `Bearer ${process.env.MEETZY_API_KEY}` },
});
const data = await res.json();
import os, requests

res = requests.delete(
    "https://app.meetzy.ai/api/v1/deals/e43414d6-f56f-42be-a64c-a836d6015efc",
    headers={"Authorization": f"Bearer {os.environ['MEETZY_API_KEY']}"},
)
data = res.json()
Response200
{
  "deleted": true
}
PUT/deals/{id}/contacts

Set the contacts of a deal

Replaces the contacts linked to the deal (the buying committee).

Scope: write

Path parameters

idstringrequired
Id of the record (UUID).

Body

contactsobject[]required
Each { lead_id, role } — role is free text (champion, decision_maker, user…).
Request
curl -X PUT "https://app.meetzy.ai/api/v1/deals/e43414d6-f56f-42be-a64c-a836d6015efc/contacts" \
  -H "Authorization: Bearer $MEETZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      {
        "lead_id": "e43414d6-f56f-42be-a64c-a836d6015efc",
        "role": "champion"
      }
    ]
  }'
const res = await fetch("https://app.meetzy.ai/api/v1/deals/e43414d6-f56f-42be-a64c-a836d6015efc/contacts", {
  method: "PUT",
  headers: { Authorization: `Bearer ${process.env.MEETZY_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "contacts": [
      {
        "lead_id": "e43414d6-f56f-42be-a64c-a836d6015efc",
        "role": "champion"
      }
    ]
  }),
});
const data = await res.json();
import os, requests

res = requests.put(
    "https://app.meetzy.ai/api/v1/deals/e43414d6-f56f-42be-a64c-a836d6015efc/contacts",
    headers={"Authorization": f"Bearer {os.environ['MEETZY_API_KEY']}"},
    json={
        "contacts": [
            {
                "lead_id": "e43414d6-f56f-42be-a64c-a836d6015efc",
                "role": "champion"
            }
        ]
    },
)
data = res.json()
Response200
{
  "linked": 1
}
PUT/deals/{id}/line-items

Set the line items of a deal

Replaces the products of the deal. The amount and MRR are recomputed unless sync_amount is false. Each line: name, quantity, unit_price, optional product_id, discount_pct, tax_pct, billing (one_time, monthly, yearly).

Scope: write

Path parameters

idstringrequired
Id of the record (UUID).

Body

line_itemsobject[]required
Products of the deal.
sync_amountboolean
Recompute amount and mrr from the lines. Default true.
Request
curl -X PUT "https://app.meetzy.ai/api/v1/deals/e43414d6-f56f-42be-a64c-a836d6015efc/line-items" \
  -H "Authorization: Bearer $MEETZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "line_items": [
      {
        "product_id": "0f6b1c2a-7d84-4b1e-9e0a-3c5d7e9f1a2b",
        "name": "Licence",
        "quantity": 12,
        "unit_price": 1000,
        "discount_pct": 10,
        "billing": "yearly"
      }
    ]
  }'
const res = await fetch("https://app.meetzy.ai/api/v1/deals/e43414d6-f56f-42be-a64c-a836d6015efc/line-items", {
  method: "PUT",
  headers: { Authorization: `Bearer ${process.env.MEETZY_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "line_items": [
      {
        "product_id": "0f6b1c2a-7d84-4b1e-9e0a-3c5d7e9f1a2b",
        "name": "Licence",
        "quantity": 12,
        "unit_price": 1000,
        "discount_pct": 10,
        "billing": "yearly"
      }
    ]
  }),
});
const data = await res.json();
import os, requests

res = requests.put(
    "https://app.meetzy.ai/api/v1/deals/e43414d6-f56f-42be-a64c-a836d6015efc/line-items",
    headers={"Authorization": f"Bearer {os.environ['MEETZY_API_KEY']}"},
    json={
        "line_items": [
            {
                "product_id": "0f6b1c2a-7d84-4b1e-9e0a-3c5d7e9f1a2b",
                "name": "Licence",
                "quantity": 12,
                "unit_price": 1000,
                "discount_pct": 10,
                "billing": "yearly"
            }
        ]
    },
)
data = res.json()
Response200
{
  "items": 1
}
GET/deals/{id}/history

Stage history and changes of a deal

timeline: every stage the deal went through — { stage_id, name, entered_first, entered_last, exited_last, days (in all, revisits added up), visits, current }. history: every change, newest first — stage_change rows (metadata.from, metadata.to) and property_change rows (metadata.changes: [{ field, label, from, to }]), each with actor_email and occurred_at.

Scope: read

Path parameters

idstringrequired
Id of the record (UUID).
Request
curl "https://app.meetzy.ai/api/v1/deals/e43414d6-f56f-42be-a64c-a836d6015efc/history" \
  -H "Authorization: Bearer $MEETZY_API_KEY"
const res = await fetch("https://app.meetzy.ai/api/v1/deals/e43414d6-f56f-42be-a64c-a836d6015efc/history", {
  headers: { Authorization: `Bearer ${process.env.MEETZY_API_KEY}` },
});
const data = await res.json();
import os, requests

res = requests.get(
    "https://app.meetzy.ai/api/v1/deals/e43414d6-f56f-42be-a64c-a836d6015efc/history",
    headers={"Authorization": f"Bearer {os.environ['MEETZY_API_KEY']}"},
)
data = res.json()
Response200
{
  "timeline": [
    {
      "stage_id": "qualified",
      "name": "Qualified",
      "entered_first": "2026-09-02T10:00:00Z",
      "entered_last": "2026-09-02T10:00:00Z",
      "exited_last": "2026-09-15T08:12:00Z",
      "days": 12.9,
      "visits": 1,
      "current": false
    },
    {
      "stage_id": "proposal",
      "name": "Proposal sent",
      "entered_first": "2026-09-15T08:12:00Z",
      "entered_last": "2026-09-15T08:12:00Z",
      "exited_last": null,
      "days": 41.2,
      "visits": 1,
      "current": true
    }
  ],
  "history": [
    {
      "id": "…",
      "type": "property_change",
      "actor_email": "lea@acme.com",
      "occurred_at": "2026-10-20T09:30:00Z",
      "metadata": {
        "changes": [
          {
            "field": "close_date",
            "label": "Close date",
            "from": "2026-10-31",
            "to": "2026-11-30"
          }
        ]
      }
    }
  ]
}
GET/deals/insights

Where deals get stuck

For each pipeline: every open stage with how many deals reached it, the share that moved further once they left it (conversion, moved_on, lost_here, decided), the days they spent there (avg_days, median_days), the deals there now (open, open_value, stuck); totals (win rate, average won deal, sales cycle average and median, pipeline velocity per day, close dates pushed back), lost_reasons and won_reasons ({ reason, count, value }), and the open deals whose close date slipping most. Amounts in the home currency.

Scope: read

Query parameters

pipeline_iduuid
One pipeline, or several separated by commas (default: the default pipeline).
daysinteger
Deals created or closed in the last N days, plus every open deal (30–1095, default 365).
ownerstring
Only this owner’s deals.
Request
curl "https://app.meetzy.ai/api/v1/deals/insights" \
  -H "Authorization: Bearer $MEETZY_API_KEY"
const res = await fetch("https://app.meetzy.ai/api/v1/deals/insights", {
  headers: { Authorization: `Bearer ${process.env.MEETZY_API_KEY}` },
});
const data = await res.json();
import os, requests

res = requests.get(
    "https://app.meetzy.ai/api/v1/deals/insights",
    headers={"Authorization": f"Bearer {os.environ['MEETZY_API_KEY']}"},
)
data = res.json()
Response200
{
  "days": 365,
  "home": "EUR",
  "pipelines": [
    {
      "pipeline": {
        "id": "…",
        "name": "Sales pipeline"
      },
      "stages": [
        {
          "id": "proposal",
          "name": "Proposal sent",
          "reached": 15,
          "moved_on": 9,
          "lost_here": 3,
          "decided": 12,
          "conversion": 75,
          "avg_days": 28.6,
          "median_days": 24,
          "open": 3,
          "open_value": 182000,
          "stuck": 1
        }
      ],
      "totals": {
        "open": 70,
        "open_value": 2076946,
        "won": 18,
        "won_value": 939500,
        "lost": 6,
        "win_rate": 75,
        "avg_won": 52194.44,
        "cycle_avg": 47.8,
        "cycle_median": 48.5,
        "velocity_per_day": 57353.2,
        "pushed": 4,
        "pushes": 6
      },
      "lost_reasons": [
        {
          "reason": "Chose a competitor",
          "count": 3,
          "value": 115500
        }
      ],
      "won_reasons": [],
      "slipping": []
    }
  ]
}
GET/deals/approvals

Deals waiting for approval

Deals whose move into a stage waits for a manager: approval gives stage_id, stage_name, requested_by, requested_at, note and patch (what the move changes once approved). can_approve: whether the key’s user is the owner or an admin of the workspace.

Scope: read
Request
curl "https://app.meetzy.ai/api/v1/deals/approvals" \
  -H "Authorization: Bearer $MEETZY_API_KEY"
const res = await fetch("https://app.meetzy.ai/api/v1/deals/approvals", {
  headers: { Authorization: `Bearer ${process.env.MEETZY_API_KEY}` },
});
const data = await res.json();
import os, requests

res = requests.get(
    "https://app.meetzy.ai/api/v1/deals/approvals",
    headers={"Authorization": f"Bearer {os.environ['MEETZY_API_KEY']}"},
)
data = res.json()
Response200
{
  "approvals": [
    {
      "id": "…",
      "name": "Tidewater — Q4 restock",
      "amount": 128000,
      "currency": "EUR",
      "company_name": "Tidewater Foods",
      "approval": {
        "status": "pending",
        "stage_id": "won",
        "stage_name": "Closed won",
        "requested_by": "lea@acme.com",
        "requested_at": "2026-10-26T09:00:00Z",
        "note": "Signed PO attached",
        "patch": {
          "stage_id": "won",
          "status": "won",
          "won_reason": "Best value for the price"
        }
      }
    }
  ],
  "can_approve": true
}
POST/deals/{id}/approval

Approve or reject a move

For the owner or an admin of the workspace. approve applies the move as it was asked (stage, outcome, reason, fields the stage required) and tells the requester, the owner and the followers; reject leaves the deal where it is. Starts the deal.approved / deal.rejected workflows and webhooks.

Scope: write

Path parameters

idstringrequired
Id of the record (UUID).

Body

decisionstringrequired
approve or reject.
notestring
A note for the requester.
Request
curl -X POST "https://app.meetzy.ai/api/v1/deals/e43414d6-f56f-42be-a64c-a836d6015efc/approval" \
  -H "Authorization: Bearer $MEETZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "decision": "approve",
    "note": "OK — margin checked"
  }'
const res = await fetch("https://app.meetzy.ai/api/v1/deals/e43414d6-f56f-42be-a64c-a836d6015efc/approval", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.MEETZY_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "decision": "approve",
    "note": "OK — margin checked"
  }),
});
const data = await res.json();
import os, requests

res = requests.post(
    "https://app.meetzy.ai/api/v1/deals/e43414d6-f56f-42be-a64c-a836d6015efc/approval",
    headers={"Authorization": f"Bearer {os.environ['MEETZY_API_KEY']}"},
    json={
        "decision": "approve",
        "note": "OK — margin checked"
    },
)
data = res.json()
Response201

Empty answer.

DELETE/deals/{id}/approval

Withdraw an approval request

By who asked, or a manager. The deal stays where it is.

Scope: delete

Path parameters

idstringrequired
Id of the record (UUID).
Request
curl -X DELETE "https://app.meetzy.ai/api/v1/deals/e43414d6-f56f-42be-a64c-a836d6015efc/approval" \
  -H "Authorization: Bearer $MEETZY_API_KEY"
const res = await fetch("https://app.meetzy.ai/api/v1/deals/e43414d6-f56f-42be-a64c-a836d6015efc/approval", {
  method: "DELETE",
  headers: { Authorization: `Bearer ${process.env.MEETZY_API_KEY}` },
});
const data = await res.json();
import os, requests

res = requests.delete(
    "https://app.meetzy.ai/api/v1/deals/e43414d6-f56f-42be-a64c-a836d6015efc/approval",
    headers={"Authorization": f"Bearer {os.environ['MEETZY_API_KEY']}"},
)
data = res.json()
Response200

Empty answer.

GET/forecast/team

Team forecast and quotas

Each salesperson’s month or quarter: quota (their revenue_won goals brought to the period), won, commit, best_case, pipeline (open deals closing in the period, by forecast category; omitted deals left out; a split deal counts for each person at their share), projected (won + commit), submission (the number they submitted, with note, submitted_at and earlier numbers in history), gap (quota minus the submitted number, else the projection) and attainment (won ÷ quota); total.forecast adds each person’s submitted number, else their projection. Amounts in the home currency.

Scope: read

Query parameters

periodstring
2026-11 (a month) or 2026-Q4 (a quarter). Default: this month.
kindstring
quarter: this quarter when no period is given.
Request
curl "https://app.meetzy.ai/api/v1/forecast/team" \
  -H "Authorization: Bearer $MEETZY_API_KEY"
const res = await fetch("https://app.meetzy.ai/api/v1/forecast/team", {
  headers: { Authorization: `Bearer ${process.env.MEETZY_API_KEY}` },
});
const data = await res.json();
import os, requests

res = requests.get(
    "https://app.meetzy.ai/api/v1/forecast/team",
    headers={"Authorization": f"Bearer {os.environ['MEETZY_API_KEY']}"},
)
data = res.json()
Response200
{
  "period": "2026-10",
  "kind": "month",
  "start": "2026-10-01",
  "end": "2026-10-31",
  "home": "EUR",
  "me": "lea@acme.com",
  "can_submit_for_others": false,
  "rows": [
    {
      "email": "lea@acme.com",
      "name": "Léa Martin",
      "quota": 80000,
      "won": 52000,
      "commit": 21000,
      "best_case": 14000,
      "pipeline": 30000,
      "deals": 9,
      "projected": 73000,
      "submission": {
        "amount": 75000,
        "note": "Tidewater signs on the 28th",
        "submitted_at": "2026-10-20T08:00:00Z",
        "history": []
      },
      "gap": 5000,
      "attainment": 65
    }
  ],
  "total": {
    "quota": 240000,
    "won": 152000,
    "commit": 61000,
    "best_case": 40000,
    "pipeline": 90000,
    "projected": 213000,
    "submitted": 75000,
    "submissions": 1,
    "people": 3,
    "forecast": 218000
  }
}
PUT/forecast/submissions

Submit a forecast

The number a salesperson commits to for a month or a quarter (replaces their earlier one, kept in history). Someone else’s only by the owner or an admin of the workspace.

Scope: write

Body

periodstringrequired
2026-11 or 2026-Q4.
amountnumberrequired
The number, in the home currency.
notestring
Why.
owner_emailstring
Whose forecast (default: the key’s user).
Request
curl -X PUT "https://app.meetzy.ai/api/v1/forecast/submissions" \
  -H "Authorization: Bearer $MEETZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "period": "2026-11",
    "amount": 75000,
    "note": "Tidewater signs on the 20th"
  }'
const res = await fetch("https://app.meetzy.ai/api/v1/forecast/submissions", {
  method: "PUT",
  headers: { Authorization: `Bearer ${process.env.MEETZY_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "period": "2026-11",
    "amount": 75000,
    "note": "Tidewater signs on the 20th"
  }),
});
const data = await res.json();
import os, requests

res = requests.put(
    "https://app.meetzy.ai/api/v1/forecast/submissions",
    headers={"Authorization": f"Bearer {os.environ['MEETZY_API_KEY']}"},
    json={
        "period": "2026-11",
        "amount": 75000,
        "note": "Tidewater signs on the 20th"
    },
)
data = res.json()
Response200

Empty answer.

GET/deals/{id}/documents

A deal’s ERP documents

The proforma (the ERP order) and the invoices the deal follows, with the number printed on them, their PDF and where they stand: to_send (waiting for the salesperson), sent (when, to whom, how) or not_needed.

Scope: read

Path parameters

idstringrequired
Id of the record (UUID).
Request
curl "https://app.meetzy.ai/api/v1/deals/e43414d6-f56f-42be-a64c-a836d6015efc/documents" \
  -H "Authorization: Bearer $MEETZY_API_KEY"
const res = await fetch("https://app.meetzy.ai/api/v1/deals/e43414d6-f56f-42be-a64c-a836d6015efc/documents", {
  headers: { Authorization: `Bearer ${process.env.MEETZY_API_KEY}` },
});
const data = await res.json();
import os, requests

res = requests.get(
    "https://app.meetzy.ai/api/v1/deals/e43414d6-f56f-42be-a64c-a836d6015efc/documents",
    headers={"Authorization": f"Bearer {os.environ['MEETZY_API_KEY']}"},
)
data = res.json()
Response200
{
  "documents": [
    {
      "id": "83d62171-1cc8-466a-ad9c-f9fbce63d4bf",
      "doc_type": "invoice",
      "label": "Invoice",
      "number": "46511008",
      "erp_number": "18195",
      "title": "Invoice 46511008",
      "date": "2026-11-09",
      "due_date": "2026-12-09",
      "status": "open",
      "total": 25359.85,
      "net_total": 25359.85,
      "currency": "EUR",
      "source": "sap_b1",
      "file": {
        "name": "Invoice 46511008 - Payfit.pdf",
        "size": 243225,
        "source": "sap",
        "at": "2026-11-09T09:12:03.000Z"
      },
      "state": "to_send",
      "flagged_at": "2026-11-09T09:11:40.000Z",
      "sent_at": null,
      "sent_to": [],
      "sent_via": null,
      "sent_by": null,
      "sent_note": null,
      "waiting_days": 1
    }
  ]
}
POST/deals/{id}/documents/{documentId}

Mark a deal’s document sent, to send or not needed

Says by hand where a proforma or invoice of the deal stands. sent tells the deal (event deal.document_sent: its workflow moves it — Proforma Sent, Invoice Sent).

Scope: write

Path parameters

idstringrequired
Id of the record (UUID).
documentIdstringrequired
Path parameter.

Body

statestringrequired
sent, to_send or not_needed.
tostring[]
Who received it (with sent).
notestring
A word on how it went.
Request
curl -X POST "https://app.meetzy.ai/api/v1/deals/e43414d6-f56f-42be-a64c-a836d6015efc/documents/%7BdocumentId%7D" \
  -H "Authorization: Bearer $MEETZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "sent",
    "to": [
      "buyer@payfit.com"
    ]
  }'
const res = await fetch("https://app.meetzy.ai/api/v1/deals/e43414d6-f56f-42be-a64c-a836d6015efc/documents/%7BdocumentId%7D", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.MEETZY_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "state": "sent",
    "to": [
      "buyer@payfit.com"
    ]
  }),
});
const data = await res.json();
import os, requests

res = requests.post(
    "https://app.meetzy.ai/api/v1/deals/e43414d6-f56f-42be-a64c-a836d6015efc/documents/%7BdocumentId%7D",
    headers={"Authorization": f"Bearer {os.environ['MEETZY_API_KEY']}"},
    json={
        "state": "sent",
        "to": ["buyer@payfit.com"]
    },
)
data = res.json()
Response201
{
  "sent": [
    {
      "id": "83d62171-1cc8-466a-ad9c-f9fbce63d4bf",
      "title": "Invoice 46511008"
    }
  ],
  "detail": "sent: Invoice 46511008"
}