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-8
Content-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-8
Content-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-8
Content-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-8
Content-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-8
Content-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"
}
}