Nutshell REST API

{
  "openapi": "3.0.0",
  "info": {
    "title": "Nutshell API",
    "description": "The most powerful API in the world",
    "version": "2.0.0"
  },
  "servers": [
    {
      "url": "app.nutshell.com/rest"
    }
  ],
  "paths": {
    "/accounts/{id}": {
      "get": {
        "tags": [
          "Accounts (Companies)"
        ],
        "summary": "Get an account",
        "description": "Get an account by ID. Accounts are companies or organizations that you do business with, and are referred to as 'Companies' in the Nutshell UI.  <br> <br> The returned arrays creators, owners, origins, contacts, accountTypes, and industries contain additional information corresponding to the requested accounts. ",
        "operationId": "e011fe1a74d2ca75e6294040b98423f1",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "API ids are of the form 'n-accounts', where n is an integer. Ids can be listed in a comma-separated format to retrieve multiple accounts.",
            "required": true,
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "account",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/accountResponse"
                }
              }
            }
          }
        },
        "security": [
          {
            "basicAuth": []
          }
        ]
      },
      "delete": {
        "tags": [
          "Accounts (Companies)"
        ],
        "summary": "Delete an account",
        "description": "Delete an account by ID. Deleted accounts are removed from the companies tab, and can be restored from the trash within 30 days of deletion via the undelete endpoint.",
        "operationId": "2ab29d8b08add12de00c9075a1dc934f",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Ids are of the form 'n-accounts', where n is an integer.",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/accountResponse"
                }
              }
            }
          }
        },
        "security": [
          {
            "basicAuth": []
          }
        ]
      },
      "patch": {
        "tags": [
          "Accounts (Companies)"
        ],
        "summary": "Update an account",
        "description": "Update an account by id. <br><br> op is the operation to be performed, and path specifies what resource to patch. <br><br> Use the path accounts/0/fieldName to update fields that are user-entered for this resource, i.e. name, description, etc. <br> <br> Use the path accounts/0/links/fieldName to update this account's links to other resources within Nutshell, i.e. contacts, owner, territory, etc. When performing an 'add', include a /- at the end of the path, i.e. accounts/0/links/fieldName/- .  <br><br> When using the remove operation, include the id at the end of the path (i.e. accounts/0/links/contacts/1-contacts) - no need to include a value. <br><br> Value can alternatively be a list of objects, which can be used with the replace operation and the path accounts/0/urls, accounts/0/addresses, accounts/0/phones, or accounts/0/phones to replace the existing list with a list of new objects. Visit <a href='https://developers.nutshell.com/reference/get_accounts-id'>the account docs</a> for more detail on the structure of these objects.",
        "operationId": "48bf7b1de74805c35713fb7b3a9f1e52",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Ids are of the form 'n-accounts', where n is an integer.",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json-patch+json": {
              "schema": {
                "$ref": "#/components/schemas/patchInput"
              }
            }
          }
        },
        "responses": {
          "204": {
            "description": "No Content"
          }
        },
        "security": [
          {
            "basicAuth": []
          }
        ]
      }
    },
    "/accounts/{id}/customfields": {
      "get": {
        "tags": [
          "Accounts (Companies)"
        ],
        "summary": "Get custom fields",
        "description": "Get a list of custom field values for an account by ID. Custom fields are user-defined fields that can be added to accounts.",
        "operationId": "31ef0f539b00b82d394f351491b80103",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Ids are of the form 'n-accounts', where n is an integer.",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "customFields": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/FullCustomField"
                      }
                    }
                  },
                  "type": "object"
                }
              }
            }
          }
        },
        "security": [
          {
            "basicAuth": []
          }
        ]
      }
    },
    "/accounts/customfields/attributes": {
      "get": {
        "tags": [
          "Accounts (Companies)"
        ],
        "summary": "Get a list of custom fields",
        "description": "Get a list of all account custom fields in your Nutshell instance. Custom fields are user-defined fields that can be added to accounts.",
        "operationId": "09c7340848e47c8b7727d7e316702d3d",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "customFields": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/CustomField"
                      }
                    }
                  },
                  "type": "object"
                }
              }
            }
          }
        },
        "security": [
          {
            "basicAuth": []
          }
        ]
      }
    },
    "/accounts/customfield": {
      "post": {
        "tags": [
          "Accounts (Companies)"
        ],
        "summary": "Create a custom field",
        "description": "Creates a custom field to use for accounts.",
        "operationId": "aa09106535968abeb7ea879a5774eec7",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CustomFieldCreateInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "security": [
          {
            "basicAuth": []
          }
        ]
      }
    },
    "/accounts/list": {
      "get": {
        "tags": [
          "Accounts (Companies)"
        ],
        "summary": "Get list items for all accounts",
        "description": "Get a list of all accounts and associated data in your Nutshell Instance, in a list item format. List items have additional fields attached to them for filtering purposes.",
        "operationId": "fea99eec1a11b79a75fd3c6092ea1c95",
        "parameters": [
          {
            "name": "filter",
            "in": "query",
            "required": false,
            "style": "deepObject",
            "explode": true,
            "schema": {
              "description": "Filter the returned accounts based on various criteria. Use /rest/accounts/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": "array",
              "items": {
                "type": "string",
                "enum": [
                  "-accountType",
                  "-createdTime",
                  "-industry",
                  "-lastContactedTime",
                  "-name",
                  "-numberOfContacts",
                  "-owner",
                  "-phone",
                  "-postalCode",
                  "-territory",
                  "accountType",
                  "createdTime",
                  "industry",
                  "lastContactedTime",
                  "name",
                  "numberOfContacts",
                  "owner",
                  "phone",
                  "postalCode",
                  "territory"
                ]
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "accounts list",
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "meta": {
                      "allOf": [
                        {
                          "properties": {
                            "count": {
                              "description": "The number of returned accounts",
                              "type": "integer",
                              "format": "int32"
                            }
                          },
                          "type": "object"
                        },
                        {
                          "properties": {
                            "total": {
                              "description": "The total number of accounts in your Nutshell instance",
                              "type": "integer",
                              "format": "int32"
                            }
                          },
                          "type": "object"
                        },
                        {
                          "properties": {
                            "facets": {
                              "description": "Contains an AccountType object, which lists the id and count for each account type in your instance",
                              "properties": {
                                "AccountType": {
                                  "properties": {
                                    "n-accountTypes": {
                                      "description": "The number of accounts with the account type id n-accountTypes, where n is an integer",
                                      "type": "integer",
                                      "format": "int32"
                                    }
                                  },
                                  "type": "object"
                                }
                              },
                              "type": "object"
                            }
                          },
                          "type": "object"
                        },
                        {
                          "$ref": "#/components/schemas/meta"
                        }
                      ]
                    },
                    "listItems": {
                      "type": "array",
                      "items": {
                        "allOf": [
                          {
                            "$ref": "#/components/schemas/ListItemAccount"
                          },
                          {
                            "$ref": "#/components/schemas/HtmlLinkable"
                          },
                          {
                            "$ref": "#/components/schemas/Avatarable"
                          }
                        ]
                      }
                    }
                  },
                  "type": "object"
                }
              }
            }
          }
        },
        "security": [
          {
            "basicAuth": []
          }
        ]
      }
    },
    "/accounts": {
      "get": {
        "tags": [
          "Accounts (Companies)"
        ],
        "summary": "Get a list of accounts",
        "description": "Get all accounts and associated data in your Nutshell instance. Accounts are companies or organizations that you do business with, and are referred to as 'Companies' in the Nutshell UI.",
        "operationId": "ee7a9535ab7ae30da91d6d9cebe2ed85",
        "parameters": [
          {
            "name": "email",
            "in": "query",
            "description": "query for accounts associated with a specific email address",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "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": "filter",
            "in": "query",
            "required": false,
            "style": "deepObject",
            "explode": true,
            "schema": {
              "description": "Filter the returned accounts based on various criteria. Use /rest/accounts/list/fields to get a full list of valid filter keys.",
              "type": "object",
              "additionalProperties": {
                "$ref": "#/components/schemas/FilterInput"
              }
            }
          },
          {
            "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": "array",
              "items": {
                "type": "string",
                "enum": [
                  "-accountType",
                  "-createdTime",
                  "-industry",
                  "-lastContactedTime",
                  "-name",
                  "-numberOfContacts",
                  "-owner",
                  "-phone",
                  "-postalCode",
                  "-territory",
                  "accountType",
                  "createdTime",
                  "industry",
                  "lastContactedTime",
                  "name",
                  "numberOfContacts",
                  "owner",
                  "phone",
                  "postalCode",
                  "territory"
                ]
              }
            }
          },
          {
            "name": "page[limit]",
            "in": "query",
            "description": "Limit the number of results returned, for pagination.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page[page]",
            "in": "query",
            "description": "Request a specific page of results, for pagination. Used in conjunction with the page[limit] parameter. Indexing is 0-based.",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "accounts",
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "meta": {
                      "allOf": [
                        {
                          "properties": {
                            "count": {
                              "description": "The number of returned accounts",
                              "type": "integer",
                              "format": "int32"
                            }
                          },
                          "type": "object"
                        },
                        {
                          "properties": {
                            "total": {
                              "description": "The total number of accounts in your Nutshell instance",
                              "type": "integer",
                              "format": "int32"
                            }
                          },
                          "type": "object"
                        },
                        {
                          "properties": {
                            "facets": {
                              "description": "Contains an AccountType object, which lists the id and count for each account type in your instance",
                              "properties": {
                                "AccountType": {
                                  "properties": {
                                    "n-accountTypes": {
                                      "description": "The number of accounts with the account type id n-accountTypes, where n is an integer",
                                      "type": "integer",
                                      "format": "int32"
                                    }
                                  },
                                  "type": "object"
                                }
                              },
                              "type": "object"
                            }
                          },
                          "type": "object"
                        },
                        {
                          "$ref": "#/components/schemas/meta"
                        }
                      ]
                    },
                    "accounts": {
                      "description": "An array of returned accounts.",
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Account"
                      }
                    }
                  },
                  "type": "object"
                }
              }
            }
          }
        },
        "security": [
          {
            "basicAuth": []
          }
        ]
      },
      "post": {
        "tags": [
          "Accounts (Companies)"
        ],
        "summary": "Create an account",
        "description": "Create a new account. Accounts are companies or organizations that you do business with, and are referred to as 'Companies' in the Nutshell UI.",
        "operationId": "0e0199fef8e93c05437d3a33104886d1",
        "requestBody": {
          "description": "At least one of the following fields is required: name, phone, email, address, or url. All other fields are optional.",
          "required": true,
          "content": {
            "json": {
              "schema": {
                "properties": {
                  "accounts": {
                    "type": "array",
                    "items": {
                      "properties": {
                        "name": {
                          "type": "string"
                        },
                        "description": {
                          "type": "string"
                        },
                        "phones": {
                          "type": "array",
                          "items": {
                            "properties": {
                              "isPrimary": {
                                "type": "boolean"
                              },
                              "name": {
                                "type": "string"
                              },
                              "value": {
                                "type": "string",
                                "example": "123-456-7890"
                              }
                            },
                            "type": "object"
                          }
                        },
                        "emails": {
                          "type": "array",
                          "items": {
                            "properties": {
                              "value": {
                                "type": "string",
                                "example": "support@nutshell.com"
                              }
                            },
                            "type": "object"
                          }
                        },
                        "urls": {
                          "type": "array",
                          "items": {
                            "properties": {
                              "value": {
                                "type": "string",
                                "example": "http://www.nutshell.com"
                              }
                            },
                            "type": "object"
                          }
                        },
                        "addresses": {
                          "type": "array",
                          "items": {
                            "properties": {
                              "name": {
                                "type": "string"
                              },
                              "isPrimary": {
                                "type": "boolean"
                              },
                              "value": {
                                "properties": {
                                  "address_1": {
                                    "description": "Street address",
                                    "type": "string",
                                    "example": "123 Main St"
                                  },
                                  "city": {
                                    "type": "string",
                                    "example": "Ann Arbor"
                                  },
                                  "state": {
                                    "type": "string",
                                    "example": "MI"
                                  }
                                },
                                "type": "object"
                              }
                            },
                            "type": "object"
                          }
                        },
                        "links": {
                          "description": "Links to other resources within Nutshell. Key is the type of resource being linked, value is the id of that resource.",
                          "type": "object"
                        },
                        "customFields": {
                          "description": "Custom fields to add to the Account.",
                          "type": "object",
                          "example": {
                            "Favorite Number": "12"
                          },
                          "additionalProperties": {
                            "$ref": "#/components/schemas/CustomFieldInput"
                          }
                        }
                      },
                      "type": "object"
                    }
                  }
                },
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Account"
                }
              }
            }
          }
        },
        "security": [
          {
            "basicAuth": []
          }
        ]
      }
    },
    "/accounts/{id}/undelete": {
      "post": {
        "tags": [
          "Accounts (Companies)"
        ],
        "summary": "Undelete an account",
        "description": "Undelete an account by id.",
        "operationId": "23c63a8f80517c993fb93e50e216167b",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Ids are of the form 'n-accounts', where n is an integer.",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Account"
                }
              }
            }
          }
        },
        "security": [
          {
            "basicAuth": []
          }
        ]
      }
    },
    "/accounts/list/fields": {
      "get": {
        "tags": [
          "Accounts (Companies)"
        ],
        "summary": "Get the fields for an account",
        "description": "Get the list of fields that can possibly be associated with accounts, along with whether they are valid for filtering sorting.",
        "operationId": "4eb956de07606de9ea86f6b39feeff20",
        "responses": {
          "200": {
            "description": "Account fields",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FieldsResponse"
                }
              }
            }
          }
        },
        "security": [
          {
            "basicAuth": []
          }
        ]
      }
    },
    "/accounttypes": {
      "get": {
        "tags": [
          "Accounts (Companies)"
        ],
        "summary": "Get a list of account types",
        "description": "Get a list of all account types in a Nutshell instance.",
        "operationId": "73f17127f4378721e7a57e7a7890b1b3",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/AccountType"
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "basicAuth": []
          }
        ]
      }
    },
    "/activities": {
      "get": {
        "tags": [
          "Activities"
        ],
        "summary": "Get activities",
        "operationId": "afbafbf6832a5c50439963afb493230f",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "description": "String search",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "How many activities to return",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "filter[participant][]",
            "in": "query",
            "description": "Which participant to get activities related to",
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          {
            "name": "filter[status][]",
            "in": "query",
            "description": "Which activities to get based on status",
            "schema": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "scheduled",
                  "logged",
                  "cancelled"
                ]
              }
            }
          },
          {
            "name": "filter[leadPriority][]",
            "in": "query",
            "description": "Whether to only return activities related to hot leads",
            "schema": {
              "type": "string",
              "enum": [
                "hot"
              ]
            }
          },
          {
            "name": "filter[activityType]",
            "in": "query",
            "description": "Which types of activities to get",
            "schema": {
              "type": "array",
              "items": {
                "type": "integer"
              }
            }
          },
          {
            "name": "filter[flagged]",
            "in": "query",
            "description": "Only return flagged activities",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "filter[isImportant]",
            "in": "query",
            "description": "Only return activities marked as important",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "filter[dateMin]",
            "in": "query",
            "description": "The earliest activity to return",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "filter[dateMax]",
            "in": "query",
            "description": "The latest activity to return",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Activity",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ActivityResponse"
                }
              }
            }
          }
        },
        "security": [
          {
            "basicAuth": []
          }
        ]
      },
      "post": {
        "tags": [
          "Activities"
        ],
        "summary": "Create an activity",
        "operationId": "245ac4db7d1ce9919113871e1fd9d14c",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/activityPostInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ActivityResponse"
                }
              }
            }
          }
        },
        "security": [
          {
            "basicAuth": []
          }
        ]
      }
    },
    "/activities/{id}": {
      "get": {
        "tags": [
          "Activities"
        ],
        "summary": "Get an activity",
        "operationId": "386cd1704288a91f21d7ea531d7cdcf6",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Activity ID of the format {integer}-activities",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Activity",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ActivityResponse"
                }
              }
            }
          }
        },
        "security": [
          {
            "basicAuth": []
          }
        ]
      },
      "put": {
        "tags": [
          "Activities"
        ],
        "summary": "Update an activity",
        "operationId": "cc696feb60257dd8d550082b06513c14",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Activity ID of the format {integer}-activities",
            "required": true,
            "schema": {
              "type": "string"
       

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