Deal sidebar

The app is displayed in the Deal Card location on the right side, along with native widgets.

Example manifest

"location": {
  "sell": {
    "deal_card": "assets/iframe.html"
  }
},

The following object is available in this location:

Events

In addition to the core events, the following events are available to apps in the Deal sidebar location:

You can also listen for changes on any object or property of the Deal object by adding the suffix .changed to its path. Any event handler bound to a .changed event receives an object with the name of the changed property, its previous value, and its new value. Example:

client.on('deal.creator.changed', (data) => {
  console.log(data);  // {propertyName, oldValue, newValue}
});

See Working with framework events.

deal.notes.added

Fires when a note is added to the deal. Any event handler bound to deal.notes.added receives the note object.

Example:

client.on('deal.notes.added', (note) => {
  console.log(note); // Note object
  // example:
  // {
  //   "id": 32661,
  //   "creator_id": 42616,
  //   "resource_type": "sales_account",
  //   "resource_id": 29732437,
  //   "content": "Called them, but no answer",
  //   "created_at": "2019-10-01T09:00:21Z",
  //   "updated_at": "2019-10-01T09:00:21Z"
  // }
});
deal.tasks.added

Fires when a task is added to the deal in the current tab. Any event handler bound to deal.tasks.added receives the task object.

Example:

client.on('deal.tasks.added', (task) => {
  console.log(task); // Task object
  // example:
  // {
  //   "id": 32661,
  //   "creator_id": 42616,
  //   "owner_id": 42616,
  //   "resource_type": "sales_account",
  //   "completed": false,
  //   "completed_at": null,
  //   "due_date": "2020-01-14T00:00:00Z",
  //   "overdue": false,
  //   "remind_at": null,
  //   "resource_id": 29732437,
  //   "content": "Schedule a meeting",
  //   "created_at": "2019-10-01T09:00:21Z",
  //   "updated_at": "2019-10-01T09:00:21Z"
  // }
});
deal.tasks.completed

Fires when a current deal's task is marked as completed in the current tab. Any event handler bound to deal.tasks.completed receives the task object.

Example:

client.on('deal.tasks.completed', (task) => {
  console.log(task); // Task object
  // example:
  // {
  //   "id": 32661,
  //   "creator_id": 42616,
  //   "owner_id": 42616,
  //   "resource_type": "sales_account",
  //   "completed": true,
  //   "completed_at": "2019-12-14T09:00:11Z",
  //   "due_date": "2020-01-14T00:00:00Z",
  //   "overdue": false,
  //   "remind_at": null,
  //   "resource_id": 29732437,
  //   "content": "Schedule a meeting",
  //   "created_at": "2019-10-01T09:00:21Z",
  //   "updated_at": "2019-10-01T09:00:21Z"
  // }
});

Deal object

The Deals API provides a simple interface to manage 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 is set automatically when you associate a deal with a primary contact which belongs to a company.

deal

Retrieves the deal object with some of its properties.

get
client.get('deal')
returns
{
  "deal": {
    "id": 4,
    "name": "Website Redesign",
    "value": "1000.50",
    "currency": "USD",
    "hot": true,
    "lastStageChangeAt": "2014-09-27T16:32:56Z",
    "dropboxEmail": "[email protected]",
    "estimatedCloseDate": "2015-06-19",
    "customizedWinLikelihood": 15,
    "tags": ["important"],
    "createdAt": "2014-09-27T16:32:56Z",
    "updatedAt": "2014-09-28T16:32:56Z"
  }
}

Properties

Actions

deal.id

The unique identifier of the deal.

get
client.get('deal.id')
returns
{
  "deal.id": 4
}
deal.creator

The user who created the deal.

get
client.get('deal.creator')
returns
{
  "deal.creator": {
    "id": 8
  }
}
deal.creator.id

The unique identifier of the user.

get
client.get('deal.creator.id')
returns
{
  "deal.creator.id": 8
}
deal.owner

The user the deal is currently assigned to.

get
client.get('deal.owner')

See the User object for the returned properties (deal.owner.*).

deal.name

Name of the deal.

get
client.get('deal.name')
returns
{
  "deal.name": "Website Redesign"
}
deal.value

