> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns.
>
> **Recommended** (the `-y` flags skip prompts, so the command runs without an interactive terminal):
> ```bash
> npx -y @scalekit-inc/cli setup -y
> ```
>
> Global:
> ```bash
> npm install -g @scalekit-inc/cli
> scalekit setup -y
> ```
>
> Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for other Agent Skills-compatible agents in `~/.agents/skills`.
> Skills: integrate-agentkit, implement-saaskit, add-mcp-oauth, implement-sso, implement-scim.
> [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/)

---

# Connect AI agents to Nutshell

The Nutshell connector lets your AI agent act in each user's Nutshell account. Each user connects their own Nutshell API key once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 60 tools.

**Authentication:** Email and API Key
**Categories:** CRM & Sales
**Tools:** 60: 37 read, 17 write, 6 destructive
**Users sign in with:** Username and password
**Built by:** Scalekit connector
**Try it:** [Playground in the Scalekit dashboard](https://app.scalekit.com/ws/signup?sk_intent=playground&provider=NUTSHELL)

## Setup

1. ### Install the SDK

   **Node.js**

   ```bash
   npm install @scalekit-sdk/node dotenv
   ```

   **Python**

   ```bash
   pip install scalekit-sdk-python python-dotenv
   ```

2. ### Set your credentials

   Add your Scalekit credentials to your `.env` file. Find values in **[app.scalekit.com](https://app.scalekit.com)** > **Developers** > **API Credentials**.

   ```sh title=".env"
   SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
   SCALEKIT_CLIENT_ID=<your-client-id>
   SCALEKIT_CLIENT_SECRET=<your-client-secret>
   ```

3. ### Create the Nutshell connection

   In **AgentKit > Connections**, create a Nutshell connection. The name you give it is the `connection_name` your code passes. See [Configure connections](/agentkit/connections/).

## Tools

Pass the exact name to `execute_tool`, with an input like each tool's example. To ask for a tool that's missing, use the [request form](https://scalekitsupport.portal.usepylon.com/forms/request-a-connector-tool).

**Node.js**

```typescript
const result = await actions.executeTool({
  toolName: 'nutshell_account_get',
  toolInput: {
    id: '<id>',
  },
  connector: 'nutshell',
  identifier: 'user_123',
})
```

**Python**

```python
result = actions.execute_tool(
    tool_name="nutshell_account_get",
    tool_input={
        "id": "<id>",
    },
    connection_name="nutshell",
    identifier="user_123",
)
```

`result.data` is the app's response as JSON, and `result.execution_id` (`executionId` in Node.js) is the ID of the call.

### `nutshell_account_get`

Get Account · Read-only

Get one account (company) by ID. Returns the account with contact info, industry, owners, tags, linked contacts and leads. Use this when you know the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): Nutshell API ID of the account, in the form <number>-accounts. Example: 337-accounts.

Example input: `{"id":"<id>"}`

### `nutshell_account_types_list`

List Account Types · Read-only

List account types. Returns account types with id and name. Use this for an account's accountType link.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `nutshell_accounts_list`

List Accounts · Read-only

List accounts (companies) in Nutshell, optionally searched by name and sorted. Returns accounts with id, name, description, owners, emails, phones, urls, addresses and links, plus meta paging. Use this to find a company. Use nutshell_account_get for one account.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `page` (`integer`, optional): Page number, starting at 0. Example: 0.
- `page_limit` (`integer`, optional): Results per page (default 50). Example: 25.
- `q` (`string`, optional): Search text matched against account names. Example: Acme.
- `sort` (`string`, optional): Field to sort by; prefix with - for descending. Example: -modifiedTime.

Example input: `{}`

### `nutshell_activities_list`

List Activities · Read-only

List activities (calls, meetings, emails logged as activities), filtered by status, type, flag or date range. Returns activities with id, name, activityType, startTime, endTime, status, participants and leads. Use this to see scheduled or logged activities. Use nutshell_activity_get for one.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `activity_type` (`array`, optional): Activity type IDs from nutshell_activity_types_list. Example: ["1-activityTypes"]
- `date_max` (`string`, optional): Latest start date (YYYY-MM-DD). Example: 2026-01-31.
- `date_min` (`string`, optional): Earliest start date (YYYY-MM-DD). Example: 2026-01-01.
- `flagged` (`boolean`, optional): Only flagged activities. Example: true.
- `limit` (`integer`, optional): Maximum number of results. Example: 25.
- `participant` (`array`, optional): Participant IDs (users or contacts). Example: ["3-contacts"]
- `q` (`string`, optional): Search text matched against activity names. Example: Acme.
- `status` (`array`, optional): Statuses to include (e.g. scheduled, logged, overdue, cancelled). Example: ["scheduled"]

Example input: `{}`

### `nutshell_activity_get`

Get Activity · Read-only

Get one activity by ID. Returns the activity with type, times, agenda, note, participants and leads. Use this when you know the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): Nutshell API ID of the activity, in the form <number>-activities. Example: 12-activities.

Example input: `{"id":"<id>"}`

### `nutshell_activity_types_list`

List Activity Types · Read-only

List activity types. Returns activity types with id and name. Use this to pick activity_type for nutshell_activity_create.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `nutshell_audiences_list`

List Audiences · Read-only

List email marketing audiences. Returns audiences with id, name and member counts. Use this to review marketing lists.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `nutshell_competitors_list`

List Competitors · Read-only

List competitors. Returns competitors with id and name. Use this to record competitors on leads.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `nutshell_contact_get`

Get Contact · Read-only

Get one contact (person) by ID. Returns the contact with contact info, owners, tags, linked accounts and leads. Use this when you know the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): Nutshell API ID of the contact, in the form <number>-contacts. Example: 3-contacts.

