Deals

Please be aware, that the type of deal value has been recently changed to reflect the implementation of deal decimal values. If a deal value has no decimal part (1000.0), it will be returned as integer (1000) as before. If a deal has a decimal part (1000.50), it will be returned as string with two decimal places (1000.50).

The Deals API provides a simple interface to manage deals. The API allows you to create, delete and update your deals. You can also retrieve a single deal as well as list of all deals. Every deal can have multiple associated contacts, each with a different role.

You can assign any number of tags and custom fields to a deal. Tags don’t need to exist to be assigned - they can be created when creating or updating the deal.

The organization_id is set automatically when you associate a deal with a primary contact which belongs to a company.

Properties

Attribute Description
id number readonly

Unique identifier of the deal.
creator_id number readonly

Unique identifier of the user who created the deal.
owner_id number

Unique identifier of the user that the deal is assigned to.
name string

Name of the deal.
value number or string

Value of the deal in a currency specified in the currency field. If a deal value has no decimal part (1000.0), it will be returned as integer (1000). If a deal has a decimal part (1000.50), it will be returned as string with two decimal places (1000.50).
currency string

Currency of the deal, specified in 3-character currency code (ISO4217) format.
hot boolean

Indicator of whether or not the deal is hot.
stage_id number

Unique identifier of the deal’s current stage in the pipeline.
last_stage_change_at string

Date and time when the deal was moved into the current stage in UTC (ISO8601 format).
last_stage_change_by_id number readonly

Unique identifier of the user who moved the deal into the current stage.
last_activity_at string readonly

Date and time of the last activity on the deal in UTC (ISO8601 format).
source_id number

Unique identifier of the Source.
loss_reason_id number

Reason why the deal was lost.
dropbox_email string readonly

Dropbox email connected with the deal.
contact_id number

Unique identifier of a primary contact.
organization_id number readonly

Unique identifier of an organization.
estimated_close_date string

Estimated close date of the deal.
customized_win_likelihood number

User-provided win likelihood with value range 0–100.
tags array

An array of tags for a deal. See more at Tags.
custom_fields object

Custom fields are key-value data attached to a deal. See more at Custom Fields.
created_at string readonly

Date and time that the deal was created in UTC (ISO8601 format).
updated_at string readonly

Date and time of the last update on the deal in UTC (ISO8601 format).

Endpoints

Retrieve all deals

Returns all deals available to the user according to the parameters provided.

Parameters

Attribute Description
page number optional

Page number to start from. Page numbering starts at 1, and omitting the page parameter will return the first page.

e.g. ?page=2
per_page number optional

Number of records to return per page. Default limit is 25 and the maximum number that can be returned is 100.

e.g. ?per_page=20
sort_by string optional

A field to sort by. You can sort by filterable custom fields as well, e.g. to filter by external id use ?sort_by=custom_fields:external_id (supported custom field types are: Number, Single Line Text, Dropdown, Multi Select). Default ordering is ascending. If you want to change the sort order to descending, append :desc to the field e.g. sort_by=value:desc.

Possible values:

  • id
  • value
  • name
  • estimated_close_date
  • updated_at
  • created_at
e.g. ?sort_by=created_at
ids string optional

Comma-separated list of deal IDs to be returned in a request.

e.g. ?ids=1,2,3
includes string optional

Comma-separated list of one or more resources related to a deal.

Possible values:

  • associated_contacts
e.g. ?includes=associated_contacts
creator_id number optional

Unique identifier of the user the deal was created by. Returns all deals created by the user.

e.g. ?creator_id=1
owner_id number optional

Unique identifier of the user the deal is owned by. Returns all deals owned by the user.

e.g. ?owner_id=1
contact_id number optional

Unique identifier of a primary contact.

e.g. ?contact_id=1
organization_id number optional

Unique identifier of an organization.

e.g. ?organization_id=2
hot boolean optional

Indicator of whether or not the deal is hot.

e.g. ?hot=true
source_id number optional

Id of the Source.

e.g. ?source_id=10
stage_id number optional

Id of the Stage.

e.g. ?stage_id=1
name string optional

Name of the deal.

e.g. ?name=Website%20Redesign
value number or string optional

Value of the deal. We encourage you to use a string with two decimal places.

e.g. ?value=1000.50
estimated_close_date string optional

Estimated close date of the deal.

e.g. ?estimated_close_date=2015-06-19
custom_fields string optional

Filterable custom field e.g. ?custom_fields[external_id]=SKU01. Custom fields must be defined and have Filterable property assigned (supported custom field types are: Number, Single Line Text, Dropdown, Multi Select).
inclusive boolean optional

Indicates how filters should be combine. true value, the default, uses AND logic. false value uses OR logic to combine filters.

e.g. ?inclusive=true

Create a deal

Create a new deal.

Parameters

Attribute Description
name string required
e.g. "name": "Website Redesign"
contact_id number required
e.g. "contact_id": "1"
value number or string optional

Value of the deal. We encourage you to use a string with two decimal places.

e.g. "value": "1000.50"
currency string optional

If omitted, currency will be set to the default currency of the account.

e.g. "currency": "EUR"
owner_id number optional

Defaults to the unique identifier of the user that the deal is created by.