Value of the deal in a currency specified in the currency field.

get
client.get('deal.value')
returns
{
  "deal.value": "1000.50"
}
deal.currency

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

get
client.get('deal.currency')
returns
{
  "deal.currency": "USD"
}
deal.hot

Whether or not the deal is hot.

get
client.get('deal.hot')
returns
{
  "deal.hot": true
}
deal.stage

Deal's current stage in the pipeline.

get
client.get('deal.stage')
returns
{
  "deal.stage": {
    "id": 1
  }
}
deal.stage.id

Unique identifier of the deal's current stage in the pipeline.

get
client.get('deal.stage.id')
returns
{
  "deal.stage.id": 1
}
deal.lastStageChangeAt

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

get
client.get('deal.lastStageChangeAt')
returns
{
  "deal.lastStageChangeAt": "2014-09-27T16:32:56Z"
}
deal.lastStageChangeBy

The user who moved the deal into the current stage.

get
client.get('deal.lastStageChangeBy')

See the User object for the returned properties (deal.lastStageChangeBy.*).

deal.source

Source of the deal.

get
client.get('deal.source')
returns
{
  "deal.source": {
    "id": 10
  }
}
deal.source.id

Unique identifier of the source.

get
client.get('deal.source.id')
returns
{
  "deal.source.id": 10
}
deal.lossReason

Reason why the deal was lost.

get
client.get('deal.lossReason')
returns
{
  "deal.lossReason": {
    "id": 20
  }
}
deal.lossReason.id

Unique identifier of the loss reason.

get
client.get('deal.lossReason.id')
returns
{
  "deal.lossReason.id": 20
}
deal.unqualifiedReason

Reason why the deal was unqualified.

get
client.get('deal.unqualifiedReason')
returns
{
  "deal.unqualifiedReason": {
    "id": 32
  }
}
deal.unqualifiedReason.id

Unique identifier of the unqualified reason.

get
client.get('deal.unqualifiedReason.id')
returns
{
  "deal.unqualifiedReason.id": 32
}
deal.dropboxEmail

Dropbox email connected with the deal.

get
client.get('deal.dropboxEmail')
returns
{
  "deal.dropboxEmail": "[email protected]"
}
deal.contact

Primary contact.

get
client.get('deal.contact')
returns
{
  "deal.contact": {
    "id": 4,
    "isOrganization": false,
    "name": "Design Services Company",
    "firstName": "Mark",
    "lastName": "Johnson",
    "customerStatus": "current",
    "prospectStatus": "none",
    "title": "CEO",
    "description": "I know him via Tom",
    "industry": "Design Services",
    "website": "www.designservices.com",
    "email": "[email protected]",
    "phone": "508-778-6516",
    "mobile": "508-778-6516",
    "fax": "+44-208-1234567",
    "twitter": "mjohnson",
    "facebook": "mjohnson",
    "linkedin": "mjohnson",
    "skype": "mjohnson",
    "address": null,
    "billingAddress": null,
    "shippingAddress": null,
    "tags": ["important"],
    "createdAt": "2014-09-27T16:32:56Z",
    "updatedAt": "2014-09-28T16:32:56Z"
  }
}
deal.contact.id

The unique identifier of the contact.

get
client.get('deal.contact.id')
returns
{
  "deal.contact.id": 4
}
deal.contact.creator

The user who created the contact.

get
client.get('deal.contact.creator')

See the User object for the returned properties (deal.contact.creator.*).

deal.contact.owner

The user the contact is currently assigned to.

get
client.get('deal.contact.owner')

See the User object for the returned properties (deal.contact.owner.*).

deal.contact.isOrganization

Whether or not this contact refers to an organization or an individual. This value can be set only during creation and cannot be changed later. The default value is false.

get
client.get('deal.contact.isOrganization')
returns
{
  "deal.contact.isOrganization": false
}
deal.contact.contact

The organization the contact belongs to. The field is set only if the contact is an individual.

get
client.get('deal.contact.contact')

See the Contact object for the returned properties (deal.contact.contact.*).

deal.contact.parentOrganization

An organization contact that is parent of this organization. The field is set only if the contact is an organization and has parent.