Example input: `{"id":"<id>"}`

### `nutshell_contacts_list`

List Contacts · Read-only

List contacts (people), optionally searched by name or email. Returns contacts with id, name, emails, phones, owners and linked accounts and leads, plus meta paging. Use this to find a person. Use nutshell_contact_get for one.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `page` (`integer`, optional): Page number, starting at 0. Example: 0.
- `page_limit` (`integer`, optional): Results per page (default 50). Example: 25.
- `q` (`string`, optional): Search text matched against contact names and emails. Example: Acme.
- `sort` (`string`, optional): Field to sort by; prefix with - for descending. Example: -modifiedTime.

Example input: `{}`

### `nutshell_events_list`

List Events · Read-only

List timeline events (changes, emails, notes, activities) across Nutshell or for one entity. Returns events with id, type, action, actor, payload and createdTime. Use this for recent activity or to sync changes.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `entity_id` (`string`, optional): Only events for this entity ID. Example: 1001-leads.
- `limit` (`integer`, optional): Maximum number of results. Example: 25.
- `max_time` (`integer`, optional): Only events before this Unix time. Example: 1767830400.
- `since_time` (`integer`, optional): Only events after this Unix time. Example: 1767225600.

Example input: `{}`

### `nutshell_industries_list`

List Industries · Read-only

List industries. Returns industries with id and name. Use this for an account's industry link.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `nutshell_invoice_get`

Get Invoice · Read-only

Get one invoice. Returns the invoice with line items, totals, status and payments. Use this when you know the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): Nutshell API ID of the invoice, in the form <number>-invoices. Example: 9-invoices.

Example input: `{"id":"<id>"}`

### `nutshell_invoices_list`

List Invoices · Read-only

List invoices. Returns invoices with id, number, status, total, due date and lead. Use nutshell_invoice_get for one.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `page` (`integer`, optional): Page number, starting at 0. Example: 0.
- `page_limit` (`integer`, optional): Results per page (default 50). Example: 25.

Example input: `{}`

### `nutshell_lead_competitors_list`

List Lead Competitors · Read-only

List competitor relationships on leads. Returns competitor maps with id, competitor, lead and status. Use this to see which competitors are on deals.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `nutshell_lead_get`

Get Lead · Read-only

Get one lead by ID. Returns the lead with status, value, stage, pipeline, products, competitors, contacts, accounts and outcome. Use this when you know the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): Nutshell API ID of the lead, in the form <number>-leads. Example: 1001-leads.

Example input: `{"id":"<id>"}`

### `nutshell_lead_products_list`

List Lead Products · Read-only

