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

integer

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

string

Pipeline UUID

string

UUID of the current stage

string

UUID of the linked Lead

string

UUID of the responsible user, or null

number

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

number

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

string

Deal origin (manual by default)

string

Loss reason. Present only on lost deals.

string

Free-form note

string

Date it entered the won stage (ISO 8601)

string

Date it entered the lost stage (ISO 8601)

string

Name of the linked Lead (resolved at read time)

string

Lead’s surname

string

Lead’s company

string

Lead’s email

string

Lead’s phone

string

URL of the Lead’s avatar

string

UUID of the Lead’s status

DealProduct[]

The deal’s product lines

Tag[]

Deal tags — they reuse the same tag catalog as Leads

integer

Number of pending activities

integer

Number of activities that are pending and overdue

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

string

Restrict to a specific stage

string

default:"recent"

recent (newest first) or oldest

string

default:"created"

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

string

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

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:

integer

default:"1"

Desired page

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

string

required

Pipeline UUID

string

required

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

string

UUID of an existing Lead

object

Data to create a new Lead along with the deal

Show new_lead properties

string

required

Lead name

string

required

Lead phone

string

Lead email

string

Lead company

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

string

UUID of the responsible user

string

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

string

Status to apply to the linked Lead

DealProduct[]

The deal’s product lines

Show Product line properties

string

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

string

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

number

Unit price. Cannot be negative.

integer

Quantity. Values lower than 1 are treated as 1.

boolean

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

string[]

UUIDs of tags to associate

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

string

New owner

number

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

string

Note

string

Origin

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

string

required

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

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

Knowledge Base

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