API documentation


The Nutshell API uses HTTP Basic authentication. All API calls, except requests for JSON-RPC's SMD file, must include the Authentication header.

The username for authentication is either your company's domain or a specific user's email address (see the Impersonation section, below). The password is always an API key.

The Nutshell API is accessible only via HTTPS to ensure that API keys and other sensitive information remain secure.

Here's an example cURL command that retrieves Lead-1000 from Nutshell's JSON-RPC API:

curl -u <domain or username>:<api token> \
-d '{ "id": "<id>", "method": "getLead", "params": { "leadId": 1000 } }' \



Each API key may allow or disallow "impersonation".

If impersonation is allowed for an API key, the API consumer may authenticate using any valid user's email address as the username. Any changes the API consumer makes will be logged as if that user had made the changes directly.

If impersonation is not permitted, the API consumer must authenticate using an email within the company's Nutshell application as the username. Any changes the API consumer makes will be logged using the API key's name (set when the key was created).


A web-only API key is used to create basic HTML forms using Nutshell's minimal HTTP POST API. Web-only API keys are created with the expectation that they may become public. They cannot be used for authentication to the JSON-RPC API.

Web-only API keys do not use HTTP Basic authentication, nor is impersonation available. See the HTTP POST API documentation for more information.

HTTP response codes

The Nutshell API will return the HTTP status code 401 (authorization required) if the Authentication header is missing or the username or API key is invalid.

The API will return an HTTP 200 status if the Authentication header is valid or authentication is not required.