List products attached to leads (product maps) with quantity and price. Returns product maps with id, product, lead, quantity, price and amount. Use this to see what is on a deal.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `nutshell_lead_stages_list`

List Lead Stages · Read-only

List the pipeline stages a lead has been in, with time spent in each. Returns stages with id, name, position, enteredTime and duration. Use this to see a deal's progression.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): Nutshell API ID of the lead, in the form <number>-leads. Example: 1001-leads.

Example input: `{"id":"<id>"}`

### `nutshell_leads_list`

List Leads · Read-only

List leads (deals), optionally searched by name and sorted. Returns leads with id, name, status, value, stage, confidence, owners and linked contacts and accounts, plus meta paging. Use this to find deals. Use nutshell_lead_get for one lead.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `page` (`integer`, optional): Page number, starting at 0. Example: 0.
- `page_limit` (`integer`, optional): Results per page (default 50). Example: 25.
- `q` (`string`, optional): Search text matched against lead names. Example: Acme.
- `sort` (`string`, optional): Field to sort by; prefix with - for descending. Example: -createdTime.

Example input: `{}`

### `nutshell_markets_list`

List Markets · Read-only

List markets. Returns markets with id, name and currency. Use this for market IDs.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `nutshell_note_get`

Get Note · Read-only

Get one note by ID. Returns the note's body, creator and parent. Use this when you know the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): Nutshell API ID of the note, in the form <number>-notes. Example: 55-notes.

Example input: `{"id":"<id>"}`

### `nutshell_notes_list`

List Notes · Read-only

List notes. Returns notes with id, body, creator, createdTime and parent entity. Use nutshell_note_get for one note.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `page` (`integer`, optional): Page number, starting at 0. Example: 0.
- `page_limit` (`integer`, optional): Results per page (default 50). Example: 25.

Example input: `{}`

### `nutshell_outcomes_list`

List Lead Outcomes · Read-only

List lead outcomes (won, lost, cancelled reasons). Returns outcomes with id, name and status. Use this for nutshell_lead_status_update.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `nutshell_pipelines_list`

List Pipelines · Read-only

List pipelines (stagesets). Returns pipelines with id, name and stages. Use this for nutshell_lead_pipeline_set.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `nutshell_product_categories_list`

List Product Categories · Read-only

List product categories. Returns categories with id and name. Use this to group products.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `nutshell_product_get`

Get Product · Read-only

Get one product. Returns the product with price, SKU, unit and category. Use this when you know the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): Nutshell API ID of the product, in the form <number>-products. Example: 8-products.

Example input: `{"id":"<id>"}`

### `nutshell_products_list`

List Products · Read-only

List or search products and services in the catalog. Returns products with id, name, sku, price and category. Use this to find product IDs for leads.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `q` (`string`, optional): Search text matched against product names. Example: Acme.
- `sort` (`string`, optional): Field to sort by; prefix with - for descending. Example: name.

Example input: `{}`

### `nutshell_quote_get`

Get Quote · Read-only

Get one quote. Returns the quote with line items, totals, status and lead. Use this when you know the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): Nutshell API ID of the quote, in the form <number>-quotes. Example: 21-quotes.

Example input: `{"id":"<id>"}`

### `nutshell_quotes_list`

List Quotes · Read-only

List quotes. Returns quotes with id, name, status, total, lead and dates. Use nutshell_quote_get for one.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `page` (`integer`, optional): Page number, starting at 0. Example: 0.
- `page_limit` (`integer`, optional): Results per page (default 50). Example: 25.

Example input: `{}`

### `nutshell_sources_list`

List Sources · Read-only

List lead sources. Returns sources with id, name and channel. Use this for source IDs on leads.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `nutshell_stages_list`

List Stages · Read-only

List pipeline stages. Returns stages with id, name, position and pipeline. Use this to read stage names and order.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `nutshell_tags_list`

List Tags · Read-only

List tags. Returns tags with id, name, tagType and color. Use this for tag IDs.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `nutshell_task_get`

Get Task · Read-only

Get one task by ID. Returns the task with due time, assignee, related entity and recurrence. Use this when you know the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): Nutshell API ID of the task, in the form <number>-tasks. Example: 77-tasks.

Example input: `{"id":"<id>"}`

### `nutshell_tasks_list`

