Deals
Endpoints
Section titled “Endpoints”| Method & path | Scope | Notes |
|---|---|---|
GET /deals |
records:read |
Page list with filters; shortcuts pipelineId, stageId, organizationId, contactId |
POST /deals |
records:write |
Create → 201 |
POST /deals/upsert |
records:write |
Up to 100 items by externalRef:<system> or id |
GET /deals/:id |
records:read |
The full deal |
PATCH /deals/:id |
records:write |
Partial; a stage change here has the same effect as a move |
POST /deals/:id/move |
records:write |
{ stageId, position?, version?, lostReason? } → 200 (also stageName) |
DELETE /deals/:id |
records:delete |
Hard delete → 204 |
PUT /deals/:id/organizations/:organizationId |
records:write |
{ role?, isPrimary? } |
DELETE /deals/:id/organizations/:organizationId |
records:write |
204 |
PUT /deals/:id/contacts/:contactId |
records:write |
{ role? } |
DELETE /deals/:id/contacts/:contactId |
records:write |
204 |
GET /deals/:id/timeline |
records:read |
Its activities |
GET /deals/:id/history |
records:read |
Audit events |
GET /pipelines/:id/board |
records:read |
The Kanban board (pipelines) |
The object
Section titled “The object”Common fields plus:
| Field | Notes |
|---|---|
name |
Required |
pipelineId, stageId, stage |
stage: { id, name, outcome, probability } |
amountCents |
Integer ≥ 0, default 0. The total for one_off; the amount per billing interval for recurring |
currency |
ISO 4217, default the account’s baseCurrency |
revenueType |
one_off (default) or recurring |
billingInterval |
month or year, required for recurring; null for one-off |
mrrCents, arrCents |
Derived: monthly amount, or round_half_even(amountCents / 12) for yearly; arrCents = 12 × mrrCents; 0 for one-off |
expectedCloseOn |
YYYY-MM-DD |
closedAt |
Set when entering a won or lost stage, cleared on an open stage |
lostReason |
Only in a lost stage (else 400) |
stageEnteredAt |
Set on every stage change |
lastActivityAt |
Read only |
position |
0-based place in the stage column |
description, ownerUserId |
|
organizations |
[{ organizationId, name, domain, role, isPrimary }] |
contacts |
[{ contactId, fullName, email, role }] |
Create
Section titled “Create”curl -s -X POST https://api.mety.ai/api/v1/deals \ -H "Authorization: Bearer $METY_KEY" -H "Content-Type: application/json" \ -H "Idempotency-Key: deal-acme-annual" \ -d '{ "name": "Acme · annual licence", "stageName": "Proposal", "amountCents": 480000, "currency": "EUR", "revenueType": "recurring", "billingInterval": "year", "expectedCloseOn": "2026-12-15", "organizations": [{ "organizationId": "'"$ORG_ID"'" }], "contacts": [{ "contactId": "'"$CONTACT_ID"'", "role": "decision maker" }] }'pipelineIddefaults to the default pipeline; the stage defaults to its first open stage.stageName(case-insensitive, in the deal’s pipeline) may replacestageId. Unknown →422 STAGE_NOT_FOUNDwithdetails.allowed(the names). AstageIdwithoutpipelineIdselects that stage’s pipeline; a stage of another pipeline →422 STAGE_NOT_IN_PIPELINE.organizationIds/contactIdsare shortcuts without roles. The first organization becomes primary.- Also accepted:
description,ownerUserId,tags,customFields,externalRefs.
This deal is 4 800 € a year: mrrCents 40 000, arrCents 480 000.
curl -s -X POST https://api.mety.ai/api/v1/deals/$DEAL_ID/move \ -H "Authorization: Bearer $METY_KEY" -H "Content-Type: application/json" \ -d '{"stageName":"Lost","lostReason":"Chose a competitor","version":5}'position is the 0-based index among the other active cards of the target stage (default: the end on a stage
change). Entering won or lost sets closedAt; entering an open stage clears closedAt and lostReason.
PATCH /deals/:id can also change stageId / stageName, and pipelineId (then a stage is required).
Upsert by external reference
Section titled “Upsert by external reference”curl -s -X POST https://api.mety.ai/api/v1/deals/upsert \ -H "Authorization: Bearer $METY_KEY" -H "Content-Type: application/json" \ -H "Idempotency-Key: gmail:THREAD_ID:deal" \ -d '{ "matchOn": "externalRef:gmail", "items": [{ "name": "Acme · annual licence", "externalRefs": { "gmail": "THREAD_ID" }, "stageName": "Proposal", "amountCents": 480000, "revenueType": "recurring", "billingInterval": "year", "organizations": [{ "organizationId": "'"$ORG_ID"'" }] }] }'Re-running updates the same deal. Several deals with the same ref → item error 409 AMBIGUOUS_MATCH.
curl -s -X PUT https://api.mety.ai/api/v1/deals/$DEAL_ID/organizations/$PARTNER_ORG_ID \ -H "Authorization: Bearer $METY_KEY" -H "Content-Type: application/json" -d '{"role":"partner"}'
curl -s -X PUT https://api.mety.ai/api/v1/deals/$DEAL_ID/contacts/$CONTACT_ID \ -H "Authorization: Bearer $METY_KEY" -H "Content-Type: application/json" -d '{"role":"champion"}'List: deals closing in the next 14 days
Section titled “List: deals closing in the next 14 days”curl -sg "https://api.mety.ai/api/v1/deals?filter[stage.outcome][eq]=open&filter[expectedCloseOn][lte]=today%2B14d&sort=expectedCloseOn:asc" \ -H "Authorization: Bearer $METY_KEY"today%2B14d is today+14d URL-encoded: in a query string a bare + means a space.