Deals

Documentation describing the API provided by the Deals service.

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.

JSON format

Name	Type	Read only	Description
`id`	number	true	Unique identifier of the deal.
`creator_id`	number	true	Unique identifier of the user who created the deal.
`owner_id`	number	false	Unique identifier of the user that the deal is assigned to.
`name`	string	false	Name of the deal.
`value`	number or string	false	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	false	Currency of the deal, specified in 3-character currency code (ISO4217) format.
`hot`	boolean	false	Indicator of whether or not the deal is hot.
`stage_id`	number	false	Unique identifier of the deal's current stage in the pipeline.
`last_stage_change_at`	string	false	Date and time when the deal was moved into the current stage in UTC (ISO8601 format).
`last_stage_change_by_id`	number	true	Unique identifier of the user who moved the deal into the current stage.
`last_activity_at`	string	true	Date and time of the last activity on the deal in UTC (ISO8601 format).
`source_id`	number	false	Unique identifier of the Source.
`loss_reason_id`	number	false	Reason why the deal was lost.
`unqualified_reason_id`	number	false	Reason why the deal was unqualied.
`dropbox_email`	string	true	Dropbox email connected with the deal.
`contact_id`	number	false	Unique identifier of a primary contact.
`organization_id`	number	true	Unique identifier of an organization.
`estimated_close_date`	string	false	Estimated close date of the deal.
`customized_win_likelihood`	number	false	User-provided win likelihood with value range 0-100.
`tags`	array	false	An array of tags for a deal. See more at Tags.
`custom_fields`	Object	false	Custom fields are key-value data attached to a deal. Only fields with non-null values are returned. See Custom Fields.
`created_at`	string	true	Date and time that the deal was created in UTC (ISO8601 format).
`updated_at`	string	true	Date and time of the last update on the deal in UTC (ISO8601 format).
`added_at`	string	true	Date and time that the deal was started in UTC (ISO8601 format).

Retrieve all deals

GET /v2/deals

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

Parameters

Name	Type	Required	In	Description
`page`	number	false	Query	Page number to start from. Page numbering starts at 1, and omitting the `page` parameter will return the first page.
`per_page`	number	false	Query	Number of records to return per page. Default limit is _25_ and the maximum number that can be returned is _100_.
`sort_by`	string	false	Query	A field to sort by. You can sort by filterable custom fields as well. Example: To sort by a custom field named "external_id", use `?sort_by=custom_fields:external_id`. Supported custom field types: Number, Single Line Text, Dropdown, Multi Select. The default ordering is ascending. To change the sort order to descending, append `:desc` to the field. Example: `sort_by=value:desc`. Possible values: "id", "value", "name", "estimated_close_date", "updated_at", "created_at"
`ids`	string	false	Query	Comma-separated list of deal IDs to be returned in a request.
`includes`	string	false	Query	Comma-separated list of one or more resources related to a deal.
`creator_id`	number	false	Query	Unique identifier of the user the deal was created by. Returns all deals created by the user.
`owner_id`	number	false	Query	Unique identifier of the user the deal is owned by. Returns all deals owned by the user.
`contact_id`	number	false	Query	Unique identifier of a primary contact.
`organization_id`	number	false	Query	Unique identifier of an organization.
`hot`	boolean	false	Query	Indicator of whether or not the deal is hot.
`source_id`	number	false	Query	Id of the Source.
`stage_id`	number	false	Query	Id of the Stage.
`name`	string	false	Query	Name of the deal.
`value`	number or string	false	Query	Value of the deal. We encourage you to use a string with two decimal places.
`estimated_close_date`	string	false	Query	Estimated close date of the deal.
`custom_fields`	string	false	Query	Filterable custom field. Example: To find deals with a custom field named "external_id" with a value of "SKU01", use the following: `?custom_fields[external_id]=SKU01`. Custom fields must be defined and have a Filterable property assigned to them. Supported custom field types: Number, Single Line Text, Dropdown, Multi Select.
`inclusive`	boolean	false	Query	Indicates how filters should be combine. `true` value, the default, uses AND logic. `false` value uses OR logic to combine filters.