e.g. "owner_id": "1"
hot boolean optional
e.g. "hot": "true"
stage_id number optional

If omitted, the deal will be placed in the first stage of the default pipeline.

e.g. "stage_id": "1"
last_stage_change_at string optional

Date and time when the deal was moved into the current stage in UTC (ISO8601 format).’)

e.g. "last_stage_change_at": "2014-09-28T16:32:56Z"
source_id number optional

Id of the deal Source.

e.g. "source_id": "10"
loss_reason_id number optional

Id of the Loss Reason.

e.g. "loss_reason_id": "20"
estimated_close_date string optional
e.g. "estimated_close_date": "2015-06-19"
customized_win_likelihood number optional

User-provided win likelihood with value range 0–100.

e.g. "customized_win_likelihood": "15"
tags array optional
e.g. "tags": ["important"]
custom_fields object optional
e.g. "custom_fields": {"website": "http://www.coffeeshop.com"}

Retrieve a single deal

Returns a single deal available to the user, according to the unique deal ID provided. If the specified deal does not exist, the request will return an error.

Parameters

Attribute Description
id number required

Unique identifier of the deal.
includes string optional

Comma-separated list of one or more resources related to the deal.

Possible values:

  • associated_contacts
e.g. ?includes=associated_contacts

Update a deal

Updates deal information. If the specified deal does not exist, the request will return an error.

In order to modify tags used on a record, you need to supply the entire set. tags are replaced every time they are used in a request.

Parameters

Attribute Description
name string optional
e.g. "name": "Website Redesign"
value number or string optional

We encourage you to use string with two decimal places.

e.g. "value": "1000.50"
currency string optional
e.g. "currency": "EUR"
owner_id number optional
e.g. "owner_id": "1"
hot boolean optional
e.g. "hot": "true"
stage_id number optional
e.g. "stage_id": "1"
last_stage_change_at string optional

Date and time when the deal was moved into the current stage in UTC (ISO8601 format).’)

e.g. "last_stage_change_at": "2014-09-28T16:32:56Z"
source_id number optional

Unique identifier of the deal Source.

e.g. "source_id": "10"
loss_reason_id number optional

Unique identifier of the Loss Reason.

e.g. "loss_reason_id": "20"
contact_id number optional

Unique identifier of a primary contact.

e.g. "contact_id": "1"
estimated_close_date string optional
e.g. "estimated_close_date": "2015-06-19"
customized_win_likelihood number optional

User-provided win likelihood with value range 0–100.

e.g. "customized_win_likelihood": "15"
tags array optional

In order to modify, you need to supply the entire set.

e.g. "tags": ["important"]
custom_fields object optional
e.g. "custom_fields": {"website": "http://www.coffeeshop.com"}

Delete a deal

Delete an existing deal and remove all of the associated contacts from the deal in a single call. If the specified deal does not exist, the request will return an error. This operation cannot be undone.

Parameters

Attribute Description
id number required

Unique identifier of the deal.

Upsert a deal

Create a new deal or update an existing, based on a value of a filter or a set of filters. At least a single filter - query parameter - is required. If no parameters are present, the request will return an error.

Behaviour:

  1. If multiple deals match a set of filters, the request will return an error - 409.

  2. If a single deal matches, then the existing deal is updated

  3. If none matches the query, a new deal is created

Notice Use Upsert API, instead of Create or Update, to avoid creating unwanted, duplicated records. Also very useful if you want Base to carry external system ids - stored as custom fields.

Parameters

Attribute Description
creator_id number optional

Unique identifier of the user the deal was created by. Returns all deals created by the user.

e.g. "creator_id": "1"
owner_id number optional

Unique identifier of the user the deal is owned by. Returns all deals owned by the user.

e.g. "owner_id": "1"
contact_id number optional

Unique identifier of a primary contact.

e.g. "contact_id": "1"
organization_id number optional

Unique identifier of an organization.

e.g. "organization_id": "2"
hot boolean optional

Indicator of whether or not the deal is hot.

e.g. "hot": "true"
source_id number optional

Id of the Source.

e.g. "source_id": "10"
stage_id number optional

Id of the Stage.

e.g. "stage_id": "1"
last_stage_change_at string optional

Date and time when the deal was moved into the current stage in UTC (ISO8601 format).’)

e.g. "last_stage_change_at": "2014-09-28T16:32:56Z"
name string optional

Name of the deal.

e.g. "name": "Website Redesign"
value number or string optional

Value of the deal. We encourage you to use a string with two decimal places.

e.g. "value": "1000.50"
estimated_close_date string optional

Estimated close date of the deal.

e.g. "estimated_close_date": "2015-06-19"
customized_win_likelihood number optional

User-provided win likelihood with value range 0–100.

e.g. "customized_win_likelihood": "15"
custom_fields string optional

Filterable custom field e.g. ?custom_fields[external_id]=SKU01. Custom fields must be defined and have Filterable property assigned (supported custom field types are: Number, Single Line Text, Dropdown, Multi Select).
inclusive boolean optional

Indicates how filters should be combine. true value, the default, uses AND logic. false value uses OR logic to combine filters.

e.g. "inclusive": "true"