List Tasks · Read-only

List tasks. Returns tasks with id, title, description, dueTime, completed state, assignee and related entity. Use nutshell_task_get for one task.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `page` (`integer`, optional): Page number, starting at 0. Example: 0.
- `page_limit` (`integer`, optional): Results per page (default 50). Example: 25.

Example input: `{}`

### `nutshell_territories_list`

List Territories · Read-only

List sales territories. Returns territories with id and name. Use this for territory IDs.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `nutshell_user_get`

Get User · Read-only

Get one user. Returns the user with name, emails and teams. Use this when you know the ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): Nutshell API ID of the user, in the form <number>-users. Example: 1-users.

Example input: `{"id":"<id>"}`

### `nutshell_users_list`

List Users · Read-only

List Nutshell users. Returns users with id, name, emails, and enabled state. Use this for owner and assignee IDs.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `nutshell_account_create`

Create Account · Write

Create an account (company). Returns the created account in accounts[0]. Use this to add a company. Use nutshell_contact_create for a person.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `name` (`string`, required): Company name. Example: Acme Corp.
- `addresses` (`array`, optional): Addresses, each with address_1, city, state, postalCode, country and optional name and isPrimary. Example: [{"address_1": "100 Main St", "city": "Ann Arbor", "state": "MI", "postalCode": "48104", "country": "US"}]
- `custom_fields` (`object`, optional): Custom field values keyed by custom field name (see nutshell_accounts_list response or the custom field list in Nutshell). Example: {"Favorite Number": "12"}
- `description` (`string`, optional): Description. Example: Manufacturing customer in Michigan.
- `emails` (`array`, optional): Email addresses, each with value and optional name and isPrimary. Example: [{"value": "jane@acme.com", "name": "work", "isPrimary": true}]
- `links` (`object`, optional): Links keyed by resource type, e.g. owners, industry, accountType, tags, contacts. Example: {"owners": ["1-users"], "industry": "4-industries"}
- `phones` (`array`, optional): Phone numbers, each with value and optional name (e.g. work, mobile) and isPrimary. Example: [{"value": "555-123-4567", "name": "work", "isPrimary": true}]
- `urls` (`array`, optional): Websites, each with value. Example: [{"value": "https://acme.com"}]

Example input: `{"name":"<name>"}`

### `nutshell_account_update`

Update Account · Write

Update an account with JSON Patch operations (name, description, links, custom fields...). Returns the updated account. Use this to change fields. Use nutshell_account_create for a new company.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): Nutshell API ID of the account, in the form <number>-accounts. Example: 123-accounts.
- `operations` (`array`, required): JSON Patch operations, each with op (add, remove, replace), path and value. Paths start with /accounts/0/, e.g. /accounts/0/name, /accounts/0/links/owners, or /accounts/0/<custom field name>. Example: [{"op": "replace", "path": "/accounts/0/name", "value": "Acme Corporation"}]

Example input: `{"id":"<id>","operations":[{"op":"replace","path":"/accounts/0/name","value":"Acme Corporation"}]}`

### `nutshell_activity_create`

Create Activity · Write

Schedule or log an activity (call, meeting, etc.) with participants and leads. Returns the created activity in activities[0]. Use this to record a call or meeting. Use nutshell_note_create for a plain note.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `end_time` (`integer`, required): End as a Unix timestamp (seconds). Example: 1767261600.
- `name` (`string`, required): Activity name. Example: Call with Jane Doe.
- `start_time` (`integer`, required): Start as a Unix timestamp (seconds). Example: 1767258000.
- `activity_type` (`string`, optional): Activity type ID from nutshell_activity_types_list. Example: 1-activityTypes.
- `description` (`string`, optional): Agenda. Example: Discuss renewal terms.
- `is_all_day` (`boolean`, optional): All-day event. Example: false.
- `is_flagged` (`boolean`, optional): Mark as important. Example: false.
- `is_logged` (`boolean`, optional): true if the activity already happened. Example: false.
- `links` (`object`, optional): participants (user/contact IDs) and leads. Example: {"participants": ["1-users", "3-contacts"], "leads": ["1001-leads"]}
- `location` (`string`, optional): Location. Example: Zoom.
- `note` (`string`, optional): Internal note. Example: Jane asked about volume pricing.