Allowed for

Agents

Using cURL

curl -v -X GET https://api.getbase.com/v2/deals \-H "Accept: application/json" \-H "Authorization: Bearer $ACCESS_TOKEN"

Example response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8Content-Language: en
{  "items": [    {      "data": {        "id": 1,        "creator_id": 1,        "owner_id": 1,        "name": "Website Redesign",        "value": "1000.50",        "currency": "USD",        "hot": true,        "stage_id": 1,        "last_stage_change_at": "2014-08-27T16:32:56Z",        "last_stage_change_by_id": 1,        "last_activity_at": "2014-08-27T17:32:56Z",        "source_id": 10,        "loss_reason_id": null,        "unqualified_reason_id": null,        "dropbox_email": "[email protected]",        "contact_id": 1,        "organization_id": 2,        "estimated_close_date": null,        "customized_win_likelihood": 15,        "tags": [          "important"        ],        "custom_fields": {          "website": "http://www.coffeeshop.com"        },        "created_at": "2014-08-27T16:32:56Z",        "updated_at": "2014-08-27T17:32:56Z"      },      "meta": {        "type": "deal"      }    }  ],  "meta": {    "type": "collection",    "count": 1,    "links": {      "self": "http://api.getbase.com/v2/deals"    }  }}

Create a deal

POST /v2/deals

Create a new deal.

Parameters

Name	Type	Required	In	Description
`name`	string	true	Body
`contact_id`	number	true	Body
`value`	number or string	false	Body	Value of the deal. We encourage you to use a string with two decimal places.
`currency`	string	false	Body	If omitted, currency will be set to the default currency of the account.
`owner_id`	number	false	Body	Defaults to the unique identifier of the user that the deal is created by.
`hot`	boolean	false	Body
`stage_id`	number	false	Body	If omitted, the deal will be placed in the first stage of the default pipeline.
`last_stage_change_at`	string	false	Body	Date and time when the deal was moved into the current stage in UTC (ISO8601 format).
`added_at`	string	false	Body	Date and time that the deal was started in UTC (ISO8601 format).
`source_id`	number	false	Body	Id of the deal Source.
`loss_reason_id`	number	false	Body	Id of the Loss Reason.
`unqualified_reason_id`	number	false	Body	Id of the Unqualify Reason.
`estimated_close_date`	string	false	Body
`customized_win_likelihood`	number	false	Body	User-provided win likelihood with value range 0-100.
`tags`	array	false	Body
`custom_fields`	object	false	Body	See Custom Fields.

Allowed for

Agents

Using cURL

curl -v -X POST https://api.getbase.com/v2/deals \-H "Accept: application/json" \-H "Content-Type: application/json" \-H "Authorization: Bearer $ACCESS_TOKEN" \-d '{  "data": {    "name": "Website Redesign",    "value": "1000.50",    "hot": true,    "source_id": 10,    "contact_id": 1,    "tags": [      "important"    ],    "custom_fields": {      "website": "http://www.coffeeshop.com"    }  },  "meta": {    "type": "deal"  }}'

Example response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8Content-Language: en
{  "data": {    "id": 1,    "creator_id": 1,    "owner_id": 1,    "name": "Website Redesign",    "value": "1000.50",    "currency": "USD",    "hot": true,    "stage_id": 1,    "last_stage_change_at": "2014-08-27T16:32:56Z",    "last_stage_change_by_id": 1,    "last_activity_at": "2014-08-27T16:32:56Z",    "source_id": 10,    "loss_reason_id": null,    "unqualified_reason_id": null,    "dropbox_email": "[email protected]",    "contact_id": 1,    "organization_id": 2,    "estimated_close_date": null,    "tags": [      "important"    ],    "custom_fields": {      "website": "http://www.coffeeshop.com"    },    "created_at": "2014-08-27T16:32:56Z",    "updated_at": "2014-08-27T16:32:56Z"  },  "meta": {    "type": "deal"  }}

