Pular para o conteúdo

POST /v1/deals/search

POST
/v1/deals/search
curl --request POST \
--url https://seu-endereco-da-api/v1/deals/search \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "status": "open", "sort": "moved_oldest", "interval": "7d", "q": "example", "stageId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "outcome": "won", "closedPeriod": "7d", "closedFrom": "example", "closedTo": "example", "createdPeriod": "all", "createdFrom": "example", "createdTo": "example", "cursor": "example", "limit": 1, "pipelineId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "filter": {} }'

Permissão que a Chave de acesso precisa: Ler negócios (deals:read).

Media typeapplication/json
object
status
string
Allowed values: open won lost all
sort
string
Allowed values: moved_oldest moved_newest created_newest created_oldest value_desc value_asc next_activity
interval
string
Allowed values: 7d 30d 90d 1y all
q
string
<= 200 characters
stageId
string format: uuid
outcome
string
Allowed values: won lost
closedPeriod
string
Allowed values: 7d 30d 90d month all custom
closedFrom
string
closedTo
string
createdPeriod
string
Allowed values: all 7d 30d 90d custom
createdFrom
string
createdTo
string
cursor
string
limit
number
>= 1
pipelineId
required
string format: uuid
filter
object
key
additional properties
any
Media typeapplication/json
object
columns
required
Array<object>
object
stageId
required
string
count
required

Deals in the stage that match the view, beyond the page

number
valueCents
required

Sum in centavos of the same deals

number
counters
required

Counted on the server within what the caller sees and the board filter

object
stale
required

Deals of the column the filter parado would return

number
overdueTask
required

Deals of the column the filter tarefa overdue would return

number
awaitingReply
required

Deals of the column the filter resposta esperando would return

number
items
required
Array<object>
object
id
required
string
number
required

Sequential per tenant, shown as #número

number
title
required
string
nullable
status
required
string
Allowed values: open won lost
valueCents
required
number
stageId
required
string
stageEnteredAt
required
string format: date-time
createdAt
required
string format: date-time
expectedCloseAt
required

Data prevista de fechamento

string format: date-time
nullable
wonAt
required
string format: date-time
nullable
lostAt
required
string format: date-time
nullable
lossReason
required
object
id
required
string
name
required
string
winReason
required
object
id
required
string
name
required
string
intake
required

Filled only while the deal sits in the intake stage

object
firstMessage
required

First inbound message of the conversation that opened the lead

string
nullable
receivedAt
required
string format: date-time
source
required
string
Allowed values: inbound_message ad form
originName
required
string
nullable
servedBy
required

Who is serving the conversation, when someone is

object
id
required
string
name
required
string
nullable
waitingDays
required

Whole days since the lead arrived

number
contactBlocked
required

The lead’s contact is blocked; accept and restore refuse it until it is unblocked

boolean
contact
required
object
id
required
string
name
required
string
channel
required

Channel key derived from the contact’s provider

string
provider
required
string
profilePicUrl
required
string
nullable
origin
required
object
id
required
string
name
required
string
color
required
string
nullable
company
required
object
id
required
string
name
required
string
groupName
required

Set when the deal belongs to a group conversation instead of a contact

string
nullable
groupProvider
required
string
nullable
groupProfilePicUrl
required
string
nullable
assignee
required
object
id
required
string
name
required
string
nullable
avatarUrl
required

Public url for the user’s photo

string
nullable
tags
required
Array<object>
object
id
required
string
name
required
string
color
required
string
nullable
nextTask
required

Open task with the earliest due date

object
id
required
string
title
required
string
dueAt
required
string format: date-time
isRequired
required
boolean
canComplete
required

Se quem chama pode concluir esta tarefa (a mesma regra de POST /tasks/:id/complete)

boolean
openTaskCount
required
number
unreadCount
required

Unread messages on the linked conversation

number
staleDays
required

Days in the stage once past the stage’s staleDays, else null

number
nullable
extras
required

The pipeline’s cardFields in order, only the filled ones; a sensitive custom field never comes

Array<object>
object
key
required

One of the pipeline’s cardFields

string
value
required

