List Deals

GET

/deals

Production
QA

List all deals org-wide with optional filters and pagination.

Authorizations

BearerAuth

Parameters

Query Parameters

page

Page number

integer

default: 1 >= 1

Page number

limit

Items per page

integer

default: 50 >= 1 <= 200

Items per page

stage_id

Any of:

string
null

string

Filter by stage ID

pipeline_id

Any of:

string
null

string

Filter by pipeline ID

search

Any of:

string
null

string

Search by deal name

owner_id

Any of:

string
null

string

Filter by owner ID

owner_email

Any of:

string
null

string

Filter by owner email

outcome

Any of:

string
null

string

Allowed values: won lost open

Filter by deal outcome. A deal is won, lost, or open - exactly one. Prefer this over is_closed_won: the boolean’s false branch means ‘not won’, which returns open AND unclassified deals alongside lost ones, and is the wrong cohort for closed-lost re-engagement.

is_closed_won

Any of:

boolean
null

boolean

LEGACY - prefer outcome=. Retained for backwards compatibility with existing consumers. true means won; false means NOT won (open, lost and unclassified deals), which is rarely what a caller intends.

last_activity_before

Any of:

string
null

string format: date-time

Only deals last touched before this timestamp

stale_before

Any of:

string
null

string format: date-time

Deals last touched before this timestamp OR never touched at all. Union of last_activity_before and the no-activity cohort - use this for ‘my stale deals’ (last_activity_before alone excludes deals with no recorded activity, since NULL is never earlier-than).

has_activity

Any of:

boolean
null

boolean

Filter by whether the deal has recorded activity

has_contact

Any of:

boolean
null

boolean

Filter by whether the deal has a route to any contact. false returns the orphaned-deal cohort: no cb_deal_contacts row AND no live primary contact (a primary_contact_id pointing at a soft-deleted or merged-away contact counts as no route). Same definition the Data Quality panel counts, so the two can never disagree.

close_after

Any of:

string
null

string format: date-time

Only deals whose close_date is on/after this timestamp (inclusive lower bound). Pair with close_before for a period window, and with outcome=won for ‘deals we closed-won in this period’. A period count needs BOTH a lower bound and the outcome join: close_before alone sums the entire deal history into every period. Deals with a NULL close_date are excluded (a deal with no close date is not closing in any window). A naive timestamp is treated as UTC.

close_before

Any of:

string
null

string format: date-time

Only deals whose close_date is strictly before this timestamp (exclusive upper bound). The window is half-open [close_after, close_before) so adjacent periods never double-count a deal that closes exactly on a boundary. A naive timestamp is treated as UTC (the close_date column is timestamp without time zone).

Header Parameters

X-Target-Org-Id

Any of:

string
null

string

Responses

200

Successful Response

object

data

required

Array<object>

object

amount

Any of:

number
null

number

close_date

Any of:

string
null

string

closed_lost_reason

Any of:

string
null

string

company_id

Any of:

unknown
null

contact_count

integer

contacts

Any of:

Array<object>
null

Array<object>

Lightweight contact summary embedded in deal responses.

id is the canonical mashup_contact_id (BigInt), matching how contacts are addressed everywhere else in the public API (g8_search_contacts, g8_lookup_person, etc.). role is the contact’s role within THIS deal (champion / decision_maker / influencer / blocker / coach / end_user) and is null when no role was set.

object

email

Any of: