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.

Stubs

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.

• Accounts
• Activities
• Activity_Types
• Assignments
• Competitors
• Contacts
• Delays - Delay applied to a process Step
• Emails
• Files
• Industries
• Leads
• Markets
• Milestones
• Notes
• Origins - the origin of an entity (API, Web, iPhone)
• Processes
• Products
• Sources
• Steps
• Users

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.

Relationships

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)

Activites have a few relationships. They include one Activity_Type and may include one User (if the Activity has been logged; in the loggedBy key). Activites 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.