By key: expected_close the same text as expectedCloseAt; products { names (up to 3), count }; next_task { title, dueAt }; contact_tags [{ id, name, color }]; origin { label } from the contact origin or the ad of the deal’s conversation; charge { status, amountCents, dueDate } of the latest charge; attachments { count }; field: { label, type, value } read on the contact, the company or the deal

object
canEdit
required

The caller holds deals:manage and the deal policy lets them act on this deal (drag, stage select)

boolean
advance
required

Null when the deal is not open or its stage is the last open one

object
nextStageId
required

Next open stage by position in the same pipeline

string
missing
required

What blocks the move to the next stage, empty when nothing does

Array<object>
object
kind
required

Assignee: the next stage requires an assignee and the deal has none; expected_close_date, value and products: the next stage requires them and the deal lacks them; company: the next stage requires a company field and the deal has no company

string
Allowed values: task field attachment assignee expected_close_date value products company
id

Task or custom field id

string
entity

Field only: whose field it is

string
Allowed values: contact company deal conversation ticket
title

Task only

string
canComplete

Task only: the caller may complete it (same rule as POST /tasks/:id/complete)

boolean
assigneeName

Task only: name of the person responsible for it

string
nullable
label

Field only: label of the field left blank

string
category

Attachment only: category the next stage requires, null for any

string
nullable
reply
required

Null when the deal is not open, has no live conversation or nobody wrote yet

object
state
required

Customer_waiting: the customer wrote and nobody answered; customer_silent: our message was the last one

string
Allowed values: customer_waiting customer_silent
since
required

Customer_waiting: first unanswered customer message; customer_silent: our last message

string format: date-time
heat
required

Null when the deal is not open or has no live conversation

object
level
required

Cold: past the stage limit, customer silent for 3 days or an overdue open task; hot: the customer wrote in the last 24 h; warm: otherwise

string
Allowed values: hot warm cold
reasons
required

Every rule that holds for the level, cold in the order stage limit, silence, task

Array<object>
object
code
required

Ai: read by the pipeline AI in the conversation, only while the heat reasons switch is on; it never changes the level

string
Allowed values: stage_limit_passed customer_silent_3d task_overdue customer_replied_24h within_stage_limit ai
text

Ai only: the reason the AI read in the conversation

string
nextStep
required

Null when the next step switch is off, the deal is not open or the AI has not read its conversation yet

object
text
required

What the seller should do next, written by the pipeline AI from the conversation

string
writtenAt
required

When the AI wrote it

string format: date-time
nextCursor
required
string
nullable
closed
required

The fixed Ganho and Perdido columns at the end of the board, won then lost; empty when paging a stage

Array<object>
object
outcome
required
string
Allowed values: won lost
count
required

Deals won or lost in the chosen closedPeriod, by the date they were closed, that match the board search and filter, beyond the page

number
valueCents
required

Sum in centavos of the same deals

number
items
required

Most recently closed first

Array<object>
object
id
required
string
number
required

Sequential per tenant, shown as #número

number
title
required
string
nullable
status
required
string
Allowed values: open won lost
valueCents
required
number
stageId
required
string
stageEnteredAt
required
string format: date-time
createdAt
required
string format: date-time
expectedCloseAt
required

Data prevista de fechamento

string format: date-time
nullable
wonAt
required
string format: date-time
nullable
lostAt
required
string format: date-time
nullable
lossReason
required
object
id
required
string
name
required
string
winReason
required
object
id
required
string
name
required
string
intake
required

Filled only while the deal sits in the intake stage

object
firstMessage
required

First inbound message of the conversation that opened the lead

string
nullable
receivedAt
required
string format: date-time
source
required
string
Allowed values: inbound_message ad form
originName
required
string
nullable
servedBy
required

Who is serving the conversation, when someone is

object
id
required
string
name
required
string
nullable
waitingDays
required

Whole days since the lead arrived

number
contactBlocked
required

The lead’s contact is blocked; accept and restore refuse it until it is unblocked

boolean
contact
required
object
id
required
string
name
required
string
channel
required

Channel key derived from the contact’s provider

string
provider
required
string
profilePicUrl
required
string
nullable
origin
required
object
id
required
string
name
required
string
color
required
string
nullable
company
required
object
id
required
string
name
required
string
groupName
required

Set when the deal belongs to a group conversation instead of a contact

