Deal sidebar

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:

• Deal object

Events

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

• deal.notes.added
• deal.tasks.added
• deal.tasks.completed

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

• deal.contact (object)
• deal.contact.address (object)
• deal.contact.address.city (property)
• deal.contact.address.country (property)
• deal.contact.address.line1 (property)
• deal.contact.address.postalCode (property)
• deal.contact.address.state (property)
• deal.contact.billingAddress (object)
• deal.contact.contact (object)
• deal.contact.createdAt (property)
• deal.contact.creator (object)
• deal.contact.customFields (property)
• deal.contact.customerStatus (property)
• deal.contact.description (property)
• deal.contact.email (property)
• deal.contact.facebook (property)
• deal.contact.fax (property)
• deal.contact.firstName (property)
• deal.contact.id (property)
• deal.contact.industry (property)
• deal.contact.isOrganization (property)
• deal.contact.lastName (property)
• deal.contact.linkedin (property)
• deal.contact.mobile (property)
• deal.contact.name (property)
• deal.contact.owner (object)
• deal.contact.parentOrganization (object)
• deal.contact.phone (property)
• deal.contact.prospectStatus (property)
• deal.contact.shippingAddress (object)
• deal.contact.skype (property)
• deal.contact.tags (property)
• deal.contact.title (property)
• deal.contact.twitter (property)
• deal.contact.updatedAt (property)
• deal.contact.website (property)
• deal.createdAt (property)
• deal.creator (object)
• deal.creator.id (property)
• deal.currency (property)
• deal.customFields (property)
• deal.customizedWinLikelihood (property)
• deal.dropboxEmail (property)
• deal.estimatedCloseDate (property)
• deal.hot (property)
• deal.id (property)
• deal.lastStageChangeAt (property)
• deal.lastStageChangeBy (object)
• deal.lossReason (property)
• deal.lossReason.id (property)
• deal.name (property)
• deal.notes (object)
• deal.organization (object)
• deal.owner (object)
• deal.source (object)
• deal.source.id (property)
• deal.stage (property)
• deal.stage.id (property)
• deal.tags (property)
• deal.tasks (object)
• deal.unqualifiedReason (property)
• deal.unqualifiedReason.id (property)
• deal.updatedAt (property)
• deal.value (property)

Actions

• deal.notes.create
• deal.tasks.create

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": "[phone]",
    "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": "[phone]"
}

deal.contact.twitter

The contact's X (formerly 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"
  }
}