Nutshell Leads API

openapi: 3.2.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:
      - 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:
      - 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:
      - 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:
      - 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:
    createdTime:
      description: When the lead was created.
      properties:
        absoluteLocalizedString:
          description: The value formatted as a string
          type: string
          example: May 28, 2024
        timestamp:
          type: number
          example: '1234567890'
        value:
          description: The value to be formatted
          type: string
          example: May 28, 2024
      type: object
    Stage:
      properties:
        id:
          description: The API ID of this entity, formatted {integer}-{entityType}
          type: string
          example: 3-contacts
        name:
          description: The name of the stage
          type: string
          example: Prospecting
        description:
          description: The purpose of the stage
          type: string
          example: Identify and qualify potential customers
        position:
          description: The order in which this stage appears in the pipeline
          type: integer
          example: 1
        activeAvatarUrl:
          type: string
        completeAvatarUrl:
          type: string
        incompleteAvatarUrl:
          type: string
        overdueAvatarUrl:
          type: string
        numSteps:
          description: The number of steps in this stage to move on to the next stage
          type: number
          example: 3
        canAdvanceStage:
          description: Can we advance the lead to this stage?
          type: boolean
          example: true
        links:
          description: A list of related entity IDs
          type: array
          items:
            properties:
              stageset:
                type: string
                example: 1-stagesets
            type: object
      type: object
    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: true
                isBoardable:
                  description: Whether the property can be displayed on lead cards/boards
                  type: boolean
                  example: true
                isRequireable:
                  description: Whether the property can be marked as required in forms
                  type: boolean
                  example: false
                isAndable:
                  description: Whether multiple filter values can be combine

# --- truncated at 32 KB (46 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/nutshell/refs/heads/main/openapi/nutshell-leads-api-openapi.yml