string
nullable
groupProvider
required
string
nullable
groupProfilePicUrl
required
string
nullable
assignee
required
object
id
required
string
name
required
string
nullable
avatarUrl
required

Public url for the user’s photo

string
nullable
tags
required
Array<object>
object
id
required
string
name
required
string
color
required
string
nullable
nextTask
required

Open task with the earliest due date

object
id
required
string
title
required
string
dueAt
required
string format: date-time
isRequired
required
boolean
canComplete
required

Se quem chama pode concluir esta tarefa (a mesma regra de POST /tasks/:id/complete)

boolean
openTaskCount
required
number
unreadCount
required

Unread messages on the linked conversation

number
staleDays
required

Days in the stage once past the stage’s staleDays, else null

number
nullable
extras
required

The pipeline’s cardFields in order, only the filled ones; a sensitive custom field never comes

Array<object>
object
key
required

One of the pipeline’s cardFields

string
value
required

By key: expected_close the same text as expectedCloseAt; products { names (up to 3), count }; next_task { title, dueAt }; contact_tags [{ id, name, color }]; origin { label } from the contact origin or the ad of the deal’s conversation; charge { status, amountCents, dueDate } of the latest charge; attachments { count }; field: { label, type, value } read on the contact, the company or the deal

object
canEdit
required

The caller holds deals:manage and the deal policy lets them act on this deal (drag, stage select)

boolean
advance
required

Null when the deal is not open or its stage is the last open one

object
nextStageId
required

Next open stage by position in the same pipeline

string
missing
required

What blocks the move to the next stage, empty when nothing does

Array<object>
object
kind
required

Assignee: the next stage requires an assignee and the deal has none; expected_close_date, value and products: the next stage requires them and the deal lacks them; company: the next stage requires a company field and the deal has no company

string
Allowed values: task field attachment assignee expected_close_date value products company
id

Task or custom field id

string
entity

Field only: whose field it is

string
Allowed values: contact company deal conversation ticket
title

Task only

string
canComplete

Task only: the caller may complete it (same rule as POST /tasks/:id/complete)

boolean
assigneeName

Task only: name of the person responsible for it

string
nullable
label

Field only: label of the field left blank

string
category

Attachment only: category the next stage requires, null for any

string
nullable
reply
required

Null when the deal is not open, has no live conversation or nobody wrote yet

object
state
required

Customer_waiting: the customer wrote and nobody answered; customer_silent: our message was the last one

string
Allowed values: customer_waiting customer_silent
since
required

Customer_waiting: first unanswered customer message; customer_silent: our last message

string format: date-time
heat
required

Null when the deal is not open or has no live conversation

object
level
required

Cold: past the stage limit, customer silent for 3 days or an overdue open task; hot: the customer wrote in the last 24 h; warm: otherwise

string
Allowed values: hot warm cold
reasons
required

Every rule that holds for the level, cold in the order stage limit, silence, task

Array<object>
object
code
required

Ai: read by the pipeline AI in the conversation, only while the heat reasons switch is on; it never changes the level

string
Allowed values: stage_limit_passed customer_silent_3d task_overdue customer_replied_24h within_stage_limit ai
text

Ai only: the reason the AI read in the conversation

string
nextStep
required

Null when the next step switch is off, the deal is not open or the AI has not read its conversation yet

object
text
required

What the seller should do next, written by the pipeline AI from the conversation

string
writtenAt
required

When the AI wrote it

string format: date-time
nextCursor
required

Send it back with outcome to read the next page of this column

string
nullable

Example

{
"columns": [
{
"items": [
{
"status": "open",
"intake": {
"source": "inbound_message"
},
"advance": {
"missing": [
{
"kind": "task",
"entity": "contact"
}
]
},
"reply": {
"state": "customer_waiting"
},
"heat": {
"level": "hot",
"reasons": [
{
"code": "stage_limit_passed"
}
]
}
}
]
}
],
"closed": [
{
"outcome": "won",
"items": [
{
"status": "open",
"intake": {
"source": "inbound_message"
},
"advance": {
"missing": [
{
"kind": "task",
"entity": "contact"
}
]
},
"reply": {
"state": "customer_waiting"
},
"heat": {
"level": "hot",
"reasons": [
{
"code": "stage_limit_passed"
}
]
}
}
]
}
]
}