API Reference / Deals

GET /deals

Get a list of deals

Returns the account's deals. Each deal belongs to one primary contact and moves through your pipeline as pending, then won or lost.

Query parameters (22)
Name Type Description
name string Search deals by name
search string Search deals by deal name, contact name or company name
status string Return deals of a particular status (i.e. `pending`, `won`, `lost`, or `closed`)
stage integer Return deals (of status `pending`) with specified deal stage
pipeline_id string Return deals from the specified pipeline only
sales_pipeline_id string Return deals referencing a specified sales pipeline only
owner_id string Return deals owned by a specific user
contact_id string Return deals for a specific contact (only use one of `contact_id`, `company_id`, `tag` or `filter_id` at a time)
company_id string Return deals for a specific company (only use one of `contact_id`, `company_id`, `tag` or `filter_id` at a time)
tag string Filter deals by tag (only use one of `contact_id`, `company_id`, `tag` or `filter_id` at a time)
filter_id string Apply filter to deal listing (only use one of `contact_id`, `company_id`, `tag` or `filter_id` at a time)
fields string Include related resources alongside each deal in the response. Syntax: `fields=<resource>(all)`. Use a comma-separated list to request multiple resources. Supported resources: `contacts`. When `fields=contacts(all)` is supplied, each deal entry includes a `contacts` array of full `Contact` objects (the primary contact plus any linked contacts). The short-form `linked_contacts` array on each deal is always returned regardless of this parameter. Example: `fields=contacts(all)`
date_filter string Signals which date field to be used for only returning resources, added or edited, in a specified date range (only to be used with `since` and/or `until`, not with `modified_since` or `unmodified_since`)
since string Specifies the start of the date range to filter resources, which have been added or edited (use with `date_filter` - date must be in format `YYYY-MM-DD` or UNIX timestamp)
until string Specifies the end of the date range to filter resources, which have been added or edited (use with `date_filter` - date must be in format `YYYY-MM-DD` or UNIX timestamp)
modified_since string Return only resources that were modified since specified time (cannot be used with `date_filter` - date must be in format `YYYY-MM-DD` or UNIX timestamp)
unmodified_since string Return only resources that were unmodified since specified time (cannot be used with `date_filter` - date must be in format `YYYY-MM-DD` or UNIX timestamp)
include_history boolean Returns deal stages history, i.e. the most recent stages for each pipeline for the deal This field is returned only when 'include_history=true' param is supplied in request (query string or request body) Format: pipeline_id => stage
sort_by string Specify field by which to order the results (use in conjunction with `order`)
order string Specify the order (ascending or descending) of the sort of the results (use in conjunction with `sort_by`)
page integer Page number. Starts from 1. Default is 1.
per_page integer Number of records to return. Maximum 100 allowed. Default is 10.

Responses