Retrieve a single deal

GET /v2/deals/:id

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

Name	Type	Required	In	Description
`id`	true	number	Query	Unique identifier of the deal.
`includes`	false	string	Query	Comma-separated list of one or more resources related to the deal. Possible values: `associated_contacts`

Allowed for

Agents

Using cURL

curl -v -X GET https://api.getbase.com/v2/deals/1 \-H "Accept: application/json" \-H "Authorization: Bearer $ACCESS_TOKEN"

Example response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8Content-Language: en
{  "data": {    "id": 1,    "creator_id": 1,    "owner_id": 1,    "name": "Website Redesign",    "value": "1000.50",    "currency": "USD",    "hot": true,    "stage_id": 1,    "last_stage_change_at": "2014-08-27T16:32:56Z",    "last_stage_change_by_id": 1,    "last_activity_at": "2014-08-27T16:32:56Z",    "source_id": 10,    "loss_reason_id": null,    "unqualified_reason_id": null,    "dropbox_email": "[email protected]",    "contact_id": 1,    "organization_id": 2,    "estimated_close_date": null,    "tags": [      "important"    ],    "custom_fields": {      "website": "http://www.coffeeshop.com"    },    "created_at": "2014-08-27T16:32:56Z",    "updated_at": "2014-08-27T16:32:56Z"  },  "meta": {    "type": "deal"  }}

Update a deal

PUT /v2/deals/:id

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

Note: 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

Name	Type	Required	In	Description
`name`	false	string	Body
`value`	false	number or string	Body	We encourage you to use string with two decimal places.
`currency`	false	string	Body
`owner_id`	false	number	Body
`hot`	false	boolean	Body
`stage_id`	false	number	Body
`last_stage_change_at`	false	string	Body	Date and time when the deal was moved into the current stage in UTC (ISO8601 format).
`added_at`	false	string	Body	Date and time that the deal was started in UTC (ISO8601 format).
`source_id`	false	number	Body	Unique identifier of the deal Source.
`loss_reason_id`	false	number	Body	Unique identifier of the Loss Reason.
`unqualified_reason_id`	false	number	Body	Unique identifier of the Unqualify Reason.
`contact_id`	false	number	Body	Unique identifier of a primary contact.
`estimated_close_date`	false	string	Body
`customized_win_likelihood`	false	number	Body	User-provided win likelihood with value range 0-100.
`tags`	false	array	Body	In order to modify, you need to supply the entire set.
`custom_fields`	false	object	Body	See Custom Fields.

Allowed for

Agents

Using cURL

curl -v -X PUT https://api.getbase.com/v2/deals/1 \-H "Accept: application/json" \-H "Content-Type: application/json" \-H "Authorization: Bearer $ACCESS_TOKEN" \-d '{  "data": {    "stage_id": 2  }}'

Example response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8Content-Language: en
{  "data": {    "id": 1,    "creator_id": 1,    "owner_id": 1,    "name": "Website Redesign",    "value": "1000.50",    "currency": "USD",    "hot": true,    "stage_id": 2,    "last_stage_change_at": "2014-08-27T16:32:56Z",    "last_stage_change_by_id": 1,    "last_activity_at": "2014-08-27T17:32:56Z",    "source_id": 10,    "loss_reason_id": null,    "unqualified_reason_id": null,    "dropbox_email": "[email protected]",    "contact_id": 1,    "organization_id": 2,    "estimated_close_date": null,    "customized_win_likelihood": 15,    "tags": [      "important"    ],    "custom_fields": {      "website": "http://www.coffeeshop.com"    },    "created_at": "2014-08-27T16:32:56Z",    "updated_at": "2014-08-27T17:32:56Z"  },  "meta": {    "type": "deal"  }}

Delete a deal

DELETE /v2/deals/:id

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

Name	Type	Required	In	Description
`id`	number	true	Query	Unique identifier of the deal.

Allowed for

