Company sidebar

Company sidebar

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

Example manifest

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

The following object is available in this location:

• Contact object

Events

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

• contact.notes.added
• contact.tasks.added
• contact.tasks.completed

You can also listen for changes on any object or property of the Contact 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('contact.creator.changed', (data) => {
  console.log(data);  // {propertyName, oldValue, newValue}
});

See Working with framework events.

contact.notes.added

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

Example:

client.on('contact.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"
  // }
});

contact.tasks.added

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

Example:

client.on('contact.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"
  // }
});

contact.tasks.completed

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

Example:

client.on('contact.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"
  // }
});

Contact object

A contact represents an individual (such as Mark Johnson) or an organization (such as Google). Each contact has two status fields: customerStatus and prospectStatus. They describe the contact's relationship to your business.

Types of contacts:

• Regular Contact - a person or an organization you know, but with whom you have not initiated a business relationship yet
• Current Prospect - a person or an organization that you are actively selling to
• Lost Prospect - a person or an organization that you have tried to sell to in the past, but were unable to complete a deal. Lost prospects have never been customers before
• Current Customer - a person or an organization that currently buys goods or services from your business
• Past Customer - a person or an organization that previously bought goods or services from your business, but no longer does so

You can assign any number of tags and custom fields to a contact. Tags do not need to already exist to be assigned; they will be created if necessary.

contact

Retrieves the contact object with some of its properties.

get

client.get('contact')
// also: client.get('contact.contact')
// also: client.get('contact.parentOrganization')

returns

{
  "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"
  }
}

Properties

• contact.address (object)
• contact.address.city (property)
• contact.address.country (property)
• contact.address.line1 (property)
• contact.address.postalCode (property)
• contact.address.state (property)
• contact.billingAddress (object)
• contact.contact (object)
• contact.createdAt (property)
• contact.creator (object)
• contact.creator.id (property)
• contact.customFields (property)
• contact.customerStatus (property)
• contact.description (property)
• contact.email (property)
• contact.facebook (property)
• contact.fax (property)
• contact.firstName (property)
• contact.id (property)
• contact.industry (property)
• contact.isOrganization (property)
• contact.lastName (property)
• contact.linkedin (property)
• contact.mobile (property)
• contact.name (property)
• contact.notes (object)
• contact.owner (object)
• contact.parentOrganization (object)
• contact.phone (property)
• contact.prospectStatus (property)
• contact.shippingAddress (object)
• contact.skype (property)
• contact.tags (property)
• contact.tasks (object)
• contact.title (property)
• contact.twitter (property)
• contact.updatedAt (property)
• contact.website (property)

Actions

• contact.notes.create
• contact.tasks.create

contact.id

The unique identifier of the contact.

get

client.get('contact.id')

returns

{
  "contact.id": 4
}

contact.creator

The user who created the contact.

get

client.get('contact.creator')

returns

{
  "contact.creator": {
    "id": 8
  }
}

contact.creator.id

The unique identifier of the user.

get

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

returns

{
  "contact.creator.id": 8
}

contact.owner

The user the contact is currently assigned to.

get

client.get('contact.owner')

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

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('contact.isOrganization')

returns

{
  "contact.isOrganization": false
}

contact.contact

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

get

client.get('contact.contact')

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

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('contact.parentOrganization')

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

contact.name

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

get

client.get('contact.name')

returns

{
  "contact.name": "Design Services Company"
}

contact.firstName

First name of the contact.

get

client.get('contact.firstName')

returns

{
  "contact.firstName": "Mark"
}

contact.lastName

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

get

client.get('contact.lastName')

returns

{
  "contact.lastName": "Johnson"
}

contact.customerStatus

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

get

client.get('contact.customerStatus')

returns

{
  "contact.customerStatus": "current"
}

contact.prospectStatus

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

get

client.get('contact.prospectStatus')

returns

{
  "contact.prospectStatus": "none"
}

