Skip to content

Deals

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)

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 }]
Terminal window
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" }]
}'
  • pipelineId defaults to the default pipeline; the stage defaults to its first open stage.
  • stageName (case-insensitive, in the deal’s pipeline) may replace stageId. Unknown → 422 STAGE_NOT_FOUND with details.allowed (the names). A stageId without pipelineId selects that stage’s pipeline; a stage of another pipeline → 422 STAGE_NOT_IN_PIPELINE.
  • organizationIds / contactIds are 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.

Terminal window
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).

Terminal window
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.

Terminal window
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"}'
Terminal window
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.