Example input: `{"end_time":1767261600,"name":"<name>","start_time":1767258000}`

### `nutshell_activity_update`

Update Activity · Write

Replace the fields of an activity. Returns the updated activity. Use this to reschedule or log an activity.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `end_time` (`integer`, required): End as a Unix timestamp (seconds). Example: 1767261600.
- `id` (`string`, required): Nutshell API ID of the activity, in the form <number>-activities. Example: 12-activities.
- `name` (`string`, required): Activity name. Example: Call with Jane Doe.
- `start_time` (`integer`, required): Start as a Unix timestamp (seconds). Example: 1767258000.
- `activity_type` (`string`, optional): Activity type ID from nutshell_activity_types_list. Example: 1-activityTypes.
- `description` (`string`, optional): Agenda. Example: Discuss renewal terms.
- `is_all_day` (`boolean`, optional): All-day event. Example: false.
- `is_flagged` (`boolean`, optional): Mark as important. Example: false.
- `is_logged` (`boolean`, optional): true if the activity already happened. Example: false.
- `links` (`object`, optional): participants (user/contact IDs) and leads. Example: {"participants": ["1-users", "3-contacts"], "leads": ["1001-leads"]}
- `location` (`string`, optional): Location. Example: Zoom.
- `note` (`string`, optional): Internal note. Example: Jane asked about volume pricing.

Example input: `{"end_time":1767261600,"id":"<id>","name":"<name>","start_time":1767258000}`

### `nutshell_contact_create`

Create Contact · Write

Create a contact (person), optionally linked to accounts. Returns the created contact in contacts[0]. Use this to add a person. Use nutshell_account_create for a company.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `name` (`string`, required): Full name. Example: Jane Doe.
- `addresses` (`array`, optional): Addresses, each with address_1, city, state, postalCode, country and optional name and isPrimary. Example: [{"address_1": "100 Main St", "city": "Ann Arbor", "state": "MI", "postalCode": "48104", "country": "US"}]
- `custom_fields` (`object`, optional): Custom field values keyed by custom field name (see nutshell_contacts_list response or the custom field list in Nutshell). Example: {"Favorite Number": "12"}
- `description` (`string`, optional): Text shown under the name, e.g. job title. Example: VP of Operations.
- `emails` (`array`, optional): Email addresses, each with value and optional name and isPrimary. Example: [{"value": "jane@acme.com", "name": "work", "isPrimary": true}]
- `links` (`object`, optional): Links keyed by resource type, e.g. accounts, owners, tags. Example: {"accounts": ["337-accounts"], "owners": ["1-users"]}
- `phones` (`array`, optional): Phone numbers, each with value and optional name (e.g. work, mobile) and isPrimary. Example: [{"value": "555-123-4567", "name": "work", "isPrimary": true}]
- `urls` (`array`, optional): Websites, each with value. Example: [{"value": "https://acme.com"}]

Example input: `{"name":"<name>"}`

### `nutshell_contact_update`

Update Contact · Write

Update a contact with JSON Patch operations. Returns the updated contact. Use this to change fields.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): Nutshell API ID of the contact, in the form <number>-contacts. Example: 123-contacts.
- `operations` (`array`, required): JSON Patch operations, each with op (add, remove, replace), path and value. Paths start with /contacts/0/, e.g. /contacts/0/name, /contacts/0/links/owners, or /contacts/0/<custom field name>. Example: [{"op": "replace", "path": "/contacts/0/description", "value": "COO"}]

Example input: `{"id":"<id>","operations":[{"op":"replace","path":"/contacts/0/description","value":"COO"}]}`

### `nutshell_lead_create`

Create Lead · Write

Create a lead (deal) linked to contacts or accounts. Returns the created lead in leads[0]. Use this to open a new deal. Use nutshell_lead_status_update to win or lose it.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `description` (`string`, required): Lead name/description. Example: Acme - 50 seat expansion.
- `custom_fields` (`object`, optional): Custom field values keyed by custom field name (see nutshell_leads_list response or the custom field list in Nutshell). Example: {"Favorite Number": "12"}
- `due_time` (`object`, optional): When the lead is due, as an object with timestamp (Unix seconds). Example: {"timestamp": 1774915200}
- `links` (`object`, optional): Links: accounts and contacts (IDs), owners, sources, tags, products, stageset (pipeline). Example: {"accounts": ["337-accounts"], "contacts": ["3-contacts"], "owners": ["1-users"]}
- `manual_value` (`string`, optional): Lead value, overriding the value from products. Example: 25000.

