API documentation

Entities and Relationships

At its core, Nutshell tracks objects such as contacts and accounts (known in the Nutshell world as "entities") and the relationships ("maps") between these entities.

Entities returned by the API contain an entityType field which tells API consumers about the entity. (Examples of entityTypes include Users, Teams, Accounts, Contacts.)

To show related entities, the API embeds stubs of these relationships in API responses. For example, a lead returned by the API has an array called contacts which includes a stub for each contact related to the Lead.


For certain API calls, it does not make sense (for performance or bandwidth reasons) for Nutshell to return a full entity complete with all its details. In these cases, the Nutshell API returns "stub" responses.

A stub includes only the most important information about an entity. A stub is indicated by the property "stub": true on the entity.

Stubs use fewer server resources and consume less bandwidth - especially important if your API consumer is a mobile device.

This is a stub for a hypothetical lead:

    "stub":               true,
    "id":                 145,
    "entityType":         "Leads",
    "rev":                "5",
    "name":               "Lead–145",
    "status":             10,
    "completion":         100,
    "value": {
        "currency":       "USD",
        "amount":         1780
    "primaryAccountName": "Auto-Owners Insurance",
    "dueTime":            "2010-07-18T12:00:00+0000",
    "closedTime":         "2010-07-18T12:00:00+0000"

Stubs are typically returned when an entity is embedded inside another for an API response (for example, an account or contact included in a lead) and optionally for some find* and search* API methods.

Entity types

Use the entityType key on a given API response object to determine its type. Entity types returned by the API are strings, and they are English plural nouns. This is an incomplete list of entityTypes returned by the API, with links to documentation on their structure.

Notes do not currently return their entityType. They may appear in the notes array for Accounts, Contacts, and Leads; and a single note may appear in the logNote key for an Activity.


Leads are the single entity type in Nutshell which has the most relationships. Each Lead can be associated with multiple Processes, Sources, Competitors, Products, Contacts, Accounts, and Notes.

Each Lead also includes exactly one:

  • creator (a User)
  • primaryAccount (an Account)
  • milestone (a Milestone)
  • market (a Market)
  • assignee (a User or Team)

Activities have a few relationships. They include one Activity_Type and may include one User (if the Activity has been logged; in the loggedBy key). Activities also have a one-to-many relationship with their participants. Participants may be Users or Contacts.

Accounts and Contacts have a two-way one-to-many relationship. Each Account may be related to multiple Contacts; similarly, each Contact may be related to multiple Accounts. Each Account knows about its Contacts and vice-versa. Because of this two-way awareness, Account-Contact relationships may be modified, added, or removed using both the editContact and editAccount API methods.

Previously Accounts and Contacts mapped to a Lead contained a relationship field consisting of an optional text description of the relationship. In October 2012 this field was removed and is replaced with a single description field on the Account or Contact directly.