get
client.get('deal.contact.parentOrganization')

See the Contact object for the returned properties (deal.contact.parentOrganization.*).

deal.contact.name

Name of the contact. Required only if the contact is an organization.

get
client.get('deal.contact.name')
returns
{
  "deal.contact.name": "Design Services Company"
}
deal.contact.firstName

First name of the contact.

get
client.get('deal.contact.firstName')
returns
{
  "deal.contact.firstName": "Mark"
}
deal.contact.lastName

Last name of the contact. Required only if the contact is an individual.

get
client.get('deal.contact.lastName')
returns
{
  "deal.contact.lastName": "Johnson"
}
deal.contact.customerStatus

The customer status of the contact. The status can be "none", "current", or "past".

get
client.get('deal.contact.customerStatus')
returns
{
  "deal.contact.customerStatus": "current"
}
deal.contact.prospectStatus

The prospect status of the contact. The status can be "none", "current", or "lost".

get
client.get('deal.contact.prospectStatus')
returns
{
  "deal.contact.prospectStatus": "none"
}
deal.contact.title

The contact's job title.

get
client.get('deal.contact.title')
returns
{
  "deal.contact.title": "CEO"
}
deal.contact.description

The contact's description.

get
client.get('deal.contact.description')
returns
{
  "deal.contact.description": "I know him via Tom"
}
deal.contact.industry

The contact's industry.

get
client.get('deal.contact.industry')
returns
{
  "deal.contact.industry": "Design Services"
}
deal.contact.website

The contact's website address.

get
client.get('deal.contact.website')
returns
{
  "deal.contact.website": "www.designservices.com"
}
deal.contact.email

The contact's email address.

get
client.get('deal.contact.email')
returns
{
  "deal.contact.email": "[email protected]"
}
deal.contact.phone

The contact's phone number.

get
client.get('deal.contact.phone')
returns
{
  "deal.contact.phone": "508-778-6516"
}
deal.contact.mobile

The contact's mobile phone number.

get
client.get('deal.contact.mobile')
returns
{
  "deal.contact.mobile": "508-778-6516"
}
deal.contact.fax

The contact's fax number.

get
client.get('deal.contact.fax')
returns
{
  "deal.contact.fax": "+44-208-1234567"
}
deal.contact.twitter

The contact's Twitter handle.

get
client.get('deal.contact.twitter')
returns
{
  "deal.contact.twitter": "mjohnson"
}
deal.contact.facebook

The contact's Facebook nickname.

get
client.get('deal.contact.facebook')
returns
{
  "deal.contact.facebook": "mjohnson"
}
deal.contact.linkedin

The contact's LinkedIn nickname.

get
client.get('deal.contact.linkedin')
returns
{
  "deal.contact.linkedin": "mjohnson"
}
deal.contact.skype

The contact's Skype nickname.

get
client.get('deal.contact.skype')
returns
{
  "deal.contact.skype": "mjohnson"
}
deal.contact.address

The contact's address.

get
client.get('deal.contact.address')
returns
{
  "deal.contact.address": {
    "line1": "2726 Smith Street",
    "city": "Hyannis",
    "postalCode": "02601",
    "state": "MA",
    "country": "US"
  }
}
deal.contact.address.line1

First line of the address. Example: number and street name.

get
client.get('deal.contact.address.line1')
returns
{
  "deal.contact.address.line1": "2726 Smith Street"
}
deal.contact.address.city

City name.

get
client.get('deal.contact.address.city')
returns
{
  "deal.contact.address.city": "Hyannis"
}
deal.contact.address.postalCode

Zip code or equivalent.

get
client.get('deal.contact.address.postalCode')
returns
{
  "deal.contact.address.postalCode": "02601"
}
deal.contact.address.state

State name.

get
client.get('deal.contact.address.state')
returns
{
  "deal.contact.address.state": "MA"
}
deal.contact.address.country

Country name.

get
client.get('deal.contact.address.country')
returns
{
  "deal.contact.address.country": "US"
}
deal.contact.billingAddress

The customers's billing address. Applicable only if either customerStatus or prospectStatus is not none.

get
client.get('deal.contact.billingAddress')