Agents

Using cURL

curl -v -X DELETE https://api.getbase.com/v2/deals/1 \-H "Authorization: Bearer $ACCESS_TOKEN"

Example response

HTTP/1.1 204 No Content

Upsert a deal

POST /v2/deals/upsert

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:

If multiple deals match a set of filters, the request will return an error - 409.
If a single deal matches, then the existing deal is updated
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 Sell to carry external system ids - stored as custom fields.

Parameters

Name	Type	Required	In	Description
`creator_id`	number	false	Body	Unique identifier of the user the deal was created by. Returns all deals created by the user.
`owner_id`	number	false	Body	Unique identifier of the user the deal is owned by. Returns all deals owned by the user.
`contact_id`	number	false	Body	Unique identifier of a primary contact.
`organization_id`	number	false	Body	Unique identifier of an organization.
`hot`	boolean	false	Body	Indicator of whether or not the deal is hot.
`source_id`	number	false	Body	Id of the Source.
`stage_id`	number	false	Body	Id of the Stage.
`last_stage_change_at`	string	false	Body	Date and time when the deal was moved into the current stage in UTC (ISO8601 format))
`added_at`	string	false	Body	Date and time that the deal was started in UTC (ISO8601 format).
`name`	string	false	Body	Name of the deal.
`value`	number or string	false	Body	Value of the deal. We encourage you to use a string with two decimal places.
`estimated_close_date`	string	false	Body	Estimated close date of the deal.
`customized_win_likelihood`	number	false	Body	User-provided win likelihood with value range 0--100.
`custom_fields`	string	false	Body	Filterable custom field. Example: To perform an upsert on a deal with a custom field named "external_id" with a value of "SKU01", use the following: `?custom_fields[external_id]=SKU01`. Custom fields must be defined and have a Filterable property assigned to them. Supported custom field types: Number, Single Line Text, Dropdown, Multi Select.
`inclusive`	boolean	false	Body	Indicates how filters should be combine. `true` value, the default, uses AND logic. `false` value uses OR logic to combine filters.

Allowed for

Agents

Using cURL

curl -v -X POST https://api.getbase.com/v2/deals/upsert?custom_fields[external_id]=SKU01 \-H "Accept: application/json" \-H "Content-Type: application/json" \-H "Authorization: Bearer $ACCESS_TOKEN" \-d '{  "data": {    "name": "Website Redesign for Coffeeshop",    "custom_fields": {      "external_id": "SKU01"    }  }}'

Example response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8Content-Language: en
{  "data": {    "id": 1,    "creator_id": 1,    "owner_id": 1,    "name": "Website Redesign for Coffeeshop",    "value": "1000.50",    "currency": "USD",    "hot": true,    "stage_id": 1,    "last_stage_change_at": "2014-08-27T16:32:56Z",    "last_stage_change_by_id": 1,    "last_activity_at": "2015-07-16T17:14:16Z",    "source_id": 10,    "loss_reason_id": null,    "unqualified_reason_id": null,    "dropbox_email": "[email protected]",    "contact_id": 1,    "organization_id": 2,    "estimated_close_date": null,    "customized_win_likelihood": 15,    "tags": [      "important"    ],    "custom_fields": {      "external_id": "SKU01",      "website": "http://www.coffeeshop.com"    },    "created_at": "2014-08-27T16:32:56Z",    "updated_at": "2015-07-16T17:14:16Z"  },  "meta": {    "type": "deal"  }}

Authentication

Sync API

Search API

Firehose API

Core APIs

Apps

Deals

JSON format

Retrieve all deals

Parameters

Allowed for

Using cURL

Example response

Create a deal

Parameters

Allowed for

Using cURL

Example response

Retrieve a single deal

Parameters

Allowed for

Using cURL

Example response

Update a deal

Parameters

Allowed for

Using cURL

Example response

Delete a deal

Parameters

Allowed for

Using cURL

Example response

Upsert a deal

Parameters

Allowed for

Using cURL

Example response