API Reference / Deals

POST /deals

Create a deal

Creates a deal on a contact. contact_id and name are required (name up to 60 characters; longer names are truncated). status defaults to pending; stage is a per-pipeline integer and applies to pending deals only. amount is the per-month deal value; for recurring deals the total is amount multiplied by the number of months.

Request body

  • contact_idstringbson-id

    ID of the contact, to whom the deal belongs

  • owner_idstringbson-id

    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

  • namestring

    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

  • 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

  • deal_fieldsarray<object>

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

    array item fields →
    • deal_fieldobject
      object fields →
      • idstringbson-id

        ID of the deal field

    • valuestring

      Value for the deal field

  • has_deal_itemsboolean

    Must to be `true` to create or keep deal items (if `false`, deal items will be removed)

  • deal_itemsarray<object>

    List of deal items associated with the deal

    array item fields →
    • 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

    • qtyintegerint32required

      Quantity of deal items

    • predefined_item_idstringbson-id

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

Responses

201 Created
  • statusintegerint32

    Response code

  • messagestring

    Response message

  • timestampintegerunix-timestamp

    Response time

  • dataobject
    object 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)

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

Related guides