Deals

A deal is an opportunity inside a stage. It always points to a real Lead — contact data comes from the Lead, it is not copied.

The Deal object

string

Deal UUID

number

integer

Human-readable sequential deal number (e.g. 1042)

pipeline_id

string

Pipeline UUID

stage_id

string

UUID of the current stage

lead_id

string

UUID of the linked Lead

owner_id

string

UUID of the responsible user, or null

value

number

Manual deal value. Only used when the deal has no products.

total

number

Calculated total: the sum of price × qty of the products, or value when there are no products

origin

string

Deal origin (manual by default)

loss_reason

string

Loss reason. Present only on lost deals.

note

string

Free-form note

won_at

string

Date it entered the won stage (ISO 8601)

lost_at

string

Date it entered the lost stage (ISO 8601)

lead_name

string

Name of the linked Lead (resolved at read time)

lead_surname

string

Lead’s surname

lead_company

string

Lead’s company

lead_email

string

Lead’s email

lead_phone

string

Lead’s phone

lead_avatar

string

URL of the Lead’s avatar

lead_status_id

string

UUID of the Lead’s status

products

DealProduct[]

The deal’s product lines

Board

GET /backend/pipelines/{id}/board

Returns the board metadata: the pipeline with its stages and, per column, the deal count and the money total. It does not return the deals themselves — use List deals to load each column.

Query Parameters

string

Search by deal number or by the linked Lead’s name/company

stage_id

string

Restrict to a specific stage

sort

string

default:"recent"

recent (newest first) or oldest

mode

string

default:"created"

Which date the period filter considers: created, won or lost

period

string

7d, 30d, 1y or custom. With custom, also provide from and to.

from

string

Start of the period (ISO 8601). Used only with period=custom.

string

End of the period (ISO 8601). Used only with period=custom.

{
  "pipeline": {
    "id": "bb0e8400-e29b-41d4-a716-446655440000",
    "group_id": "aa0e8400-e29b-41d4-a716-446655440000",
    "name": "Inbound Sales",
    "description": "Leads coming from the website",
    "position": 0,
    "stages": [
      { "id": "cc0e8400-e29b-41d4-a716-446655440000", "name": "Entrada", "color": "217 91% 60%", "position": 0 }
    ],
    "loss_reasons": ["Sem orçamento"],
    "created_at": "2026-07-16T09:00:00Z"
  },
  "stages": [
    {
      "stage": { "id": "cc0e8400-e29b-41d4-a716-446655440000", "name": "Entrada", "color": "217 91% 60%", "position": 0 },
      "deal_count": 12,
      "total": 48500.00
    }
  ],
  "total_deals": 12,
  "total_amount": 48500.00
}

List deals

GET /backend/pipelines/{id}/deals

Returns a page of deals. The board paginates per column — pass stage_id to load one stage at a time instead of the whole pipeline.

Query Parameters

Accepts every filter of the board, plus:

page

integer

default:"1"

Desired page

limit

integer

default:"20"

Items per page. Values outside 1–100 fall back to the default of 20.

curl -X GET "https://api.leavo.ai/backend/pipelines/bb0e8400-e29b-41d4-a716-446655440000/deals?stage_id=cc0e8400-e29b-41d4-a716-446655440000&limit=20" \
  -H "Authorization: Bearer your_api_key_here"

const params = new URLSearchParams({
  stage_id: 'cc0e8400-e29b-41d4-a716-446655440000',
  limit: '20'
});

const response = await fetch(
  `https://api.leavo.ai/backend/pipelines/bb0e8400-e29b-41d4-a716-446655440000/deals?${params}`,
  { headers: { 'Authorization': 'Bearer your_api_key_here' } }
);

{
  "data": [
    {
      "id": "dd0e8400-e29b-41d4-a716-446655440000",
      "number": 1042,
      "pipeline_id": "bb0e8400-e29b-41d4-a716-446655440000",
      "stage_id": "cc0e8400-e29b-41d4-a716-446655440000",
      "lead_id": "550e8400-e29b-41d4-a716-446655440000",
      "owner_id": null,
      "value": 0,
      "total": 4500.00,
      "origin": "manual",
      "note": "",
      "created_at": "2026-07-16T09:30:00Z",
      "updated_at": "2026-07-16T09:30:00Z",
      "lead_name": "John Smith",
      "lead_company": "XYZ Company",
      "lead_email": "john@example.com",
      "lead_phone": "+15551234567",
      "products": [
        {
          "id": "ee0e8400-e29b-41d4-a716-446655440000",
          "product_id": "ff0e8400-e29b-41d4-a716-446655440000",
          "name": "Premium Plan",
          "price": 1500.00,
          "qty": 3,
          "custom": false,
          "total": 4500.00
        }
      ],
      "tags": [],
      "pending_todos": 1,
      "overdue_todos": 0
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 1,
    "total_count": 12,
    "has_next": false,
    "has_prev": false
  }
}

Get a deal

GET /backend/pipeline/deals/{id}

Returns the full deal, with products, tags and Lead data.

Create a deal

POST /backend/pipeline/deals

Requires the pipeline.deals.create permission.

Request Body

pipeline_id

string

required

Pipeline UUID

stage_id

string

required

UUID of the initial stage. It must belong to the given pipeline, otherwise the response is 400.

lead_id

string

UUID of an existing Lead

new_lead

object

Data to create a new Lead along with the deal

Show new_lead properties

name

string

required

Lead name

phone

string

required

Lead phone

string

Lead email

company

string

Lead company

Provide lead_id or new_lead. Without either one, the response is 400 — a deal never exists without a Lead.

owner_id

string

UUID of the responsible user

loss_reason

string

Loss reason. Required when stage_id points to the lost stage.

lead_status_id

string

Status to apply to the linked Lead

products

DealProduct[]

The deal’s product lines

Show Product line properties

product_id

string

UUID of a catalog product. Name and price are copied at the moment it is added.

name

string

Name of the one-off line. Required when custom is true.

price

number

Unit price. Cannot be negative.

qty

integer

Quantity. Values lower than 1 are treated as 1.

custom

boolean

true for a one-off line, which exists only in this deal and does not enter the global catalog

tag_ids

string[]

UUIDs of tags to associate

origin

string

Deal origin. Default: manual.

curl -X POST "https://api.leavo.ai/backend/pipeline/deals" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "pipeline_id": "bb0e8400-e29b-41d4-a716-446655440000",
    "stage_id": "cc0e8400-e29b-41d4-a716-446655440000",
    "lead_id": "550e8400-e29b-41d4-a716-446655440000",
    "products": [
      { "product_id": "ff0e8400-e29b-41d4-a716-446655440000", "qty": 3 },
      { "custom": true, "name": "Onboarding", "price": 800.00, "qty": 1 }
    ],
    "tag_ids": ["880e8400-e29b-41d4-a716-446655440000"]
  }'