200 OK
  • statusintegerint32

    Response code

  • messagestring

    Response message

  • timestampintegerunix-timestamp

    Response time

  • dataobject
    object fields →
    • dealsarray<object>
      array item fields →
      • dealobject

        Represent (potential) financial transactions with your contacts. Deals include information like amount, deal stage, closed date or expected close date. Deals support file attachments.

        object fields →
        • idstringbson-id

          ID of the deal

        • contact_idstringbson-idrequired

          ID of the contact, to whom the deal belongs

        • owner_idstringbson-idrequired

          ID of the user, to whom the deal belongs. Defaults to the logged API user's ID.

        • pipeline_idstringbson-id

          ID of a pipeline the deal belongs to

        • sales_pipeline_idstringbson-id

          ID of a sales pipeline the deal belongs to

        • namestringrequired

          Name of the deal

        • textstring

          Extra notes related to the deal (supports `[b]bold[/b]` and `[i]italic[/i]` formatting)

        • stageintegerint32

          A numerical representation of the progress of a pending deal (number ranging from 0 to 100 exclusive)

        • statusstring

          Status of the deal

          enum: pending · won · lost

        • expected_close_datestringdate

          The date the deal is expected to close (status should be `pending`). Defaults to today's date.

        • close_datestringdate

          The date the deal actually closed (status should be `won` or `lost`). Defaults to today's date.

        • datestringdate

          Creation date of the deal. Defaults to today's date.

        • amountnumberfloat

          The monitary value of the deal (per month, if multi-month deal)

        • monthsintegerint32

          Number of months the deal is to be paid for (1 for regular deals, 2+ for multi-month)

        • costnumberfloat

          The monitary cost of the deal

        • marginnumberfloat

          Profit margin for the deal (`amount` minus `cost`)

        • total_amountnumberfloat

          Product of amount and months (will only differ from `amount` field, if multi-month deal)

        • total_costnumberfloat

          Product of cost and months (will only differ from `cost` field, if multi-month deal)

        • commission_basestring

          Base used to calculate the commission of the deal

          enum: amount · margin

        • commission_typestring

          Type of commission for the deal

          enum: none · percentage · absolute

        • commissionnumberfloat

          Commission payable for the deal

        • commission_percentagenumberfloat

          Commission percentage for the deal

        • reason_lost_idstringbson-id

          ID of the reason lost

        • deal_fieldsarray<object>

          Custom field values on the deal.

          array item fields →
          • deal_fieldobject

            Extra user-configurable data fields for Deals. Only editable by admins.

            object fields →
            • idstringbson-id

              ID of the deal field

            • namestringrequired

              Name of the deal field

            • typestringrequired

              Type of the deal field. There are several types of custom fields that may store data in different formats. External ID type is a special type introduced for referencing entities in the external systems. Its value is unique amid the whole system. Section divider type is introduced just for visual purpose: it allows grouping custom fields. If custom fields in the section don't have values then they are hidden in the 'view' UI (but always shown in 'edit' UI). This logic is applied in the API: if a deal doesn't have values for all the custom fields in the section then this section divider custom field isn't exposed in the API (along with other custom fields inside the section).

              enum: date · multi_line_text · multiple_choice · number · select_box · single_line_text · external_id · section_divider

            • positionintegerint32

              The position of the deal field in the list

            • choicesarray<string>

              A list of possible choices (for fields of type `multiple_choice` or `select_box`)

          • valuestring

            Value for the deal field

        • has_deal_itemsboolean

          Does the deal have deal items?

        • deal_itemsarray<object>

          Line items on the deal — each with a name, quantity, price, cost and amount.

          array item fields →
          • idstringbson-id

            ID of the deal item

          • namestringrequired

            Name of the deal item

          • descriptionstringrequired

            Description text of the deal item

          • costnumberfloatrequired

            Cost of the deal item

          • pricenumberfloatrequired

            Price of the deal item

          • amountnumberfloat

            Amount of the deal items

          • qtyintegerint32required

            Quantity of deal items

          • deal_idstringbson-id

            ID of the parent deal

          • predefined_item_idstringbson-id

            ID of the predefined item used for deal item creation (can be empty)

          • positionintegerint32

            Position of the predefined item in the items list

          • created_atstringdate-time

            Creation time of the deal item

          • modified_atstringdate-time

            Last modification time of the deal item

        • authorstring

          Shortened name of the creator of the deal. Defaults to the logged API user.

        • has_related_notesboolean

          Does the deal have related notes?

        • attachmentsarray<object>

          Files attached to the deal.

          array item fields →
          • idstringbson-id

            ID of the attachment

          • filenamestringrequired

            Name of the attachment file

          • custom_filenamestring

            Custom name of the attachment file

          • pinnedboolean

            Show if the attachment is pinned to its owner contact

          • pinned_atstring

            Shows pinned at timestamp. Is null if pinned == false

          • sizeintegerint32required

            Size of the attachment file (in bytes)

          • storage_providerstring

            Name of the storage provider (where the attachment file is stored)

            enum: amazon · google_drive · dropbox · evernote

          • urlstring

            External URL of the attachment file

          • url_expires_atstringdate-time

            The time the attachment URL expires

          • thumbnailobject

            An image preview of the attachment file (if one exists)

            object fields →
            • urlstring

              External URL of the attachment's thumbnail

        • contact_infoobject

          Information about the contact, to whom the deal belongs (read only).

          object fields →
          • contact_namestring

            Name of the contact associated with the deal

          • companystring

            Name of the company associated with the deal

        • ownerobject

          Information about the deal owner (read only).

          object fields →
          • idstring

            ID of the deal owner

          • namestring

            Name of the deal owner

          • emailstring

            Email address of the deal owner

        • previous_pipeline_stagesobject

          Returns the last stage in which the deal was for each pipeline (pipeline_id => stage) This field is returned only when 'include_history=true' param is supplied in query string

        • created_atstringdate-time

          Creation time of the deal

        • modified_atstringdate-time

          Last modification time of the deal

        • linked_contactsarray<object>

          Short form of contacts linked to the deal. Always returned with the deal payload (on both `GET /deals` and `GET /deals/{deal_id}`). For full contact objects use `fields=contacts(all)` on `GET /deals`.

          array item fields →
          • idstringbson-id

            ID of the linked contact

          • contact_namestring

            Full display name of the linked contact

          • companystring

            Display name of the company the contact belongs to (empty string if none)

          • photo_urlstring

            URL of the contact's profile picture (empty string if none)

      • contactsarray<object>

        Full `Contact` objects for the deal (primary contact plus linked contacts). Returned only when `fields=contacts(all)` is supplied.

        array item fields →
        • idstringbson-id

          ID of the contact

        • titlestring

          The title of the contact

          enum: Mr · Mrs · Ms

        • first_namestring

          First name of the contact

        • last_namestring

          Last name of the contact

        • job_titlestring

          Job title of the contact

        • starredboolean

          Is the contact starred?

        • photo_urlstring

          URL of the contact's photo

        • company_idstringbson-id

          ID of the company, to which the contact belongs

        • company_namestring

          Name of the company, to whom the contact belongs

        • urlsarray<object>

          URLs associated with the contact

          array item fields →
          • typestring

            The type of URL

            enum: website · blog · twitter · linkedin · xing · facebook · google_plus · other

          • valuestring

            The URL associated with the contact

        • phonesarray<object>

          Phone numbers associated with the contact

          array item fields →
          • typestring

            The type of phone number

            enum: work · mobile · home · direct · fax · company · other

          • valuestring

            The phone number associated with the contact

        • emailsarray<object>

          Email addresses associated with the contact

          array item fields →
          • typestring

            The type of email address

            enum: work · home · other

          • valuestring

            The email address associated with the contact

        • address_listarray<object>

          An array of contact addresses.

          array item fields →
          • addressstring

            Street address.

          • citystring

            City.

          • statestring

            State, province or region.

          • zip_codestring

            Postal or ZIP code.

          • country_codestring

            ISO 3166 country code, upper-case.

          • typestring

            Type of the address

            enum: work · home · billing · delivery · other

        • statusstring

          Status of the contact

        • status_idstringbson-id

          ID of the status of the contact

        • tagsarray<string>

          Tags on the contact — free-form strings from the account's tag list.

        • lead_source_idstring

          ID of the lead source of the contact

        • lead_sourcestring

          Display name of the lead source of the contact

        • backgroundstring

          Background infomation about the contact

        • owner_idstringbson-id

          ID of the user, to whom the contact belongs. Defaults to the logged API user's ID.

        • custom_fieldsarray<object>

          Custom field values on the contact, as custom field and value pairs.

          array item fields →
          • custom_fieldobject

            Extra user-configurable data fields for Contacts. Only editable by admins.

            object fields →
            • idstringbson-id

              ID of the custom field

            • namestringrequired

              Name of the custom field

            • typestringrequired

              Type of the custom field. There are several types of custom fields that may store data in different formats. External ID type is a special type introduced for referencing entities in the external systems. Its value is unique amid the whole system. Section divider type is introduced just for visual purpose: it allows grouping custom fields. If custom fields in the section don't have values then they are hidden in the 'view' UI (but always shown in 'edit' UI). This logic is applied in the API: if a contact doesn't have values for all the custom fields in the section then this section divider custom field isn't exposed in the API (along with other custom fields inside the section).

              enum: anniversary · date · multi_line_text · multiple_choice · number · select_box · single_line_text · external_id · section_divider

            • positionintegerint32

              The position of the custom field in the list

            • choicesarray<string>

              A list of possible choices (for fields of type `multiple_choice` or `select_box`)

          • valuestring

            Value for the custom field

        • letterstring

          The first letter of the contacts last name

        • pending_dealboolean

          Does the contact have one or more pending deals?

        • total_pendingsnumber

          The total value of all pending deals for the contact

        • total_deals_countintegerint32

          Number of deals associated with the contact

        • company_sizeintegerint32

          Number of contacts within the contact's company

        • sales_closed_forarray<string>

          A list of user IDs, for whom the sales cycle is closed

        • closed_salesarray<object>

          A list of closed sales objects

          array item fields →
          • user_idstringbson-id

            ID of the user, for whom the sales cycle is closed

          • closed_atintegerunix-timestamp

            Time that the sales cycle was closed

          • commentstring

            An optional message detailing why the sales cycle was closed

        • google_contacts_dataobject

          The google contacts data associated with this contact

          object fields →
          • account_emailstring

            Google contacts email

          • idstring

            Google contact id

          • saved_atintegerunix-timestamp

            Time the contact was saved to google

        • created_atstringdate-time

          Creation time of the contact

        • modified_atstringdate-time

          Last modification time of the contact

    • total_countintegerint32

      Total number of items

    • pageintegerint32

      Current page number

    • per_pageintegerint32

      Number of items returned in each page

    • max_pageintegerint32

      The page number of the last page of items

Standard error responses: 400 · 401 · 403 · 404 · 409 · 500 — shared across the API. See Errors.

Related guides