Nutshell Leads API
Sales opportunities: create, read, update, close, reopen, watch, stage and stageset assignment, installments, reports and lead custom fields. 25 operation(s) across 19 path(s).
OpenAPI Specification
openapi: 3.0.0
info:
title: Nutshell Leads API
description: The most powerful API in the world
version: 2.0.0
contact:
name: Nutshell Developers
url: https://developers.nutshell.com
servers:
- url: https://app.nutshell.com/rest
description: Nutshell REST API
tags:
- name: Leads
paths:
/competitormaps/{id}:
get:
tags:
- Competitors
- Leads
summary: Get a lead-competitor relationship
operationId: b1d85dde464bf9f894809bdafc72560e
parameters:
- name: id
in: path
description: The ID of the lead-competitor relationship
required: true
schema:
type: string
responses:
'200':
description: A list of lead-competitor relationships
content:
application/json:
schema:
$ref: '#/components/schemas/LeadCompetitorMapResponse'
security:
- basicAuth: []
delete:
tags:
- Competitors
- Leads
summary: Delete a lead-competitor relationship
operationId: 851afdd2aef2a992349827409b2e6771
parameters:
- name: id
in: path
description: The ID of the lead-competitor relationship
required: true
schema:
type: string
responses:
'204':
description: No Content
security:
- basicAuth: []
patch:
tags:
- Competitors
- Leads
summary: Update a lead-competitor relationship
operationId: ba720a5972ac5167437e05f71e3592d0
parameters:
- name: id
in: path
description: The ID of the lead-competitor relationship
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/patchInput'
responses:
'204':
description: No Content
security:
- basicAuth: []
/competitormaps:
get:
tags:
- Competitors
- Leads
summary: Get a list of lead-competitor relationships
operationId: e1accd46a9067a71fe5617536bda2103
responses:
'200':
description: A list of lead-competitor relationships
content:
application/json:
schema:
$ref: '#/components/schemas/LeadCompetitorMapResponse'
security:
- basicAuth: []
/leads/{id}/customfields:
get:
tags:
- Leads
summary: Get a lead's custom fields
description: Get a list of custom fields that are applied to a lead.
operationId: 83433994d9721607dea58b99daf963ee
parameters:
- name: id
in: path
description: Lead ID
required: true
schema:
type: string
responses:
'200':
description: Custom Fields
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/FullCustomField'
security:
- basicAuth: []
/leads/customfields/attributes:
get:
tags:
- Leads
summary: Get applicable custom fields for leads
description: Get a list of custom fields that can be applied to leads.
operationId: 653f973376f3b7ecfdf95585605ddc40
responses:
'200':
description: Custom Fields
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/CustomField'
security:
- basicAuth: []
/leads/customfield:
post:
tags:
- Leads
summary: Create a custom field
description: Creates a custom field to use for leads.
operationId: 91e474dc9fbb7fc3414b76130994d575
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CustomFieldCreateInput'
responses:
'200':
description: OK
security:
- basicAuth: []
/leads/{id}:
get:
tags:
- Leads
summary: Get a lead
description: Get a single lead by the ID provided.
operationId: 8e55836889bb7d432d5fe3d9bfe608b7
parameters:
- name: id
in: path
description: Lead ID
required: true
schema:
type: string
responses:
'200':
description: Lead
content:
application/json:
schema:
$ref: '#/components/schemas/FullLead'
security:
- basicAuth: []
delete:
tags:
- Leads
summary: Delete a lead.
description: Delete a lead by the ID provided. Can be restored with the undelete endpoint.
operationId: 2ac175944b197a9c18dd9f6e9a53cb88
parameters:
- name: id
in: path
description: Lead ID
required: true
schema:
type: string
responses:
'200':
description: Lead
content:
application/json:
schema:
$ref: '#/components/schemas/FullLead'
security:
- basicAuth: []
patch:
tags:
- Leads
summary: Update a lead
description: Update a lead by id. <br><br> op is the operation to be performed, and path specifies
what resource to patch. <br><br> Use the path leads/0/fieldName to update fields that are user-entered
for this resource, i.e. name, description, etc. <br> <br> Use the path leads/0/links/fieldName
to update this lead's links to other resources within Nutshell, i.e. contacts, owner, tags, etc.
When performing an 'add', include a /- at the end of the path, i.e. leads/0/links/fieldName/-
. <br><br> When using the remove operation, include the id at the end of the path (i.e. leads/0/links/contacts/1-contacts)
- no need to include a value. <br><br> To update the value of the lead with a replace operation,
use the path leads/0/manualValue with a value of the amount as a string, or leads/0/valueToProductMode
without a value to set the lead's value back to the sum of products.
operationId: 5a47a634e21ffbad6a5c268af67a63ae
parameters:
- name: id
in: path
description: Lead ID
required: true
schema:
type: string
requestBody:
required: true
content:
application/json-patch+json:
schema:
$ref: '#/components/schemas/patchInput'
responses:
'204':
description: No Content
'400':
description: No patches sent
security:
- basicAuth: []
/leads/list:
get:
tags:
- Leads
summary: Get list items for all leads
description: Get a list of all leads and associated data in your Nutshell Instance, in a list item
format. List items have additional fields attached to them for filtering purposes.
operationId: 3b3fb3c15cb2f6f9bd67ecae3cb0baa9
parameters:
- name: filter
in: query
required: false
style: deepObject
explode: true
schema:
description: Filter the returned leads based on various criteria. Use /rest/leads/list/fields
to get a full list of valid filter keys.
type: object
additionalProperties:
$ref: '#/components/schemas/FilterInput'
- name: q
in: query
description: Used to search all related info on an entity. Returns all entities that are similar
to the query term.
required: false
schema:
type: string
- name: sort
in: query
description: Sort the returned list by a chosen field. Use a '-' before the field name to sort
in descending order.
required: false
schema:
type: string
enum:
- -age
- -value
- -milestone
- -confidence
- -name
- -closedTime
- -owner
- -sources
- age
- value
- milestone
- confidence
- name
- closedTime
- owner
- sources
responses:
'200':
description: Leads list
content:
application/json:
schema:
properties:
meta:
allOf:
- properties:
count:
description: The number of returned leads
type: integer
format: int32
type: object
- properties:
total:
description: The total number of leads in your Nutshell instance
type: integer
format: int32
type: object
- $ref: '#/components/schemas/meta'
listItems:
type: array
items:
allOf:
- $ref: '#/components/schemas/ListItemLead'
- $ref: '#/components/schemas/HtmlLinkable'
- $ref: '#/components/schemas/Avatarable'
type: object
security:
- basicAuth: []
/leads:
get:
tags:
- Leads
summary: Get a list of leads
description: Get a list of all leads and associated data in your Nutshell Instance.
operationId: 132e65861bebcb3781c3d37e66aff309
parameters:
- name: q
in: query
description: Used to search all related info on an entity. Returns all entities that are similar
to the query term.
required: false
schema:
type: string
- name: sort
in: query
description: Sort the returned list by a chosen field. Use a '-' before the field name to sort
in descending order.
required: false
schema:
type: string
enum:
- -age
- -value
- -milestone
- -confidence
- -name
- -closedTime
- -owner
- -sources
- age
- value
- milestone
- confidence
- name
- closedTime
- owner
- sources
- name: filter
in: query
required: false
style: deepObject
explode: true
schema:
description: Filter the returned leads based on various criteria. Use /rest/leads/list/fields
to get a full list of valid filter keys.
type: object
additionalProperties:
$ref: '#/components/schemas/FilterInput'
- name: page[page]
in: query
description: The page of results to return. Indexing is 0-based.
required: false
schema:
type: integer
- name: page[limit]
in: query
description: How many results to return per page
required: false
schema:
type: integer
responses:
'200':
description: Leads
content:
application/json:
schema:
$ref: '#/components/schemas/LeadResponse'
security:
- basicAuth: []
post:
tags:
- Leads
summary: Create a lead
description: Create a new lead. Only one lead can be created at a time.
operationId: 7d9961f8fbd457ba5670721926517135
requestBody:
required: true
content:
application/json:
schema:
properties:
leads:
type: array
items:
properties:
description:
description: Description of the lead, which is also set as the name of the lead
type: string
example: Car Wash Inc.
manualValue:
description: Value of the lead, will override the value calculated from the products
type: string
example: '999.99'
dueTime:
$ref: '#/components/schemas/dueTime'
customFields:
description: Custom fields to add to the Lead.
type: object
example:
Favorite Number: '12'
additionalProperties:
$ref: '#/components/schemas/CustomFieldInput'
links:
properties:
accounts:
description: This can either be the IDs of the accounts the lead should be
associated with, or an account object
type: array
items:
type: string
example: 1-accounts
contacts:
description: This can either be the IDs of the contacts the lead should be
associated with, or a contact object
type: array
items:
type: string
example: 1-contacts
owner:
description: The ID of the user the lead is assigned to
type: string
example: 1-users
sources:
description: The IDs of the sources the lead should be associated with
type: array
items:
type: string
example: 1-sources
tags:
description: The tags to attach to the lead
type: array
items:
type: string
example: 1-tags
productMaps:
description: The products to attach to the lead. You need to specify a product
ID and under links to map the product to the lead. When specifying the price,
quantity, or other root level productMap properties, you need to specify
the type and productType as well
type: array
items:
$ref: '#/components/schemas/LeadProductMap'
competitorMaps:
type: array
items:
type: string
type: object
type: object
type: object
responses:
'201':
description: Lead
content:
application/json:
schema:
$ref: '#/components/schemas/FullLead'
security:
- basicAuth: []
/leads/report:
get:
tags:
- Leads
summary: Get reports for a lead
operationId: c7d33a5a9825ea23ef5a75587cc4a9bd
parameters:
- name: filter[name]
in: query
description: Filter results by lead name. Visit the filters guide for more information on how
to filter by other terms.
required: false
schema:
type: string
- name: q
in: query
description: Used to search all related info. Returns all reports that are similar to the query
term.
required: false
schema:
type: string
- name: sort
in: query
description: Sort the returned list by a chosen field. Use a '-' before the field name to sort
in descending order.
required: false
schema:
type: string
- name: format
in: query
required: false
schema:
type: string
enum:
- json
- csv
- pdf
- png
- html
- name: gap
in: query
description: The bucket size of the report
required: false
schema:
type: string
enum:
- d
- w
- m
- y
- q
- name: groupByField
in: query
description: The field to group leads by. Sales or losses reports should use closedTime, newleads
and custom reports should use createdTime.
required: false
schema:
type: string
- name: pivotFacet
in: query
description: The facet to sort values on.
required: false
schema:
type: string
- name: reportType
in: query
description: The type of report to generate.
required: false
schema:
type: string
enum:
- sales
- losses
- newleads
- forecast
- attribution
- custom
- name: segmentByField
in: query
description: 'Ways to break down the report further to compare across different variables. Useful
to answer questions such as: Who has made the most sales? Which products are earning the most?
Where are our leads coming from?'
required: false
schema:
type: string
enum:
- outcomes
- competitors
- products
- productCategories
- assignees
- territories
- sources
- tags
- channels
- name: useConfidence
in: query
description: When calculating lead values, use their weight confidence value or not
required: false
schema:
type: boolean
responses:
'200':
description: Reports
content:
application/json:
schema:
properties:
reports:
type: array
items:
properties:
report:
$ref: '#/components/schemas/NutReportOnDemandReport'
type: object
type: object
'400':
description: Invalid input
security:
- basicAuth: []
/leads/{id}/installments:
get:
tags:
- Leads
summary: Get installments for a lead
description: Returns the installment schedule for a lead. Requires lead installments on the account
plan.
operationId: 7c4277bf7ac3a1e50fb98c713565bc36
parameters:
- name: id
in: path
description: Lead ID
required: true
schema:
type: string
responses:
'200':
description: Installments
content:
application/json:
schema:
required:
- installments
properties:
installments:
type: array
items:
$ref: '#/components/schemas/LeadInstallment'
type: object
security:
- basicAuth: []
post:
tags:
- Leads
summary: Update installments for a lead
description: Replaces the lead's installment schedule. The request body is a JSON array of installment
objects (`id`, `dueTime`, `description`, `value`, `isFailed`). `dueTime` is an ISO 8601 string.
Requires lead installments on the account plan.
operationId: 32aed6101ab1c412a24275e076aaba1f
parameters:
- name: id
in: path
description: Lead ID
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: array
items:
required:
- dueTime
- value
- isFailed
properties:
id:
type: string
example: 1-installments
dueTime:
type: string
example: 2026-01-01T00:00:00+0000
description:
type: string
example: Q1 payment
value:
type: string
example: '1000'
isFailed:
type: boolean
example: false
type: object
responses:
'200':
description: Updated installments
content:
application/json:
schema:
required:
- installments
properties:
installments:
type: array
items:
$ref: '#/components/schemas/LeadInstallment'
type: object
security:
- basicAuth: []
/leads/{id}/stages:
get:
tags:
- Leads
summary: Get all stages associated with lead
description: Get all stages associated with a lead by the ID provided, including information like
amount of time spent in each stage.
operationId: 3cc07d39be52c9a287e147e138f88446
parameters:
- name: id
in: path
description: Lead ID
required: true
schema:
type: string
responses:
'200':
description: Stages
content:
application/json:
schema:
properties:
meta:
type: object
allOf:
- $ref: '#/components/schemas/meta'
- properties:
timeSpent:
description: Array of time spent in each stage
type: array
items:
properties:
formatted:
description: Formatted value
type: string
prefix:
description: Prefix to add to value
type: string
suffix:
description: Suffix to add to value
type: string
value:
description: Actual value
type: number
unit:
description: Unit of time
type: string
type: object
stageset:
$ref: '#/components/schemas/Stageset'
type: object
stages:
type: array
items:
$ref: '#/components/schemas/Stage'
type: object
security:
- basicAuth: []
/leads/{id}/reopen:
post:
tags:
- Leads
summary: Reopen a lead
description: Reopen a lead that was previously closed.
operationId: 104d97bbcf04ea8a2ac72428fbdaa10b
parameters:
- name: id
in: path
description: Lead ID
required: true
schema:
type: string
responses:
'200':
description: Lead
content:
application/json:
schema:
$ref: '#/components/schemas/FullLead'
security:
- basicAuth: []
/leads/{id}/status:
post:
tags:
- Leads
summary: Update the status of a lead.
description: Update the status of a lead, for example, close a lead as won or lost. Also allows
for setting the outcome of the lead, and competitor and product maps.
operationId: 74bb9b0e446b6a0a9913e5b8f8bca628
parameters:
- name: id
in: path
description: ID of the lead to update the status of
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
properties:
outcomeId:
description: ID of the outcome to set for the lead
type: string
example: 1-outcomes
competitorMaps:
description: Array of competitor maps ids
type: array
items:
type: string
example: 1-competitorMaps
productMaps:
description: Array of product maps. You need to specify a product ID and under links
to map the product to the lead. When specifying the price, quantity, or other root
level productMap properties, you need to specify the type and productType as well
type: array
items:
$ref: '#/components/schemas/LeadProductMap'
type: object
responses:
'200':
description: Lead
content:
application/json:
schema:
$ref: '#/components/schemas/FullLead'
security:
- basicAuth: []
/leads/{id}/stageset:
post:
tags:
- Leads
summary: Set the pipeline for a lead
description: Pipelines are also known as stagesets.
operationId: ac69339d38f3809791db2340e47bff9b
parameters:
- name: id
in: path
description: Lead ID
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
properties:
stageset:
description: ID of the stageset to set
type: string
example: 1-stagesets
type: object
responses:
'200':
description: Lead
content:
application/json:
schema:
$ref: '#/components/schemas/FullLead'
security:
- basicAuth: []
/leads/{id}/watch:
post:
tags:
- Leads
summary: Watch a lead
description: Watch/unwatch a lead to receive (or stop receiving) notifications about it. The user
this change is made for is the authenticated user when making the api call.
operationId: cb65d8c1aa9bba020e669ab84d846887
parameters:
- name: id
in: path
description: Lead ID
required: true
schema:
type: string
responses:
'200':
description: Lead
content:
application/json:
schema:
$ref: '#/components/schemas/FullLead'
security:
- basicAuth: []
/leads/{id}/undelete:
post:
tags:
- Leads
summary: Undelete a lead
operationId: 3e509411f0439f11ffa52e726354b3b9
parameters:
- name: id
in: path
description: Lead ID
required: true
schema:
type: string
responses:
'200':
description: Lead
content:
application/json:
schema:
$ref: '#/components/schemas/FullLead'
security:
- basicAuth: []
/leads/list/fields:
get:
tags:
- Leads
summary: Get the fields for a lead
description: Get the list of fields that can possibly be associated with leads, along with whether
they are valid for filtering sorting.
operationId: 1ef7499bb48d0b6d9aedccfeb6053b95
responses:
'200':
description: Lead fields
content:
application/json:
schema:
$ref: '#/components/schemas/FieldsResponse'
security:
- basicAuth: []
/outcomes/{id}:
get:
tags:
- Leads
summary: Get a lead outcome by ID
operationId: a02ff2477ba693ce337ed58c2f7cb2d4
parameters:
- name: id
in: path
description: The ID of the lead outcome
required: true
schema:
type: string
responses:
'200':
description: A single lead outcome
content:
application/json:
schema:
$ref: '#/components/schemas/LeadOutcome'
security:
- basicAuth: []
/outcomes:
get:
tags:
- Leads
summary: Get a list of lead outcomes
operationId: 023ebfb59f2c7fe37eb81dc618d24af0
responses:
'200':
description: A list of lead outcomes
content:
application/json:
schema:
$ref: '#/components/schemas/LeadOutcome'
security:
- basicAuth: []
components:
schemas:
Avatarable:
properties:
avatarUrl:
description: The URL of the entity's avatar image.
type: string
example: https://app.nutshell.com/avatars/contacts/1006/{path}
initials:
description: The initials of the entity, used as a fallback for the avatar image.
type: string
example: AF
type: object
Competitor:
properties:
id:
description: The API ID of this entity, formatted {integer}-{entityType}
type: string
example: 3-contacts
type: object
CustomField:
properties:
id:
description: The API ID of this entity, formatted {integer}-{entityType}
type: string
example: 3-contacts
type: object
CustomFieldCreateInput:
properties:
name:
description: The name of the custom fields
type:
description: Email, location, phone, and URL are only applicable to leads.
choices:
description: For enums only. The possible values for the custom field.
isMultiple:
description: For enums only. Whether the custom field can have multiple values
id:
description: The API ID of this entity, formatted {integer}-{entityType}
type: string
example: 3-contacts
title:
type: string
example: Custom Field Title
type: object
CustomFieldInput:
description: The key-value pair for the custom field.
properties:
id:
description: The API ID of this entity, formatted {integer}-{entityType}
type: string
example: 3-contacts
type: string
FieldsResponse:
description: Response object for entity fields endpoint
properties:
properties:
properties:
exampleProperty:
properties:
type:
description: The type of the property
type: string
example: string
title:
description: The display title of the property
type: string
example: Example Property
description:
description: The description of the property
type: string
example: This is an example property
isFilterable:
description: Whether the property can be used in filters
type: boolean
example: true
isDisplayable:
description: Whether the property can be displayed
type: boolean
example: true
isSortable:
description: Whether the property can be used for sorting
type: boolean
example: true
isGoalable:
description: Whether the property can be used as a condition in automation goals
type: boolean
example: false
isAddable:
description: Whether the property can be set when creating or editing a lead
type: boolean
example:
# --- truncated at 32 KB (47 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/nutshell/refs/heads/main/openapi/nutshell-leads-api-openapi.yml