const response = await fetch('https://api.leavo.ai/backend/pipeline/deals', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your_api_key_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    pipeline_id: 'bb0e8400-e29b-41d4-a716-446655440000',
    stage_id: 'cc0e8400-e29b-41d4-a716-446655440000',
    new_lead: {
      name: 'Mary Jones',
      phone: '+15557778888',
      company: 'ACME'
    }
  })
});

Returns 201 Created with the deal.

Update a deal

PUT /backend/pipeline/deals/{id}

Requires pipeline.deals.edit. Omitted fields stay unchanged.

Request Body

owner_id

string

New owner

value

number

Manual value. Cannot be negative. Only affects total when the deal has no products.

note

string

Note

origin

string

Origin

products

DealProduct[]

When sent, it replaces the entire list of products. Send [] to remove them all.

The stage is not changed by this endpoint. Use Move between stages.

Move between stages

PUT /backend/pipeline/deals/{id}/stage

Moves the deal between board columns. Requires pipeline.deals.edit.

Request Body

stage_id

string

required

UUID of the destination stage. It must belong to the same pipeline as the deal, otherwise the response is 400.

loss_reason

string

Loss reason. Required when the destination stage has kind: "lost".

Moving to the lost stage without loss_reason returns 400. There is no path that loses a deal silently.

Side effects of moving. Every move always clears won_at and lost_at first before applying the destination, so pulling a deal out of Won/Lost discards the marking with it:

Destination	Effect
`kind: "won"`	Sets `won_at`; `lost_at` and `loss_reason` become null
`kind: "lost"`	Sets `lost_at` and records `loss_reason`; `won_at` becomes null
Regular stage	`won_at`, `lost_at` and `loss_reason` become null

The reason can be one of the loss_reasons configured on the pipeline or free text — the “Other” option is not stored in the list of reasons.

curl -X PUT "https://api.leavo.ai/backend/pipeline/deals/dd0e8400-e29b-41d4-a716-446655440000/stage" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "stage_id": "cc3e8400-e29b-41d4-a716-446655440000",
    "loss_reason": "Fechou com concorrente"
  }'

{
  "code": "ERR_INVALID_INPUT",
  "message": "Informe o motivo da perda para marcar o negócio como perdido"
}

Error message strings are returned by the API in Portuguese. Match on code (ERR_INVALID_INPUT), never on the message text.

Deal tags

Deal tags reuse the same tag catalog as Leads — there is no separate catalog.

Add a tag

POST /backend/pipeline/deals/{id}/tags/{tagID}

Remove a tag

DELETE /backend/pipeline/deals/{id}/tags/{tagID}

Both require pipeline.deals.edit and return { "success": true }.

Delete a deal

DELETE /backend/pipeline/deals/{id}

Requires pipeline.deals.delete.

Deletes the deal and everything hanging off it: products, tags, activities, files and history. The linked Lead is not deleted.

{ "success": true }

Overview

Leads

Status

Tags

Pipeline (CRM)

Webhooks

Custom Fields

Cadences

Conversations

Messages

Departments

File Uploads

Templates (Meta/Gupshup)

Follow-up

The Deal object

Board

Query Parameters

List deals

Query Parameters

Get a deal

Create a deal

Request Body

Update a deal

Request Body

Move between stages

Request Body

Deal tags

Add a tag

Remove a tag

Delete a deal

​The Deal object

​Board

​Query Parameters

​List deals

​Query Parameters

​Get a deal

​Create a deal

​Request Body

​Update a deal

​Request Body

​Move between stages

​Request Body

​Deal tags

​Add a tag

​Remove a tag

​Delete a deal

The Deal object

Board

Query Parameters

List deals

Query Parameters

Get a deal

Create a deal

Request Body

Update a deal

Request Body

Move between stages

Request Body

Deal tags

Add a tag

Remove a tag

Delete a deal