contact.title

The contact's job title.

get

client.get('contact.title')

returns

{
  "contact.title": "CEO"
}

contact.description

The contact's description.

get

client.get('contact.description')

returns

{
  "contact.description": "I know him via Tom"
}

contact.industry

The contact's industry.

get

client.get('contact.industry')

returns

{
  "contact.industry": "Design Services"
}

contact.website

The contact's website address.

get

client.get('contact.website')

returns

{
  "contact.website": "www.designservices.com"
}

contact.email

The contact's email address.

get

client.get('contact.email')

returns

{
  "contact.email": "[email protected]"
}

contact.phone

The contact's phone number.

get

client.get('contact.phone')

returns

{
  "contact.phone": "508-778-6516"
}

contact.mobile

The contact's mobile phone number.

get

client.get('contact.mobile')

returns

{
  "contact.mobile": "508-778-6516"
}

contact.fax

The contact's fax number.

get

client.get('contact.fax')

returns

{
  "contact.fax": "[phone]"
}

contact.twitter

The contact's X (formerly Twitter) handle.

get

client.get('contact.twitter')

returns

{
  "contact.twitter": "mjohnson"
}

contact.facebook

The contact's Facebook nickname.

get

client.get('contact.facebook')

returns

{
  "contact.facebook": "mjohnson"
}

contact.linkedin

The contact's LinkedIn nickname.

get

client.get('contact.linkedin')

returns

{
  "contact.linkedin": "mjohnson"
}

contact.skype

The contact's Skype nickname.

get

client.get('contact.skype')

returns

{
  "contact.skype": "mjohnson"
}

contact.address

The contact's address.

get

client.get('contact.address')

returns

{
  "contact.address": {
    "line1": "2726 Smith Street",
    "city": "Hyannis",
    "postalCode": "02601",
    "state": "MA",
    "country": "US"
  }
}

contact.address.line1

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

get

client.get('contact.address.line1')

returns

{
  "contact.address.line1": "2726 Smith Street"
}

contact.address.city

City name.

get

client.get('contact.address.city')

returns

{
  "contact.address.city": "Hyannis"
}

contact.address.postalCode

Zip code or equivalent.

get

client.get('contact.address.postalCode')

returns

{
  "contact.address.postalCode": "02601"
}

contact.address.state

State name.

get

client.get('contact.address.state')

returns

{
  "contact.address.state": "MA"
}

contact.address.country

Country name.

get

client.get('contact.address.country')

returns

{
  "contact.address.country": "US"
}

contact.billingAddress

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

get

client.get('contact.billingAddress')

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

contact.shippingAddress

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

get

client.get('contact.shippingAddress')

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

contact.tags

An array of tags for the contact.

get

client.get('contact.tags')

returns

{
  "contact.tags": ["important"]
}

contact.customFields

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

get

client.get('contact.customFields')

returns

{
  "contact.customFields": ['Last Location', 'Current Vendor', 'my custom field name']
}

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('contact.customFields:my custom field name')

retuns

{
  "contact.customFields:my custom field name": "my value"
}

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

contact.createdAt

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

get

client.get('contact.createdAt')

returns

{
  "contact.createdAt": "2014-09-27T16:32:56Z"
}

contact.updatedAt

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

get

client.get('contact.updatedAt')

returns

{
  "contact.updatedAt": "2014-09-28T16:32:56Z"
}

contact.notes

contact.notes.create

Creates a note for the contact.

invoke

client.invoke('contact.notes.create', 'Called them, but no answer.');

argument

• Content of the note (string)

returns

{
  "contact.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"
  }
}

contact.tasks

contact.tasks.create

Creates a task for the contact.

invoke

client.invoke('contact.tasks.create', 'Schedule a meeting', '2020-01-14');

arguments

• Content of the task (string)
• Due date of the task (string)

returns

{
  "contact.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"
  }
}