Example input: `{"description":"<description>"}`

### `nutshell_lead_pipeline_set`

Set Lead Pipeline · Write

Move a lead to a different pipeline (stageset). Returns the updated lead. Use nutshell_pipelines_list for pipeline IDs.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `id` (`string`, required): Nutshell API ID of the lead, in the form <number>-leads. Example: 1001-leads.
- `stageset` (`string`, required): Pipeline (stageset) ID. Example: 1-stagesets.

Example input: `{"id":"<id>","stageset":"<stageset>"}`

### `nutshell_lead_reopen`

Reopen Lead · Write

Reopen a closed lead. Returns the reopened lead. Use this after nutshell_lead_status_update closed it.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `id` (`string`, required): Nutshell API ID of the lead, in the form <number>-leads. Example: 1001-leads.

Example input: `{"id":"<id>"}`

### `nutshell_lead_status_update`

Update Lead Status · Write

Close a lead by setting its outcome (won, lost or cancelled outcome ID), with optional competitor and product maps. Returns the updated lead. Use this to win or lose a deal. Use nutshell_lead_reopen to reopen it. Use nutshell_outcomes_list for outcome IDs.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `id` (`string`, required): Nutshell API ID of the lead, in the form <number>-leads. Example: 1001-leads.
- `outcome_id` (`string`, required): Outcome ID from nutshell_outcomes_list. Example: 1-outcomes.
- `competitor_maps` (`array`, optional): Competitor map IDs to attach. Example: ["1-competitorMaps"]

Example input: `{"id":"<id>","outcome_id":"<outcome_id>"}`

### `nutshell_lead_update`

Update Lead · Write

Update a lead with JSON Patch operations (description, value, links, custom fields...). Returns the updated lead. Use this to edit a lead. Use nutshell_lead_status_update to close it.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): Nutshell API ID of the lead, in the form <number>-leads. Example: 123-leads.
- `operations` (`array`, required): JSON Patch operations, each with op (add, remove, replace), path and value. Paths start with /leads/0/, e.g. /leads/0/name, /leads/0/links/owners, or /leads/0/<custom field name>. Example: [{"op": "replace", "path": "/leads/0/description", "value": "Acme - 60 seat expansion"}]

Example input: `{"id":"<id>","operations":[{"op":"replace","path":"/leads/0/description","value":"Acme - 60 seat expansion"}]}`

### `nutshell_note_create`

Create Note · Write

Add a note to a lead, contact or account. Returns the created note. Use this to record free-form context. Use nutshell_activity_create for meetings or calls.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `body` (`string`, required): Note text. Example: Sent revised proposal.
- `parent` (`string`, required): ID of the lead, contact or account to attach the note to. Example: 1001-leads.

Example input: `{"body":"<body>","parent":"<parent>"}`

### `nutshell_quote_status_update`

Update Quote Status · Write

Change a quote's status (READY, SENT, REVOKED, ACCEPTED, ARCHIVED). Returns the updated quote. Use this to mark a quote sent or accepted.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `id` (`string`, required): Nutshell API ID of the quote, in the form <number>-quotes. Example: 21-quotes.
- `status` (`string`, required): New status. Example: SENT. One of: `READY`, `SENT`, `REVOKED`, `ACCEPTED`, `ARCHIVED`.
- `accepted_email` (`string`, optional): Email recorded when accepting. Example: jane@acme.com.
- `accepted_name` (`string`, optional): Name recorded when accepting. Example: Jane Doe.

Example input: `{"id":"<id>","status":"READY"}`

### `nutshell_source_create`

Create Source · Write

Create a lead source. Returns the created source. Use this to track a new channel.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `name` (`string`, required): Source name. Example: sk-test webinar.
- `channel` (`integer`, optional): 0 none, 1 organic search, 2 paid search, 3 organic social, 4 paid social, 5 email, 6 referrer, 7 traditional, 8 direct. Example: 5.

