Nutshell CRM API Basics for Leads, Contacts and Accounts
A form on your website should create a lead in Nutshell, or a lead marked won should open a job in the system your team schedules from. Both run through Nutshell's API, and it has fewer moving parts than most CRMs: one host, one sign-in style for every request, and record IDs that carry their own type, like 1003-leads.
It does its own job well, but your accounting software and support desk never see the deal.
Stuck on Nutshell? Let's solve it →Docs: developers.nutshell.com. The REST API is where Nutshell says to start. The older JSON-RPC API still works but gets no new endpoints.
Key: generated in the Nutshell web app.
Setup › API keysAuth: HTTP Basic on every request, with a Nutshell user's email address as the username and the API key as the password. HTTPS only, on app.nutshell.com.
First call: GET https://app.nutshell.com/rest/accounts. In the API, companies are accounts and people are contacts.
Nutshell's two APIs, and which one new code should use
REST API
- Resources sit under
https://app.nutshell.com/rest/, such as/rest/leads,/rest/contactsand/rest/activities. - Edits are
PATCHrequests with a JSON Patch body andcontent-type: application/json-patch+json. - IDs name their type:
3-contacts,1003-leads,1-outcomes. Store the whole string. - Winning or losing a lead is its own call:
POST /rest/leads/{id}/statuswith anoutcomeId.
JSON-RPC API
- One endpoint,
https://app.nutshell.com/api/v1/json. The body names the method, e.g.getLeadwithleadIdinparams. - The Basic auth username can be your company's domain or a user's email. The password is always an API key.
- Every
edit*method needs the record'srev. A stale one fails with a 409, andREV_IGNOREskips the check, which the docs say to use with caution. findcalls that return full records rather than stubs are rate limited. Add and edit calls aren't.
Write new integrations against REST. Leave a working JSON-RPC script alone until it needs something only the REST side will ever get, then move it.
Five Nutshell API requests, in the order a sync needs them
- 1
Generate a key for the integration
Setup › API keysDecide which user's email the integration will send with the key. Before using your own data, the authentication guide publishes sandbox credentials you can call right away.
- 2
Read accounts
curl -u you@yourcompany.com:YOUR_API_KEY https://app.nutshell.com/rest/accountsreturns companies. Swap in/rest/contactsfor people or/rest/leadsfor what other CRMs call deals.Watch for: the vocabulary. A pipeline shows up as a stageset and a stage as a milestone.
- 3
Change one field on a contact
PATCH /rest/contacts/3-contactswith[{"op": "replace", "path": "/contacts/0/firstName", "value": "Nutty"}]. Custom fields are patched the same way, by field name in the path.Watch for: the content type. JSON Patch requests send
application/json-patch+json, not plainapplication/json. - 4
Set the outcome on a lead
POST /rest/leads/1003-leads/statuswith{"outcomeId": "1-outcomes"}. Fetch the list of lead outcomes first so the integration uses your account's IDs for won, lost and canceled. - 5
Add an outgoing webhook
Setup › API keysWebhooks are set up in the web app, and Nutshell POSTs JSON to the URL you give it when people, companies, leads or activities change, a booking comes in, or a Nutshell form is submitted.
Watch for: the firehose. Every webhook gets every event, so filter for the few that matter. The guide doesn't describe retries or request signing, so put an unguessable token in the URL and run a nightly pass over the timeline events list.
Nutshell jobs that need no API code
Check the Nutshell integrations directory before writing anything. It spans phones, calendars, forms, e-signature, help desks and accounting, and its QuickBooks Online connection already creates invoices from a lead. Nutshell also lists Zapier among its developer options for short handoffs.
For reporting, Enterprise accounts can ask Nutshell for SQL Access, now in Early Access. It's a read-only MySQL connection set up with Nutshell's team, and it can't join Nutshell data to your other systems, so a report that mixes pipeline with finance numbers still means loading both into one warehouse.
n-frames builds the parts those routes leave out: a won lead opening the job in the field or project system your team works from, a web lead checked against existing accounts before a duplicate is created, or a nightly copy of Nutshell data landing beside your finance numbers.
Nutshell pricing, login and API questions
How much does Nutshell cost?
Nutshell charges per user, billed monthly or yearly, and higher tiers add automation, forecasting and support. Current figures are on nutshell.com's pricing page. Two API-side extras depend on what you buy: SQL Access is an Enterprise feature, and sending Nutshell invoices to QuickBooks needs the Proposals & Invoices add-on.
Does Nutshell have an API?
It has two. The REST API covers accounts, contacts, leads, activities, notes, tasks, products, quotes and invoices, and it's where new endpoints go. The JSON-RPC API is the older one, still supported but frozen. Both take HTTP Basic auth with an API key as the password, and webhooks sit alongside them.
Is there a Nutshell mobile app?
Yes. Nutshell has iOS and Android apps, so reps can update a lead or log a call away from a desk. Changes made there land on the same records the API reads.
What is Nutshell Mail, and how is it different from Nutshell the CRM?
Nothing to do with the CRM. NutshellMail was a separate social-media email digest that Constant Contact acquired in 2010. It isn't part of Nutshell or its API, so you can ignore it when you're evaluating either.
What are good alternatives to Nutshell?
Pipedrive, HubSpot and Salesforce sit in the same space, each trading price, complexity and depth differently. If you'll be integrating, weigh the APIs too: how they authenticate, how webhooks behave, and how many calls a plan allows. Our Pipedrive API and HubSpot API pages cover two of them.
Where do I log into Nutshell?
Use the sign-in link on nutshell.com, which opens the app on app.nutshell.com. That's also the only host the API answers on.
Who builds integrations on the Nutshell CRM API?
n-frames writes them for teams on Nutshell: lead intake from forms and other tools, won leads passed to the system that delivers the work, and webhook receivers that act on the handful of events that matter. We use the REST API for new work and the JSON-RPC API only where an existing script already depends on it.