See the Address object for the returned properties (deal.contact.billingAddress.*).

deal.contact.shippingAddress

The customers's billing address. Applicable only if either customerStatus or prospectStatus is not none.

get
client.get('deal.contact.shippingAddress')

See the Address object for the returned properties (deal.contact.shippingAddress.*).

deal.contact.tags

An array of tags for the contact.

get
client.get('deal.contact.tags')
returns
{
  "deal.contact.tags": ["important"]
}
deal.contact.customFields

Custom fields are a key-value pair attached to a contact.

get
client.get('deal.contact.customFields')

See the Custom Fields object for the returned properties (deal.contact.customFields.*).

deal.contact.customFields:fieldName

Retrieves the value of a custom field. Add the custom field name to the path of the request after a colon.

get
client.get('deal.contact.customFields:my custom field name')
retuns
{
  "deal.contact.customFields:my custom field name": "my value"
}

See Custom Fields in the Sell REST API docs for possible return types.

deal.contact.createdAt

Contact's creation date and time (UTC, ISO8601 format).

get
client.get('deal.contact.createdAt')
returns
{
  "deal.contact.createdAt": "2014-09-27T16:32:56Z"
}
deal.contact.updatedAt

Contact's last update date and time (UTC, ISO8601 format).

get
client.get('deal.contact.updatedAt')
returns
{
  "deal.contact.updatedAt": "2014-09-28T16:32:56Z"
}
deal.organization

Associated organization.

get
client.get('deal.organization')

See the Contact object for the returned properties (deal.organization.*).

deal.estimatedCloseDate

Estimated close date of the deal.

get
client.get('deal.estimatedCloseDate')
returns
{
  "deal.estimatedCloseDate": "2015-06-19"
}
deal.customizedWinLikelihood

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

get
client.get('deal.customizedWinLikelihood')
returns
{
  "deal.customizedWinLikelihood": 15
}
deal.tags

An array of tags for the deal.

get
client.get('deal.tags')
returns
{
  "deal.tags": ["important"]
}
deal.customFields

Custom fields are a key-value pair attached to a deal.

get
client.get('deal.customFields')
returns
{
  "deal.customFields": ['Last Location', 'Current Vendor', 'my custom field name']
}
deal.customFields:fieldName

Retrieves the value of a custom field. Add the custom field name to the path of the request after a colon.

get
client.get('deal.customFields:my custom field name')
retuns
{
  "deal.customFields:my custom field name": "my value"
}

See Custom Fields in the Sell REST API docs for possible return types.

deal.createdAt

Deal's creation date and time (UTC, ISO8601 format).

get
client.get('deal.createdAt')
returns
{
  "deal.createdAt": "2014-09-27T16:32:56Z"
}
deal.updatedAt

Deal's last update date and time (UTC, ISO8601 format).

get
client.get('deal.updatedAt')
returns
{
  "deal.updatedAt": "2014-09-28T16:32:56Z"
}
deal.notes
deal.notes.create

Creates a note for the deal.

invoke
client.invoke('deal.notes.create', 'Called them, but no answer.');
argument
  • Content of the note (string)
returns
{
  "deal.notes.create": {
    "id": 32661,
    "creator_id": 42616,
    "resource_type": "sales_account",
    "resource_id": 29732437,
    "content": "Called them, but no answer",
    "created_at": "2019-10-01T09:00:21Z",
    "updated_at": "2019-10-01T09:00:21Z"
  }
}
deal.tasks
deal.tasks.create

Creates a task for the deal.

invoke
client.invoke('deal.tasks.create', 'Schedule a meeting', '2020-01-14');
arguments
  • Content of the task (string)
  • Due date of the task (string)
returns
{
  "deal.tasks.create": {
    "id": 32661,
    "creator_id": 42616,
    "owner_id": 42616,
    "resource_type": "sales_account",
    "completed": false,
    "completed_at": null,
    "due_date": "2020-01-14T00:00:00Z",
    "overdue": false,
    "remind_at": null,
    "resource_id": 29732437,
    "content": "Schedule a meeting",
    "created_at": "2019-10-01T09:00:21Z",
    "updated_at": "2019-10-01T09:00:21Z"
  }
}