Example input: `{"name":"<name>"}`

### `nutshell_tag_create`

Create Tag · Write

Create a tag for leads, contacts or accounts. Returns the created tag. Use this before tagging records.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `name` (`string`, required): Tag name. Example: Enterprise.
- `tag_type` (`string`, required): 1 leads, 2 contacts, 3 accounts. Example: 1. One of: `1`, `2`, `3`.
- `color_type` (`string`, optional): Color 1-14 (1 default, 3 red, 9 blue, 11 green...). Example: 9.

Example input: `{"name":"<name>","tag_type":"1"}`

### `nutshell_task_create`

Create Task · Write

Create a task, optionally assigned to a user and attached to a lead, contact or account. Returns the created task. Use this for to-dos. Use nutshell_task_update to complete it.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `title` (`string`, required): Task title. Example: Send contract.
- `assignee` (`string`, optional): User ID to assign. Example: 1-users.
- `description` (`string`, optional): Details. Example: Use the 2026 template.
- `due_time` (`string`, optional): Due time as a Unix timestamp. Example: 1767258000.
- `related_entity` (`string`, optional): Lead, contact or account ID to attach the task to. Example: 1001-leads.

Example input: `{"title":"<title>"}`

### `nutshell_task_update`

Update Task · Write

Update a task with JSON Patch operations, e.g. mark it complete or change the due time. Returns the updated task. Use this to complete or edit a task.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): Nutshell API ID of the task, in the form <number>-tasks. Example: 123-tasks.
- `operations` (`array`, required): JSON Patch operations, each with op (add, remove, replace), path and value. Paths start with /tasks/0/, e.g. /tasks/0/name, /tasks/0/links/owners, or /tasks/0/<custom field name>. Example: [{"op": "replace", "path": "/tasks/0/title", "value": "Send signed contract"}]

Example input: `{"id":"<id>","operations":[{"op":"replace","path":"/tasks/0/title","value":"Send signed contract"}]}`

### `nutshell_account_delete`

Delete Account · Destructive

Delete an account; it can be restored from the trash within 30 days. Returns an empty response on success. Use this to remove a company.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): Nutshell API ID of the account, in the form <number>-accounts. Example: 337-accounts.

Example input: `{"id":"<id>"}`

### `nutshell_contact_delete`

Delete Contact · Destructive

Delete a contact; it can be restored from the trash. Returns an empty response on success. Use this to remove a person.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): Nutshell API ID of the contact, in the form <number>-contacts. Example: 3-contacts.

Example input: `{"id":"<id>"}`

### `nutshell_lead_delete`

Delete Lead · Destructive

Delete a lead; it can be restored with undelete. Returns an empty response on success. Use this to remove a deal.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): Nutshell API ID of the lead, in the form <number>-leads. Example: 1001-leads.

Example input: `{"id":"<id>"}`

### `nutshell_note_delete`

Delete Note · Destructive

Delete a note. Returns an empty response on success. Use this to remove a note.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): Nutshell API ID of the note, in the form <number>-notes. Example: 55-notes.

Example input: `{"id":"<id>"}`

### `nutshell_product_delete`

Delete Product · Destructive

Delete a product from the catalog. Returns an empty response on success. Use this to retire a product.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): Nutshell API ID of the product, in the form <number>-products. Example: 8-products.

Example input: `{"id":"<id>"}`

### `nutshell_task_delete`

Delete Task · Destructive

Delete a task. Returns an empty response on success. Use this to remove a task.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, required): Nutshell API ID of the task, in the form <number>-tasks. Example: 77-tasks.

Example input: `{"id":"<id>"}`

## Related

Other CRM & Sales connectors ([all 174](/agentkit/connectors/?category=crm-sales)):

- [Salesforce](/agentkit/connectors/salesforce/): Scalekit connector, OAuth, 74 tools
- [HubSpot](/agentkit/connectors/hubspot/): Scalekit connector, OAuth, 457 tools
- [Close](/agentkit/connectors/close/): Scalekit connector, OAuth, 103 tools


---

## More Scalekit documentation

| Resource | What it contains | When to use it |
|----------|-----------------|----------------|
| [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content |
| [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas |
| [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |
