A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Nutshell API is how an app or AI agent works with a Nutshell CRM account: finding and creating leads, adding people and companies, logging activities, and reading the pipeline a sales team sells through. Access is granted with an API key tied to a Nutshell user, and there are no per-method permissions, so a key inherits whatever that user can see and do. The REST API has no dated version and is updated continuously, and a record change can be pushed to a registered webhook.
How an app or AI agent connects to Nutshell determines what it can reach. There is a REST API for working with records, an older JSON-RPC API that Nutshell still supports, and a webhook channel for receiving changes, and each is governed by the API key behind it and the Nutshell user that key belongs to.
The primary API: resource-based endpoints for leads, contacts, accounts, activities, tasks, notes, products, pipelines, and more, served under app.nutshell.com/rest. It uses standard HTTP methods, JSON Patch for updates, and the JSON:API convention for links between records. A call authenticates with HTTP Basic auth using a user email and an API key.
The older API, where every call POSTs a method name and parameters to a single endpoint under app.nutshell.com/api/v1/json rather than addressing resources by URL. It is still supported indefinitely but no longer gains new methods. It authenticates with the same email and API key, and a discovery call (getApiForUsername) returns the host to use.
Nutshell POSTs a JSON payload to a registered URL when a record changes, covering people, companies, leads, activities, scheduler bookings, and form submissions. The payload names the entity, the action, the actor, and the changed fields. Nutshell recommends re-fetching the full record through the REST API rather than trusting the payload fields. Webhooks are configured under Setup then API keys.
A Nutshell user creates an API key under Setup then API keys. Requests send HTTP Basic auth where the username is that user's email address and the password is the API key. The key acts as the user, inheriting that user's access to records, since Nutshell has no per-endpoint scopes. All calls require HTTPS.
The Nutshell API is organized around the records a sales team works with, like leads, people, companies, activities, tasks, and notes. Each area has its own methods, and a write here changes the live CRM that the whole team sees.
Methods for finding and managing leads, Nutshell's word for a deal or sale in progress.
Methods for the people a team sells to.
Methods for the companies a team sells to.
Methods for logged and scheduled activities, like calls and meetings.
Methods for to-do tasks assigned to users.
Methods for notes attached to records.
Methods for products, pipelines, and the stages a lead moves through.
Methods for reading the team's users and managing tags and sources.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
LeadsMethods for finding and managing leads, Nutshell's word for a deal or sale in progress.6 | ||||||
| GET | /leads | Get a list of all leads and associated data, with filtering and paging. | read | — | Current | |
No per-endpoint scope; the key inherits the user's access. Large find requests are the most throttled. Acts onlead Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /leads/{id} | Retrieve a single lead by id. | read | — | Current | |
No per-endpoint scope; the key inherits the user's access. Acts onlead Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /leads | Create a new lead. | write | — | Current | |
No per-endpoint scope; the key inherits the user's access. Create requests are not rate limited. Acts onlead Permission (capability)None required VersionAvailable since the API’s base version Webhook event leadsRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /leads/{id} | Update a lead using JSON Patch operations. | write | — | Current | |
No per-endpoint scope; the key inherits the user's access. Adds append /- to the path; removes append the item id. Acts onlead Permission (capability)None required VersionAvailable since the API’s base version Webhook event leadsRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /leads/{id}/status | Update a lead's status to close it as won, lost, or canceled. | write | — | Current | |
Closes the deal; no per-endpoint scope, the key inherits the user's access. Acts onlead Permission (capability)None required VersionAvailable since the API’s base version Webhook event leadsRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /leads/{id} | Delete a lead. | write | — | Current | |
Removes the deal; an undelete endpoint can restore it. No per-endpoint scope. Acts onlead Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Contacts (People)Methods for the people a team sells to.4 | ||||||
| GET | /contacts | Get a list of all contacts (people), with filtering and paging. | read | — | Current | |
No per-endpoint scope; the key inherits the user's access. Acts oncontact Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /contacts/{id} | Retrieve a single contact by id. | read | — | Current | |
No per-endpoint scope; the key inherits the user's access. Acts oncontact Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /contacts | Create a new contact (person). | write | — | Current | |
No per-endpoint scope; the key inherits the user's access. Acts oncontact Permission (capability)None required VersionAvailable since the API’s base version Webhook event contactsRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /contacts/{id} | Update a contact using JSON Patch operations. | write | — | Current | |
No per-endpoint scope; the key inherits the user's access. Acts oncontact Permission (capability)None required VersionAvailable since the API’s base version Webhook event contactsRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Accounts (Companies)Methods for the companies a team sells to.4 | ||||||
| GET | /accounts | Get a list of all accounts (companies), with filtering and paging. | read | — | Current | |
No per-endpoint scope; the key inherits the user's access. Acts onaccount Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /accounts/{id} | Retrieve a single account (company) by id. | read | — | Current | |
No per-endpoint scope; the key inherits the user's access. Acts onaccount Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /accounts | Create a new account (company). | write | — | Current | |
No per-endpoint scope; the key inherits the user's access. Acts onaccount Permission (capability)None required VersionAvailable since the API’s base version Webhook event accountsRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /accounts/{id} | Update an account (company) using JSON Patch operations. | write | — | Current | |
No per-endpoint scope; the key inherits the user's access. Acts onaccount Permission (capability)None required VersionAvailable since the API’s base version Webhook event accountsRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ActivitiesMethods for logged and scheduled activities, like calls and meetings.3 | ||||||
| GET | /activities | Get a list of all activities, with filtering and paging. | read | — | Current | |
No per-endpoint scope; the key inherits the user's access. Acts onactivity Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /activities/{id} | Retrieve a single activity by id. | read | — | Current | |
No per-endpoint scope; the key inherits the user's access. Acts onactivity Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /activities | Create a new activity, like a logged call or a scheduled meeting. | write | — | Current | |
No per-endpoint scope; the key inherits the user's access. Acts onactivity Permission (capability)None required VersionAvailable since the API’s base version Webhook event activitiesRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
TasksMethods for to-do tasks assigned to users.3 | ||||||
| GET | /tasks | Get a list of all tasks, with filtering and paging. | read | — | Current | |
No per-endpoint scope; the key inherits the user's access. Acts ontask Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /tasks | Create a new task assigned to a user. | write | — | Current | |
No per-endpoint scope; the key inherits the user's access. Acts ontask Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /tasks/{id} | Update a task using JSON Patch operations. | write | — | Current | |
No per-endpoint scope; the key inherits the user's access. Acts ontask Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
NotesMethods for notes attached to records.2 | ||||||
| GET | /notes | Get a list of all notes, with filtering and paging. | read | — | Current | |
No per-endpoint scope; the key inherits the user's access. Acts onnote Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /notes | Create a note attached to a record. | write | — | Current | |
No per-endpoint scope; the key inherits the user's access. Acts onnote Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Products & PipelineMethods for products, pipelines, and the stages a lead moves through.5 | ||||||
| GET | /products | Get a list of all products in the catalog. | read | — | Current | |
No per-endpoint scope; the key inherits the user's access. Acts onproduct Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /leads/{id}/products | List the products attached to a lead. | read | — | Current | |
No per-endpoint scope; the key inherits the user's access. Acts onproduct Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /pipelines | List the sales pipelines configured in the account. | read | — | Current | |
No per-endpoint scope; the key inherits the user's access. Acts onpipeline Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /stages | List the stages a lead can move through across pipelines. | read | — | Current | |
No per-endpoint scope; the key inherits the user's access. Acts onstage Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /leads/{id}/pipeline | Set the pipeline a lead belongs to. | write | — | Current | |
Moves the deal between pipelines; no per-endpoint scope. Acts onpipeline Permission (capability)None required VersionAvailable since the API’s base version Webhook event leadsRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Users & TagsMethods for reading the team's users and managing tags and sources.4 | ||||||
| GET | /users | List the Nutshell users on the account. | read | — | Current | |
Returns the team roster, including names and email addresses. No per-endpoint scope. Acts onuser Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /tags | List the tags defined in the account. | read | — | Current | |
No per-endpoint scope; the key inherits the user's access. Acts ontag Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /tags | Create a new tag. | write | — | Current | |
No per-endpoint scope; the key inherits the user's access. Acts ontag Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /sources | List the lead sources defined in the account. | read | — | Current | |
No per-endpoint scope; the key inherits the user's access. Acts onsource Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Nutshell can notify an app when a record changes, like a lead moving to a new stage or a person being edited. It POSTs a payload describing what changed, which Nutshell recommends treating as a prompt to re-fetch the full record through the REST API rather than trusting the fields in the message.
| Event | What it signals | Triggered by |
|---|---|---|
leads (create / update) | A lead changed: an attribute edit, a stage transition, an outcome change (won, lost, or canceled), a value adjustment, a note, or a merge. The payload names the action and the changed fields. | /leads/leads/{id}/leads/{id}/status |
people (create / update) | A person (contact) changed: an attribute edit, a note, a file upload, a description update, an ownership change, or a merge. | /contacts/contacts/{id} |
companies (create / update) | A company (account) changed: an attribute edit, a note, a file, a description, an assignment update, or a merge. | /accounts/accounts/{id} |
activities (create / update) | An activity changed: a name, description, or time edit, or a status update such as scheduled, logged, or canceled. | /activities |
Nutshell does not publish fixed numeric rate limits. It throttles the heaviest read traffic, large list (find) requests and high volumes of single-record reads, and asks teams that need more to get in touch.
Nutshell does not publish fixed numeric rate limits. It applies throttling to the heaviest read traffic, specifically large list (find) requests that return full records and high volumes of single-record reads, while incoming create and edit requests are not rate limited. Teams that expect heavy usage or hit throttling are asked to contact Nutshell to discuss higher limits rather than relying on a published ceiling.
REST list endpoints page with two query parameters: page[page] selects the page using 0-based indexing, and page[limit] sets how many records come back per page. List endpoints also accept filter parameters in the form filter[type][]=value, including ranges, address subfields, and time ranges, to narrow results before paging.
Nutshell does not document a fixed maximum page size; page[limit] sets the records returned per page. A response follows the JSON:API shape, returning the requested records alongside related records and navigation links.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | Bad Request | The request was malformed, like an invalid filter, a bad JSON Patch operation, or a missing required field on a create. | Check the request body and query parameters against the endpoint reference, fix them, and resend. |
| 401 | Unauthorized | Authentication failed: the email and API key pair was missing, wrong, or sent without HTTPS. | Confirm the Basic-auth credentials use a valid user email and a current API key, and that the call is over HTTPS. |
| 403 | Forbidden | The authenticated user cannot perform this action on this record, because the key inherits that user's access and the user lacks it. | Use a key created under a Nutshell user that has access to the record or action. |
| 404 | Not Found | The record id does not exist, or is not visible to the user behind the key. | Verify the id and confirm the user can see the record. |
| 429 | Too Many Requests | Throttling kicked in, most often on large list (find) requests or a high volume of single reads. | Slow the request rate, page through large lists in smaller batches, and contact Nutshell if higher limits are needed. |
The REST API has no dated version to pin and is updated continuously, while the older JSON-RPC API is still supported but no longer gains new methods.
The REST API is Nutshell's primary API and carries no dated version to pin. It is resource-based, uses standard HTTP methods with JSON Patch for updates, and follows the JSON:API convention. Nutshell updates it continuously as new capabilities ship inside the product, so there is no version header to set.
The older JSON-RPC API posts a method name and parameters to a single endpoint. Nutshell continues to support and maintain it indefinitely for existing integrations but is no longer adding new methods, directing new work to the REST API.
There is no version header to set on the REST API; track the changelog for new capabilities.
Nutshell developer site ↗Bollard AI sits between a team's AI agents and Nutshell. Grant each agent exactly the access it needs, read or write, record type by record type, and every call is checked and logged.