Create, list, update, and delete deals in the MisarReach pipeline — api.misar.io/reach/api/deals.

Deals represent sales opportunities tracked in the MisarReach Kanban pipeline. Each deal is linked to a lead (by email), and optionally to a conversation, campaign, or contact.

Base URL: https://api.misar.io/reach

List deals

GET/api/deals

Returns a paginated list of deals for the authenticated user, with a revenue summary. Required scope: deals:read.

Query parameters

statusstringquery

Filter by deal status. One of: "interested" | "meeting" | "proposal" | "closed" | "lost".

limitnumberquerydefault: 50

Maximum number of deals to return (1–100).

offsetnumberquerydefault: 0

Pagination offset (number of records to skip).

Response fields

revenue.totalnumber

Sum of value across all deals (any status), in the deal's own currency.

revenue.closednumber

Sum of value for deals with status = "closed".

revenue.pipelinenumber

Sum of value for deals not yet closed or lost.

curl "https://api.misar.io/reach/api/deals?status=proposal&limit=20" \
  -H "Authorization: Bearer msr_your_key_here"

{
  "deals": [
    {
      "id": "uuid",
      "lead_email": "[email protected]",
      "lead_name": "Priya Sharma",
      "value": 15000,
      "currency": "USD",
      "status": "proposal",
      "notes": "Demo scheduled for next Tuesday.",
      "conversation_id": "uuid-or-null",
      "campaign_id": "uuid-or-null",
      "created_at": "2026-05-21T10:00:00Z",
      "closed_at": null
    }
  ],
  "total": 12,
  "revenue": {
    "total": 180000,
    "closed": 45000,
    "pipeline": 135000
  }
}

Create a deal

POST/api/deals

Creates a new deal. Returns the created deal with HTTP 201. New deals are created with status = "new" and stage = "new". Required scope: deals:write.

Request body

leadEmailstringbodyrequired

Lead's email address. Used to identify the contact in the pipeline.

leadNamestringbody

Lead's display name.

valuenumberbodydefault: 0

Deal value in the smallest currency unit (e.g., cents for USD). Non-negative integer.

currencystringbodydefault: USD

ISO 4217 3-letter currency code (e.g., "USD", "EUR", "INR").

notesstringbody

Free-text notes on this deal (max 5,000 characters).

conversationIdstringbody

UUID of a conversation to link this deal to. The conversation's deal_id field is updated automatically.

campaignIdstringbody

UUID of a campaign to associate this deal with.

contactIdstringbody

UUID of a contact record to link.

curl -X POST https://api.misar.io/reach/api/deals \
  -H "Authorization: Bearer msr_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "leadEmail": "[email protected]",
    "leadName": "Priya Sharma",
    "value": 15000,
    "currency": "USD",
    "notes": "Responded positively to cold email. Schedule demo."
  }'

{
  "ok": true,
  "deal": {
    "id": "uuid",
    "status": "new",
    "lead_email": "[email protected]",
    "value": 15000
  }
}

Update a deal

PATCH/api/deals/:id

Updates the status, value, or notes of an existing deal. Only the fields provided in the request body are modified. When status is set to "closed", the closed_at timestamp is automatically set to the current time. Required scope: deals:write.

Path parameters

idstringpathrequired

UUID of the deal to update.

Request body

statusstringbody

New deal status. One of: "interested" | "meeting" | "proposal" | "closed" | "lost".

valuenumberbody

Updated deal value (non-negative integer).

notesstringbody

Updated free-text notes (max 5,000 characters).

curl -X PATCH https://api.misar.io/reach/api/deals/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer msr_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"status": "closed", "notes": "Contract signed."}'

{
  "ok": true,
  "deal": {
    "id": "uuid",
    "status": "closed",
    "value": 15000,
    "lead_email": "[email protected]"
  }
}

Status codes

Code	Meaning
`200`	Deal updated
`400`	Invalid UUID format
`404`	Deal not found or does not belong to the authenticated user
`422`	Validation error in request body

Deal status values

Status	Description
`new`	Default when created. Lead has been identified.
`contacted`	Outreach sent but no reply yet.
`interested`	Lead has responded positively.
`meeting`	A call or demo has been scheduled.
`proposal`	A proposal or quote has been sent.
`closed`	Deal won. `closed_at` is set.
`lost`	Deal lost. Excluded from revenue pipeline totals.

The pipeline board groups deals by stage, which mirrors status. Use POST /api/pipeline to move a deal's stage (e.g., drag-and-drop in the UI). Use PATCH /api/deals/:id to update the status directly via API.

Deals API

List deals

Create a deal

Update a deal

Status codes

Deal status values