Nutshell API Essential Guide

What type of API does Nutshell provide?

JSON-RPC API

Nutshell's primary API is a JSON-RPC API. Key points about this API include:

• It uses JSON-RPC v2.0 protocol and supports named parameters
• It is accessible via HTTPS and requires authentication using HTTP Basic auth
• It offers comprehensive functionality for retrieving and modifying data in Nutshell

HTTP POST API

Nutshell also offers a simpler HTTP POST API with more limited functionality:

• It can only be used to add contacts, accounts, or leads to Nutshell
• It cannot retrieve, edit, or delete data
• It is intended for simple form submissions from static websites

Webhooks API

Nutshell provides a Webhooks API that allows sending notifications to specified URLs when certain events occur in Nutshell.

Key Considerations

• The JSON-RPC API is the most full-featured option for integrating with Nutshell programmatically
• The HTTP POST API provides a simpler option for basic form submissions
• Authentication is required for all API calls except requests for the JSON-RPC SMD file
• Nutshell uses ETags for cache validation at the network level

In summary, while Nutshell offers multiple API options, its primary API is JSON-RPC based rather than a REST, GraphQL, or SOAP API. The JSON-RPC API provides the most comprehensive programmatic access to Nutshell's functionality.

Does the Nutshell API have webhooks?

Yes, the official Nutshell API does have webhooks. Here are the key points about Nutshell's webhook functionality:

Webhook Availability

Nutshell offers a Webhooks API that allows you to receive notifications when certain events occur in Nutshell. This eliminates the need to constantly poll the API for changes.

Event Types

You can subscribe to webhooks for changes to the following entity attributes in Nutshell:

• Leads
• Contacts
• Accounts
• Activities
• Products
• Competitors

Webhook Payload

When a qualifying event occurs, Nutshell sends a JSON payload to the URL you specify. This payload contains detailed information about the event, including:

• Event type (e.g., create, update)
• Entity affected
• Changes made
• Timestamps
• User who performed the action
• Related entities

Example Use Cases

Webhooks can be used for various purposes, such as:

• Updating external systems when leads are created or modified
• Triggering automated workflows based on Nutshell events
• Syncing Nutshell data with other applications in real-time

Implementation

To use webhooks, you need to:

1. Set up an endpoint on your server to receive the webhook payloads
2. Configure the webhook in your Nutshell account, specifying the events you want to subscribe to and the URL to receive notifications

Best Practices

• Implement proper security measures to validate incoming webhook requests
• Handle webhook payloads asynchronously to prevent timeouts
• Set up error handling and retry mechanisms for failed webhook deliveries

By utilizing Nutshell's webhook functionality, you can create more responsive and efficient integrations with your CRM data.

Rate Limits and other limitations

Here are the key points about the API Rate Limits for the Nutshell API:

Rate Limiting Approach

Nutshell takes a flexible approach to rate limiting:

• They make efforts to make data as accessible as possible, but implement some rate limits to maintain service quality.
• The degree of rate limiting may change depending on current conditions.

Specific Rate Limits

• Rate limits are primarily applied to certain large requests:

  • find requests (e.g. findLeads()) with non-stub responses are rate limited the most.
  • Excessive get requests (e.g. getContact()) are rate limited to a lesser extent.

• Incoming add or edit requests are not rate limited.

No Specific Numbers Provided

• The documentation does not provide specific numeric rate limits (e.g. requests per second).

Handling Rate Limits

• If you have questions about API usage or need higher limits, Nutshell encourages contacting their support.

Best Practices

• Use stub responses where possible to reduce load and avoid rate limits.
• Cache responses when appropriate to reduce API calls.
• Contact Nutshell support if you need higher rate limits for your use case.

Key Takeaway

Nutshell takes a flexible approach to rate limiting, focusing mainly on large find requests and excessive get requests. They don't publish specific numeric limits, but encourage users to contact them if they have concerns about API usage or need higher limits.

Latest API Version

The most recent version of the Nutshell API is api/v1.

Key points to consider:

1. api/v1 is currently the only valid version of the Nutshell API [1].

