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:

Events

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

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": "+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"
  }
}

Properties

Actions

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": "+44-208-1234567"
}
contact.twitter

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