Overview

The purpose of this guide is to give you a number of examples for how to perform common actions in Nutshell via the REST API. Before getting started, it's useful to familiarize yourself with common Nutshell terms and the format for API IDs. You will also need an auth token as explained in the 🔒 API authentication guide.

Endpoints

The following is a list of commonly used endpoints to perform certain actions within Nutshell. This is not an exhaustive list and neither are the options shown in each example. Please view the complete API reference for more details.

Account, Contact, and Lead endpoints

Accounts, contacts, and leads form the three core entities within Nutshell. Standard CRUD operations are shared across all three -- that is, the request format for updating a lead is the same as an account or contact just with a different endpoint and different API IDs. As always, view the API reference for more details.

Commonly used actions

To use the provided curl commands, you will have to replace <auth> with your base 64 encoded authorization token.

Get entity

Used to get information related to an individual account, contact, or lead. Objects are returned with a Links array which can be used to find information about related entities.

curl --request GET  
     --url <https://app.nutshell.com/rest/accounts/3-accounts>  
     --header 'accept: */*'  
     --header 'authorization: Basic <auth>’

Update entity (PATCH replace)

Used to update information related to an individual account, contact, or lead. Uses one of three operations (add, remove, replace). Path represents the sequence of index operations required to reach the value to be changed.

curl --request PATCH  
     --url <https://app.nutshell.com/rest/contacts/3-contacts>  
     --header 'authorization: Basic <auth>’  
     --header 'content-type: application/json-patch+json'  
     --data '  
[  
  {  
    "op": "replace",  
    "path": "/contacts/0/firstName",  
    "value": "Nutty"  
  }  
]  
'

Add a tag (PATCH add)

Used to add a tag to a core entity, allowing arbitrary items to be grouped together by a string. Note that tags are entity-specific; that is, when a tag is created it is created for an account, contact, or lead, and cannot be applied to the other two.

📘
Add operations
When performing an add operation you must add a "/-" to the end of the path.

curl --request PATCH  
     --url <https://app.nutshell.com/rest/contacts/3-contacts>  
     --header 'authorization: Basic <auth>’  
     --header 'content-type: application/json-patch+json'  
     --data '  
[  
  {  
    "op": "add",  
    "path": "/leads/0/links/tags/-",  
    "value": "15-tags"  
  }  
]  
'

Remove a tag (PATCH remove)

Removing is similar to adding, except the ID of the entity to remove is appended to the end of the path.

curl --request PATCH  
     --url <https://app.nutshell.com/rest/contacts/3-contacts>  
     --header 'authorization: Basic <auth>’  
     --header 'content-type: application/json-patch+json'  
     --data '  
[  
  {  
    "op": "remove",  
    "path": "/leads/0/links/tags/15-tags"  
  }  
]  
'

Add a product to a lead

Lead value is calculated by the products attached to a given lead, which can be added using the lead PATCH endpoint.

curl --request PATCH  
     --url <https://app.nutshell.com/rest/leads/1003-leads>  
     --header 'authorization: Basic \<auth’>  
     --header 'content-type: application/json-patch+json'  
     --data '  
[  
  {  
    "op": "add",  
    "path": "/leads/0/links/products/-",  
    "value": "3-products"  
  }  
]  
'

Modifying quantity/price

Products are mapped to leads by way of a product map. This mapping contains the price and quantity of a product for a given lead which can be modified to affect the overall lead value.

After getting a lead, you can get its associated product map IDs through the "links" property (lead[“links”][“productMaps”][0]). You can then use Get lead product to view information about the product mapping.

curl --request PATCH  
     --url <https://app.nutshell.com/rest/productmaps/167-productMaps>  
     --header 'authorization: Basic <auth>’  
     --header 'content-type: application/json-patch+json'  
     --data '  
[  
  {  
    "op": "replace",  
    "path": "/productMaps/0/quantity",  
    "value": "5"  
  }  
]  
'

Create/log an activity

Activities are used to track interactions between Nutshell users and contacts and can be created to represent events in the future or "logged" to represent completed activities.

curl --request POST  
     --url <https://app.nutshell.com/rest/activities>  
     --header 'accept: */*'
     --header 'authorization: Basic <auth>’  
     --header 'content-type: application/json-patch+json'  
     --data '  
{  
  "activities": \[  
    {  
      "name": "Learning about the Nutshell API",  
      "description": "Learning how to use the Nutshell REST API to perform common activities",  
      "note": "This note can only be seen inside of Nutshell, not by external users included on the activity",  
      "location": "Online",  
      "activityType": "1-activityTypes",  
      "startTime": 1747769351,  
      "endTime": 1747769851,  
      "isFlagged": false,  
      "isLogged": true,  
      "links": {  
        "participants": [  
          "1-users",  
          "3-contacts"  
        ]  
      }  
    }  
  ]  
}  
'

Creating a custom field

Custom fields allow arbitrary data to be stored on core entities in different formats such as dates, text, and numbers. Custom fields are specific to a core entity type -- that is, a custom field for a contact cannot be used for an account or lead. Custom fields can be created as follows, though the "choices" and "isMultiple" fields are only for Enum type fields.

curl --request POST  
     --url <https://app.nutshell.com/rest/leads/customfield>  
     --header 'authorization: Basic <auth>'  
     --header 'content-type: application/json'  
     --data '  
{  
  "name": "Coolness score",  
  "type": "Enum",  
  "choices": [  
    "0-5",  
    "6-10",  
    "11+"  
  ],  
  "isMultiple": false  
}  
'

Setting/updating a custom field

Custom fields can be added and updated on core entities similarly to manipulating other properties using the PATCH endpoint, with the end of the path value including the name of the custom field.

curl --request PATCH  
     --url <https://app.nutshell.com/rest/contacts/3-contacts>  
     --header 'authorization: Basic <auth>’  
     --header 'content-type: application/json-patch+json'  
     --data '  
[  
  {  
    "op": "replace",  
    "path": "/contacts/0/Important info",  
    "value": “Hello world”  
  }  
]  
'

Update lead status

This endpoint is used to mark leads as won, cancelled, or closed. A list of valid outcomes can be retrieved by making a GET request to the /outcomes endpoint.

curl --request POST  
     --url <https://app.nutshell.com/rest/leads/1003-leads/status>  
     --header 'accept: */*'
     --header 'authorization: Basic <auth>'  
     --header 'content-type: application/json'  
     --data '  
{  
  "outcomeId": "1-outcomes"  
}  
'