2. The API endpoint URL is constructed by appending the API version and "/json" to the domain, for example: https://app.nutshell.com/api/v1/json [1].

3. Nutshell uses JSON-RPC v2.0 and supports named parameters [1].

4. The API requires HTTPS for security [1].

5. Authentication is done using HTTP Basic authentication with either a company domain or user email as the username, and an API key as the password [1].

Best practices:

1. Cache the API endpoint URL returned by the endpoint discovery API for 10-90 minutes [1].

2. Use ETags for cache validation at the network level [1].

3. Implement the rev system for application-level cache control [1].

4. Handle potential errors, such as "rev key is out-of-date" (error code 409) [1].

5. Be cautious when using the "REV_IGNORE" option to bypass rev checks [1].

How to get a Nutshell developer account and API Keys?

To get a developer account for Nutshell to create an API integration, you need to follow these steps:

1. Create a Nutshell Account

First, you need to have a Nutshell account. If you don't already have one, you'll need to sign up for Nutshell's CRM service.

2. Access API Keys Section

Once you have a Nutshell account:

1. Log in to your Nutshell account
2. Click on your Avatar icon in the lower-left corner
3. Click on "Company settings"
4. Under the Connections heading, click on "API keys"

3. Create an API Key

To create a new API key:

1. Click on "(+) Add API key..."
2. Choose the appropriate permission type for your integration needs
3. Click "new API key"

Key Points to Consider:

• There are different types of API keys with varying levels of access:

  • API + user impersonation: This type is required for certain integrations, like Zapier.
  • Web-only: Used for creating basic HTML forms using Nutshell's minimal HTTP POST API.

• Treat your API key like a password, as it allows access to your Nutshell data.

• The API key you create will be used for authentication when making API calls.

Best Practices:

1. Choose the appropriate permission type for your integration to ensure you're not granting unnecessary access.
2. Keep your API key secure and don't share it publicly.
3. If you're building an integration, consider using the JSON-RPC API for more powerful functionality.
4. Familiarize yourself with Nutshell's API documentation for detailed information on endpoints and methods.

By following these steps, you'll have created a developer account (which is essentially your regular Nutshell account with API access) and obtained an API key to create your integration with Nutshell's API.

What can you do with the Nutshell API?

Based on the provided information, here's a list of data models you can interact with using the Nutshell API, along with what is possible for each:

Contacts (People)

• Retrieve contact information
• Create new contacts
• Edit existing contacts
• Search for contacts
• Associate contacts with leads and accounts

Accounts (Companies)

• Retrieve account information
• Create new accounts
• Edit existing accounts
• Search for accounts
• Associate accounts with leads and contacts

Leads

• Retrieve lead information
• Create new leads
• Edit existing leads
• Search for leads
• Change lead status (e.g., potential, won, lost)
• Move leads between stages and pipelines
• Associate leads with contacts, accounts, products, and competitors
• Add notes to leads
• Upload files to leads

Activities

• Retrieve activity information
• Create new activities
• Edit existing activities
• Log activities
• Associate activities with leads and participants

Products

• Retrieve product information
• Associate products with leads
• Specify quantity and price for products in leads

Competitors

• Retrieve competitor information
• Associate competitors with leads

Sources

• Retrieve source information
• Associate sources with leads

Tags

• Retrieve tag information
• Add or remove tags from leads

Users and Teams

• Retrieve user and team information
• Assign leads to users or teams

Custom Fields

• Retrieve custom field information
• Add custom field data to entities

Notes

• Add notes to various entities
• Retrieve note information

Files

• Upload and download files associated with entities

Markets

• Retrieve market information
• Associate markets with leads

Milestones (Stages)

• Retrieve milestone information
• Move leads between milestones

Stagesets (Pipelines)

• Retrieve stageset information
• Move leads between stagesets

Tasks

• Retrieve task information
• Create and edit tasks

Industries

• Retrieve industry information
• Associate industries with accounts

This list covers the main data models and interactions possible with the Nutshell API. The API allows for creating, retrieving, updating, and deleting (CRUD) operations on most of these entities, as well as searching and associating them with each other.