DM Champ Docs

Deals API

A deal is one sales opportunity on your Sales Pipeline board — a title, a value, the stage it sits in, and optionally the contact it belongs to and the team member it is assigned to. This guide covers reading and managing deals over the API.

All examples below show the ?apiKey= query form in cURL and the X-API-Key header in JavaScript and Python — either works on every endpoint.

The deal object 

{
  "id": "deal_abc123",
  "title": "Annual plan – Jane's Clinic",
  "description": "Asked for pricing on the annual plan.",
  "company": "Jane's Clinic",
  "stage": "stage-2",
  "value": 4800,
  "probability": 60,
  "priority": "high",
  "status": "open",
  "source": "whatsapp",
  "position": 0,
  "contact_id": "ctc_9f8e7d",
  "assigned_to": "usr_4a2b",
  "tags": ["clinic"],
  "close_date": "2026-10-01T00:00:00.000Z",
  "created_at": "2026-09-05T09:12:00.000Z",
  "updated_at": "2026-09-05T09:40:00.000Z",
  "stage_entered_at": "2026-09-05T09:40:00.000Z"
}

stage is the id of one of your pipeline stages — read them from your pipeline settings (GET /users/me/pipeline-settings). Timestamps are ISO 8601.

List deals

GET /deals — returns the deals on your account, newest first.

Query parameters (all optional): stage (a stage id), contact_id, limit (default 50, max 200), cursor (from the previous page’s next_cursor).

cURL

curl "https://api.dmchamp.com/v1/deals?apiKey=YOUR_API_KEY&stage=stage-2&limit=50"

JavaScript

const res = await fetch("https://api.dmchamp.com/v1/deals?stage=stage-2&limit=50", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { deals, next_cursor } = await res.json();

Python

res = requests.get(
    "https://api.dmchamp.com/v1/deals",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"stage": "stage-2", "limit": 50},
)
deals = res.json()["deals"]

Response (200)

{ "success": true, "deals": [{ "id": "deal_abc123", "title": "Annual plan – Jane's Clinic", "...": "..." }], "next_cursor": null }

Get a deal

GET /deals/{dealId}

curl "https://api.dmchamp.com/v1/deals/deal_abc123?apiKey=YOUR_API_KEY"

Response (200)

{ "success": true, "deal": { "id": "deal_abc123", "title": "Annual plan – Jane's Clinic", "...": "..." } }

A deal that does not exist, or belongs to another account, returns 404.

Create a deal

POST /deals — title and stage are required; stage must be one of your pipeline’s stage ids.

curl -X POST "https://api.dmchamp.com/v1/deals?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Annual plan – Jane'"'"'s Clinic", "stage": "stage-1", "value": 4800, "contact_id": "ctc_9f8e7d" }'

Response (201)

{ "success": true, "deal_id": "deal_abc123" }

Update a deal

PUT /deals/{dealId} — send only the fields you want to change (title, description, value, stage, status, priority, contact_id, …). value must be a number.

curl -X PUT "https://api.dmchamp.com/v1/deals/deal_abc123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "value": 5200, "priority": "high" }'

Response (200): { "success": true, "deal_id": "deal_abc123" }

Move a deal to another stage

POST /deals/{dealId}/move — body { "new_stage_id": "stage-3", "new_position": 0 }. Position 0 puts the card at the top of the column.

curl -X POST "https://api.dmchamp.com/v1/deals/deal_abc123/move?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "new_stage_id": "stage-3", "new_position": 0 }'

Response (200): { "success": true, "deal_id": "deal_abc123", "stage": "stage-3", "position": 0 }

Delete a deal

DELETE /deals/{dealId} — removes the deal. This cannot be undone.

curl -X DELETE "https://api.dmchamp.com/v1/deals/deal_abc123?apiKey=YOUR_API_KEY"

Response (200): { "success": true }

Next steps

  • Sales Pipeline — how stages, stage tags and the board work.
  • Tasks API — tasks can be linked to a deal with deal_id.
  • Automations — the Find deals and Find deal steps read the same data inside a workflow.