{
"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.
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.
op is the operation to be performed, and path specifies what resource to patch.
Use the path accounts/0/fieldName to update fields that are user-entered for this resource, i.e. name, description, etc.
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/- .
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.
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 the account docs 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"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/activityPostInput"
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ActivityResponse"
}
}
}
}
},
"security": [
{
"basicAuth": []
}
]
}
},
"/activitytypes": {
"get": {
"tags": [
"Activities"
],
"summary": "Get activity types",
"operationId": "e09bcf63999a97ba02d8f461039bbba2",
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ActivityTypeResponse"
}
}
}
}
},
"security": [
{
"basicAuth": []
}
]
}
},
"/audiences": {
"get": {
"tags": [
"Audiences"
],
"summary": "Get a list of audiences",
"description": "Returns a list of all email marketing audiences in a Nutshell instance.",
"operationId": "0e172d1fdc100344130d7c677ea0b498",
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Audience"
}
}
}
}
}
},
"security": [
{
"basicAuth": []
}
]
},
"post": {
"tags": [
"Audiences"
],
"summary": "Create an audience",
"description": "Create an audience. Audiences are used to organize leads, contacts, and accounts into groups for marketing.",
"operationId": "9e1046e87d298eda177cb6323ddaa01c",
"requestBody": {
"description": "The name of the audience to be created.",
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"emAudiences": {
"description": "The name of the audience to be created.",
"type": "array",
"items": {
"properties": {
"name": {
"type": "string",
"example": "Your Audience"
}
},
"type": "object"
}
}
},
"type": "object"
}
}
}
},
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"properties": {
"emAudiences": {
"description": "Properties of the created audience",
"type": "array",
"items": {
"properties": {
"id": {
"type": "string",
"example": "1-emAudiences"
},
"type": {
"type": "string",
"example": "emAudiences"
},
"name": {
"type": "string",
"example": "Your Audience"
},
"isWebFX": {
"type": "boolean",
"example": false
}
},
"type": "object"
}
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
}
]
}
},
"/competitors/{id}": {
"get": {
"tags": [
"Competitors"
],
"summary": "Get a competitor",
"operationId": "c7625772e8320ae9d155b40b1974291b",
"parameters": [
{
"name": "id",
"in": "path",
"description": "The ID of the competitor",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "A single competitor",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CompetitorResponse"
}
}
}
}
},
"security": [
{
"basicAuth": []
}
]
}
},
"/competitors": {
"get": {
"tags": [
"Competitors"
],
"summary": "Get a list of competitors",
"operationId": "3013cdcf2331b70ff8d2cebc7a4c3c81",
"parameters": [
{
"name": "q",
"in": "query",
"description": "String to search for in competitor name",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "A list of competitors",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CompetitorResponse"
}
}
}
}
},
"security": [
{
"basicAuth": []
}
]
}
},
"/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": []
}
]
}
},
"/contacts/{id}": {
"get": {
"tags": [
"Contacts (People)"
],
"summary": "Get a contact",
"description": "Returns a single contact based on the provided ID.",
"operationId": "8a291bf9a1a7e4a7fd1ca0cabfdaa8a7",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Contact ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Contact",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ContactResponse"
}
}
}
}
},
"security": [
{
"basicAuth": []
}
]
},
"delete": {
"tags": [
"Contacts (People)"
],
"summary": "Delete a contact",
"description": "Deletes a contact from Nutshell. Can be recovered by posting to /contacts/{id}/undelete",
"operationId": "2b3d155b2889d34aa67235e67aa91d3f",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Contact ID",
"required": true,
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
}
],
"responses": {
"204": {
"description": "No Content"
}
},
"security": [
{
"basicAuth": []
}
]
},
"patch": {
"tags": [
"Contacts (People)"
],
"summary": "Update a contact",
"description": "Update a contact by id.
op is the operation to be performed, and path specifies what resource to patch.
Use the path contacts/0/fieldName to update fields that are user-entered for this resource, i.e. name, description, etc.
Use the path contacts/0/links/fieldName to update this contact's links to other resources within Nutshell, i.e. accounts, owner, territory, emAudiences, etc. When performing an 'add', include a /- at the end of the path, i.e. contacts/0/links/fieldName/- .
When using the remove operation, include the id at the end of the path (i.e. contacts/0/links/accounts/1-accounts) - no need to include a value.
Value can alternatively be a list of objects, which can be used with the replace operation and the path contacts/0/urls, contacts/0/addresses, contacts/0/phones, contacts/0/phones, contacts/0/links/emAudiences, or contacts/0/links/accounts to replace the existing list with a list of new objects. For certain replace operations like accounts and emAudiences, provide an array of strings as the value.
Visit the contact docs for more detail on the structure of these objects. ",
"operationId": "cb995ae09d7e0e99e91b122bcc9358ed",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Ids are of the form 'n-contacts', 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": []
}
]
}
},
"/contacts/{id}/customfields": {
"get": {
"tags": [
"Contacts (People)"
],
"summary": "Get contact custom fields",
"description": "Returns a list of custom fields for a contact.",
"operationId": "66abde512928a58ff9e3d7fac51a236e",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Contact ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Custom Fields",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CustomField"
}
}
}
}
}
},
"security": [
{
"basicAuth": []
}
]
}
},
"/contacts/customfields/attributes": {
"get": {
"tags": [
"Contacts (People)"
],
"summary": "Get applicable custom fields",
"description": "Get a list of all custom fields that can be applied to any contact.",
"operationId": "6f66fdf709475681e4e16528980ec105",
"responses": {
"200": {
"description": "Custom Fields",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CustomField"
}
}
}
}
}
},
"security": [
{
"basicAuth": []
}
]
}
},
"/contacts/customfield": {
"post": {
"tags": [
"Contacts (People)"
],
"summary": "Create a custom field",
"description": "Creates a custom field to use for contacts.",
"operationId": "e156619e0c6caae9203e0c505a33bcad",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CustomFieldCreateInput"
}
}
}
},
"responses": {
"200": {
"description": "OK"
}
},
"security": [
{
"basicAuth": []
}
]
}
},
"/contacts": {
"get": {
"tags": [
"Contacts (People)"
],
"summary": "Get a list of contacts",
"description": "Returns a number of contacts which is filterable based on their basic information.",
"operationId": "cde301caba6b033521a71e6bed772a58",
"parameters": [
{
"name": "email",
"in": "query",
"description": "Returns contacts with the provided email address.",
"schema": {
"type": "string"
}
},
{
"name": "q",
"in": "query",
"description": "Returns contacts with a piece of information similar to the provided string, such as name, email, location, etc.",
"schema": {
"type": "string"
}
},
{
"name": "sort",
"in": "query",
"description": "What criteria to order the returned list of results.",
"schema": {
"type": "string",
"enum": [
"accountType",
"-accountType",
"accounts",
"-accounts",
"createdTime",
"-createdTime",
"email",
"-email",
"industry",
"-industry",
"lastContactedTime",
"-lastContactedTime",
"name",
"-name",
"owner",
"-owner",
"phone",
"-phone",
"postalCode",
"-postalCode",
"territory",
"-territory"
]
}
},
{
"name": "filter",
"in": "query",
"required": false,
"style": "deepObject",
"explode": true,
"schema": {
"description": "Filter the returned contacts based on various criteria. Use /rest/contacts/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": "Contact",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ContactResponse"
}
}
}
}
},
"security": [
{
"basicAuth": []
}
]
},
"post": {
"tags": [
"Contacts (People)"
],
"summary": "Create a contact",
"description": "Create a new contact, also known as a person, in Nutshell. Only one contact may be created at a time.",
"operationId": "376a09558c05d3d4d273459f15a57326",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/contactPostInput"
}
}
}
},
"responses": {
"200": {
"description": "Contact",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ContactResponse"
}
}
}
}
},
"security": [
{
"basicAuth": []
}
]
}
},
"/contacts/{id}/undelete": {
"post": {
"tags": [
"Contacts (People)"
],
"summary": "Undelete a contact",
"operationId": "c56447f926210f833c484e8ba7486e8c",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Contact ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Contact",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ContactResponse"
}
}
}
}
},
"security": [
{
"basicAuth": []
}
]
}
},
"/contacts/list": {
"get": {
"tags": [
"Contacts (People)"
],
"summary": "Get list items for all contacts",
"description": "Get a list of all contacts and associated data in your Nutshell Instance, in a list item format. List items have additional fields attached to them for filtering purposes. Contacts are people that you do business with, and are referred to as 'People' in the Nutshell UI.",
"operationId": "7416ffd79a200377cb6276e02b1f5ddb",
"parameters": [
{
"name": "filter",
"in": "query",
"required": false,
"style": "deepObject",
"explode": true,
"schema": {
"description": "Filter the returned contacts based on various criteria. Use /rest/contacts/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",
"-accounts",
"-createdTime",
"-industry",
"-lastContactedTime",
"-owner",
"-phone",
"-postalCode",
"-territory",
"accountType",
"accounts",
"createdTime",
"industry",
"lastContactedTime",
"owner",
"phone",
"postalCode",
"territory"
]
}
}
}
],
"responses": {
"200": {
"description": "contacts list",
"content": {
"application/json": {
"schema": {
"properties": {
"meta": {
"allOf": [
{
"properties": {
"count": {
"description": "The number of returned contacts",
"type": "integer",
"format": "int32"
}
},
"type": "object"
},
{
"properties": {
"total": {
"description": "The total number of contacts in your Nutshell instance",
"type": "integer",
"format": "int32"
}
},
"type": "object"
},
{
"$ref": "#/components/schemas/meta"
}
]
},
"listItems": {
"type": "array",
"items": {
"allOf": [
{
"$ref": "#/components/schemas/ListItemContact"
},
{
"$ref": "#/components/schemas/HtmlLinkable"
},
{
"$ref": "#/components/schemas/Avatarable"
}
]
}
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
}
]
}
},
"/contacts/list/fields": {
"get": {
"tags": [
"Contacts (People)"
],
"summary": "Get the fields for a contact",
"description": "Get the list of fields that can possibly be associated with contacts, along with whether they are valid for filtering sorting.",
"operationId": "a2e78cb11ef577ef33e5c162da51ab51",
"responses": {
"200": {
"description": "Contact fields",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FieldsResponse"
}
}
}
}
},
"security": [
{
"basicAuth": []
}
]
}
},
"/editions": {
"get": {
"tags": [
"Editions"
],
"summary": "Get a list of editions",
"operationId": "4a302c8065d7f9015251d17f23bb237e",
"responses": {
"200": {
"description": "A list of editions",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Edition"
}
}
}
}
},
"security": [
{
"basicAuth": []
}
]
}
},
"/editions/{id}": {
"get": {
"tags": [
"Editions"
],
"summary": "Get a single edition by its ID",
"operationId": "7975bcc74536182c42a0ceca95dcbc35",
"parameters": [
{
"name": "id",
"in": "path",
"description": "The ID of the edition",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "An edition",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Edition"
}
}
}
}
},
"security": [
{
"basicAuth": []
}
]
}
},
"/emails/{id}": {
"get": {
"tags": [
"Emails"
],
"summary": "Get an email",
"operationId": "43ba2d674b5cc459bb8cdf42698d303f",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Email ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Email"
}
},
"security": [
{
"basicAuth": []
}
]
}
},
"/events": {
"get": {
"tags": [
"Events (Timeline)"
],
"summary": "Get a list of events",
"description": "Retrieve a feed of events. Events, also known as change logs, are a record of everything that happened in Nutshell. They're used to power notifications and timelines among other things.",
"operationId": "975fac2bed2a6a346717a88cfcdb9324",
"parameters": [
{
"name": "max_id",
"in": "query",
"description": "Retrieve a feed of events with an ID less than or equal to than the specified ID",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "since_id",
"in": "query",
"description": "Retrieve a feed of events with an ID greater than the specified ID",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "max_time",
"in": "query",
"description": "Retrieve a feed of events that occurred before the specified time",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "since_time",
"in": "query",
"description": "Retrieve a feed of events that occurred after the specified time",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "entity_id",
"in": "query",
"description": "Retrieve a feed of events related to a specific entity",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "limit",
"in": "query",
"description": "The number of events to return",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "events",
"in": "query",
"description": "Opt in to additional event types: comments, mailchimp, followup, constantContact, emailInteraction, assignments, formSubmissions",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"comments",
"mailchimp",
"followup",
"constantContact",
"emailInteraction",
"assignments",
"formSubmissions"
]
}
}
},
{
"name": "filters[payload][]",
"in": "query",
"description": "Retrieve a feed of events related to a type of entity",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"accounts",
"activities",
"assignments",
"chats",
"companyEnrichment",
"constantContact",
"contacts",
"emails",
"emailInteraction",
"formSubmissions",
"inbox_threads",
"leadUpdates",
"leads",
"marketingEmails",
"mcfxSessions",
"notes",
"queued",
"ticketMessages",
"undelivered",
"unshared"
]
}
}
},
{
"name": "filters[creator][]",
"in": "query",
"description": "Retrieve a feed of events caused by a specific user or team",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
},
{
"name": "filters[emailEntityType][]",
"in": "query",
"description": "Whether to receive email sent or received events. Requires a creator filter",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"sender",
"recipient"
]
}
}
}
],
"responses": {
"200": {
"description": "A list of events",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EventResponse"
}
}
}
}
},
"security": [
{
"basicAuth": []
}
]
}
},
"/events/deleted": {
"get": {
"tags": [
"Events (Timeline)"
],
"summary": "Get deletion events",
"description": "Retrieve a feed of every time an entity was deleted.",
"operationId": "eade9331abb11f33feaeb9e9d8ae89a7",
"parameters": [
{
"name": "filter[types]",
"in": "query",
"description": "Retrieve a feed of events related to a type of entity",
"required": false,
"schema": {
"type": "string",
"enum": [
"accounts",
"activities",
"assignments",
"chats",
"companyEnrichment",
"constantContact",
"contacts",
"emails",
"emailInteraction",
"formSubmissions",
"inbox_threads",
"leadUpdates",
"leads",
"marketingEmails",
"mcfxSessions",
"notes",
"queued",
"ticketMessages",
"undelivered",
"unshared"
]
}
},
{
"name": "sort",
"in": "query",
"description": "Reverse the order of returned results",
"required": false,
"schema": {
"type": "string",
"enum": [
"-change_time"
]
}
}
],
"responses": {
"200": {
"description": "A list of events",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EventResponse"
}
}
}
}
},
"security": [
{
"basicAuth": []
}
]
}
},
"/filters": {
"get": {
"tags": [
"Filter"
],
"summary": "Get saved filters",
"description": "Get saved filters",
"operationId": "9bbf17f9beb5e7eebe638a634e861945",
"parameters": [
{
"name": "userId",
"in": "query",
"description": "The user ID to get saved filters for",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "reportType",
"in": "query",
"description": "The type of saved filters to get. Use report_* to get all report filters, or entity_list_leads, entity_list_contacts, entity_list_accounts to get all filters for the given entity type.",
"required": false,
"schema": {
"type": "string",
"enum": [
"report_*",
"entity_list_leads",
"entity_list_contacts",
"entity_list_accounts"
]
}
},
{
"name": "filter",
"in": "query",
"description": "Filter options",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success"
}
}
}
},
"/forms": {
"get": {
"tags": [
"Forms"
],
"summary": "Get all forms",
"description": "Get all non-archived nutshell forms along with the IDs of the fields used in each form.",
"operationId": "b0fec1131366b61118593ec9e86a4c9e",
"responses": {
"200": {
"description": "Forms",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormResponse"
}
}
}
}
},
"security": [
{
"basicAuth": []
}
]
}
},
"/forms/{id}": {
"get": {
"tags": [
"Forms"
],
"summary": "Get a form",
"description": "Get a single form by the ID provided. The fields used in the form are also returned in the response.",
"operationId": "c150c11fa75e601f12a5d0c3291b7e9c",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Form ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Form",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/FormResponse"
},
{
"properties": {
"wfFields": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Field"
}
}
},
"type": "object"
}
]
}
}
}
}
},
"security": [
{
"basicAuth": []
}
]
}
},
"/forms/{fieldId}": {
"get": {
"tags": [
"Forms"
],
"summary": "Get a form field",
"description": "Get a single form field by the ID provided.",
"operationId": "8218d4f193a6ef911f41a9ffdfbd4eb4",
"parameters": [
{
"name": "fieldId",
"in": "path",
"description": "Field Id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Form Field",
"content": {
"application/json": {
"schema": {
"properties": {
"wfFields": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Field"
}
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
}
]
}
},
"/industries/{id}": {
"get": {
"tags": [
"Industries"
],
"summary": "Get a single industry by its ID",
"operationId": "3d6ab32d8162c8d9fd58cd0f40888de4",
"parameters": [
{
"name": "id",
"in": "path",
"description": "The ID of the industry",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "An industry",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Industry"
}
}
}
}
},
"security": [
{
"basicAuth": []
}
]
}
},
"/industries": {
"get": {
"tags": [
"Accounts (Companies)"
],
"summary": "Get a list of industries",
"description": "Retreives the list of valid industries to describe companies as belonging to.",
"operationId": "7e2ccf9488b1ee4f602c7059eee817e5",
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Industry"
}
}
}
}
}
},
"security": [
{
"basicAuth": []
}
]
}
},
"/invoices/{id}": {
"get": {
"tags": [
"Invoices"
],
"summary": "Get an invoice",
"description": "Get a single invoice by the ID provided.",
"operationId": "b9c9d23692da5d58d025a29911416b8f",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Invoice ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Invoice",
"content": {
"application/json": {
"schema": {
"properties": {
"invoices": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Invoice"
},
"example": [
{
"id": "789-quotes",
"type": "invoices",
"number": "1000-01",
"displayStatus": "ACCEPTED",
"total": {
"amount": "3200.50",
"currency": "USD",
"formatted": "$3,200.50"
},
"productLineItems": [
{
"id": "1-quoteProductLineItems",
"position": 0,
"product": "100-products",
"name": "Consulting Services",
"description": "Monthly consulting retainer",
"sku": "CONS-001",
"quantity": 2,
"term": null,
"price": {
"amount": "1500.00",
"currency": "USD",
"formatted": "$1,500.00"
},
"total": {
"amount": "3000.00",
"currency": "USD",
"formatted": "$3,000.00"
},
"discountUnit": null,
"discountNumber": null
}
],
"subtotalLineItems": [
{
"id": "1-quoteSubtotalLineItems",
"position": 0,
"label": "Tax",
"modifierUnit": "%",
"modifierValue": 6.5,
"operation": "+",
"total": {
"amount": "200.50",
"currency": "USD",
"formatted": "$200.50"
}
}
],
"recipient": {
"id": "321-contacts",
"name": "Jane Doe",
"email": "jane@example.com"
},
"validThroughTime": "2024-12-31T23:59:59Z",
"createdTime": "2024-01-15T10:30:00Z",
"publishedTime": "2024-01-16T14:20:00Z",
"sentTime": "2024-01-17T09:15:00Z",
"paidTime": "2024-01-20T16:45:00Z",
"acceptedName": "Jane Customer",
"acceptedEmail": "jane@example.com",
"completionComment": "Paid via ACH",
"deletedTime": null,
"links": {
"lead": "456-leads"
}
}
]
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
}
]
}
},
"/invoices/{id}/status": {
"post": {
"tags": [
"Invoices"
],
"summary": "Update the status of an invoice",
"description": "Updates an invoice to a native Nutshell status (READY, SENT, REVOKED, ACCEPTED, ARCHIVED). ACCEPTED marks the invoice as paid. Optional comment is stored as payment/completion metadata.",
"operationId": "d35e25a23af6446bdc10dffb07a59c79",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Invoice ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"status"
],
"properties": {
"status": {
"type": "string",
"enum": [
"READY",
"SENT",
"REVOKED",
"ACCEPTED",
"ARCHIVED"
],
"example": "ACCEPTED"
},
"comment": {
"description": "Payment or completion note (invoices only, on ACCEPTED or REVOKED)",
"type": "string",
"example": "Paid via ACH"
},
"acceptedName": {
"description": "Optional name recorded when marking the invoice paid",
"type": "string"
},
"acceptedEmail": {
"description": "Optional email recorded when marking the invoice paid",
"type": "string"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Invoice",
"content": {
"application/json": {
"schema": {
"properties": {
"invoices": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Invoice"
},
"example": [
{
"id": "789-quotes",
"type": "invoices",
"number": "1000-01",
"total": {
"amount": "3200.50",
"currency": "USD",
"formatted": "$3,200.50"
},
"validThroughTime": "2024-12-31T23:59:59Z",
"createdTime": "2024-01-15T10:30:00Z",
"publishedTime": "2024-01-16T14:20:00Z",
"sentTime": "2024-01-17T09:15:00Z",
"paidTime": "2024-01-20T16:45:00Z",
"acceptedName": "Jane Customer",
"acceptedEmail": "jane@example.com",
"completionComment": "Paid via ACH",
"deletedTime": null,
"links": {
"lead": "456-leads"
}
}
]
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
}
]
}
},
"/invoices": {
"get": {
"tags": [
"Invoices"
],
"summary": "Get a list of invoices",
"operationId": "44a63cb9277feafb979ccef9038cd6d5",
"parameters": [
{
"name": "filter[lead]",
"in": "query",
"description": "Filter invoices by lead",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "filter[dateMin]",
"in": "query",
"description": "Filter invoices created after this date. Date expected in the format YYYY-MM-DD",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "filter[dateMax]",
"in": "query",
"description": "Filter invoices created before this date. Date expected in the format YYYY-MM-DD",
"required": false,
"schema": {
"type": "string"
}
},
{
"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": "A list of invoices",
"content": {
"application/json": {
"schema": {
"properties": {
"invoices": {
"description": "An array of invoice objects",
"type": "array",
"items": {
"$ref": "#/components/schemas/Invoice"
},
"example": [
{
"id": "789-quotes",
"type": "invoices",
"number": "1000-01",
"displayStatus": "ACCEPTED",
"total": {
"amount": "3200.50",
"currency": "USD",
"formatted": "$3,200.50"
},
"productLineItems": [
{
"id": "1-quoteProductLineItems",
"position": 0,
"product": "100-products",
"name": "Consulting Services",
"description": "Monthly consulting retainer",
"sku": "CONS-001",
"quantity": 2,
"term": null,
"price": {
"amount": "1500.00",
"currency": "USD",
"formatted": "$1,500.00"
},
"total": {
"amount": "3000.00",
"currency": "USD",
"formatted": "$3,000.00"
},
"discountUnit": null,
"discountNumber": null
}
],
"subtotalLineItems": [
{
"id": "1-quoteSubtotalLineItems",
"position": 0,
"label": "Tax",
"modifierUnit": "%",
"modifierValue": 6.5,
"operation": "+",
"total": {
"amount": "200.50",
"currency": "USD",
"formatted": "$200.50"
}
}
],
"recipient": {
"id": "321-contacts",
"name": "Jane Doe",
"email": "jane@example.com"
},
"validThroughTime": "2024-12-31T23:59:59Z",
"createdTime": "2024-01-15T10:30:00Z",
"publishedTime": "2024-01-16T14:20:00Z",
"sentTime": "2024-01-17T09:15:00Z",
"paidTime": "2024-01-20T16:45:00Z",
"acceptedName": "Jane Customer",
"acceptedEmail": "jane@example.com",
"completionComment": "Paid via ACH",
"deletedTime": null,
"links": {
"lead": "456-leads"
}
},
{
"id": "790-quotes",
"type": "invoices",
"number": "1000-02",
"displayStatus": "SENT",
"total": {
"amount": "1500.00",
"currency": "USD",
"formatted": "$1,500.00"
},
"productLineItems": [
{
"id": "2-quoteProductLineItems",
"position": 0,
"product": "101-products",
"name": "Setup Fee",
"description": "One-time setup",
"sku": "SETUP-001",
"quantity": 1,
"term": null,
"price": {
"amount": "1500.00",
"currency": "USD",
"formatted": "$1,500.00"
},
"total": {
"amount": "1500.00",
"currency": "USD",
"formatted": "$1,500.00"
},
"discountUnit": null,
"discountNumber": null
}
],
"subtotalLineItems": [],
"recipient": {
"id": "322-contacts",
"name": "John Smith",
"email": "john@example.com"
},
"validThroughTime": "2024-11-30T23:59:59Z",
"createdTime": "2024-02-01T08:00:00Z",
"publishedTime": "2024-02-02T10:00:00Z",
"sentTime": "2024-02-03T11:00:00Z",
"paidTime": null,
"acceptedName": null,
"acceptedEmail": null,
"completionComment": null,
"deletedTime": null,
"links": {
"lead": "457-leads"
}
}
]
},
"meta": {
"$ref": "#/components/schemas/meta"
},
"links": {
"description": "Pagination links",
"type": "object",
"example": {
"self": "/rest/invoices?page[page]=0&page[limit]=25",
"first": "/rest/invoices?page[page]=0&page[limit]=25",
"last": "/rest/invoices?page[page]=0&page[limit]=25"
}
}
},
"type": "object"
}
}
}
}
},
"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.
op is the operation to be performed, and path specifies what resource to patch.
Use the path leads/0/fieldName to update fields that are user-entered for this resource, i.e. name, description, etc.
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/- .
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.
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": []
}
]
}
},
"/markets/{id}": {
"get": {
"tags": [
"Markets"
],
"summary": "Get a market by the ID",
"operationId": "1ea697bdc341c343978370e0465ec30a",
"parameters": [
{
"name": "id",
"in": "path",
"description": "The ID of the market",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "A market",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Market"
}
}
}
}
},
"security": [
{
"basicAuth": []
}
]
}
},
"/markets": {
"get": {
"tags": [
"Markets"
],
"summary": "Get a list of markets",
"operationId": "9768a284fcd11af320b20036afca17d6",
"responses": {
"200": {
"description": "A list of markets",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Market"
}
}
}
}
},
"security": [
{
"basicAuth": []
}
]
}
},
"/notes/{id}": {
"get": {
"tags": [
"Notes"
],
"summary": "Get a note",
"description": "Get a single note by the ID provided.",
"operationId": "7cda4297fad55a1bd186049667840325",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Note ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Note",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Note"
}
}
}
}
},
"security": [
{
"basicAuth": []
}
]
},
"delete": {
"tags": [
"Notes"
],
"summary": "Delete a note.",
"description": "Delete a note by the ID provided. Can be restored with the undelete endpoint.",
"operationId": "836127953fcc40da01ecc8c605bad12a",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Note ID",
"required": true,
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
}
],
"responses": {
"200": {
"description": "Note",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Note"
}
}
}
}
},
"security": [
{
"basicAuth": []
}
]
}
},
"/notes/{id}/undelete": {
"post": {
"tags": [
"Notes"
],
"summary": "Undelete a note.",
"description": "Undelete a note by the ID provided.",
"operationId": "56325ab1a38cdcc6bcbbdbe540a78907",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Note ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Note",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Note"
}
}
}
}
},
"security": [
{
"basicAuth": []
}
]
}
},
"/notes": {
"get": {
"tags": [
"Notes"
],
"summary": "Get a list of notes",
"description": "Get a list of notes.",
"operationId": "c855c6708aa8bb59e12dd00ac6afbd04",
"parameters": [
{
"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": "Note",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Note"
}
}
}
}
},
"security": [
{
"basicAuth": []
}
]
},
"post": {
"tags": [
"Notes"
],
"summary": "Create a note",
"operationId": "d75ec624406914f4ac17a0cf1fc38d05",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/notePostInput"
}
}
}
},
"responses": {
"201": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Note"
}
}
}
}
},
"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": []
}
]
}
},
"/products/{id}": {
"get": {
"tags": [
"Products"
],
"summary": "Get a product",
"operationId": "e524bd8b37d52ef8fa586cadacfbbe63",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Product",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProductResponse"
}
}
}
}
},
"security": [
{
"basicAuth": []
}
]
},
"delete": {
"tags": [
"Products"
],
"summary": "Delete a product",
"operationId": "1fb8ea517bd0df4cfe5fedda69e56084",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProductResponse"
}
}
}
},
"204": {
"description": "No Content"
}
},
"security": [
{
"basicAuth": []
}
]
}
},
"/products/{id}/undelete": {
"post": {
"tags": [
"Products"
],
"summary": "Undelete a product",
"operationId": "799d14014dfe97d25006bd23aa1955de",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProductResponse"
}
}
}
},
"400": {
"description": "Bad Request"
}
},
"security": [
{
"basicAuth": []
}
]
}
},
"/products": {
"get": {
"tags": [
"Products"
],
"summary": "List all products",
"operationId": "09a50065f621a61a55b5bc5c0df3f338",
"parameters": [
{
"name": "q",
"in": "query",
"description": "Filter for matching name or sku",
"schema": {
"type": "string"
}
},
{
"name": "sort",
"in": "query",
"schema": {
"type": "string",
"enum": [
"name",
"-name",
"sku",
"-sku"
]
}
}
],
"responses": {
"200": {
"description": "List of products",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProductResponse"
}
}
}
}
},
"security": [
{
"basicAuth": []
}
]
}
},
"/productcategories": {
"get": {
"tags": [
"ProductCategories"
],
"summary": "List all product categories",
"operationId": "717f48307abd255776158e66cbbe8656",
"responses": {
"200": {
"description": "List of product categories",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProductCategoryResponse"
}
}
}
}
},
"security": [
{
"basicAuth": []
}
]
},
"post": {
"tags": [
"ProductCategories"
],
"summary": "Create a product category",
"description": "Create a new product category. Product categories are used to organize products into groups.",
"operationId": "6b6ddd29d78bb86bfa27c73614f601ff",
"requestBody": {
"description": "Name is required.",
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"productCategories": {
"type": "array",
"items": {
"properties": {
"name": {
"type": "string",
"example": "Electronics"
}
},
"type": "object"
}
}
},
"type": "object"
}
}
}
},
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProductCategoryResponse"
}
}
}
},
"400": {
"description": "Bad Request"
}
},
"security": [
{
"basicAuth": []
}
]
}
},
"/productcategories/{id}": {
"get": {
"tags": [
"ProductCategories"
],
"summary": "Get a product category",
"operationId": "e35b57d17d5dad46410b632e6e4a539d",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Product Category ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Product category",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProductCategoryResponse"
}
}
}
}
},
"security": [
{
"basicAuth": []
}
]
}
},
"/productmaps/{id}": {
"get": {
"tags": [
"Products"
],
"summary": "Get lead product",
"description": "A product map is an instance of a product attached to a lead, including quantity and custom pricing information. This endpoint returns a single mapping between a particular product and lead.",
"operationId": "741f6e4eb5abcbdfc94754dd76257d9e",
"parameters": [
{
"name": "id",
"in": "path",
"description": "ProductMap ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LeadProductMapResponse"
}
}
}
}
},
"security": [
{
"basicAuth": []
}
]
},
"patch": {
"tags": [
"Products"
],
"summary": "Update a lead's product information.",
"description": "A product map is an instance of a product attached to a lead, including quantity and custom pricing information which this endpoint allows you to modify.",
"operationId": "427685c90f14ed7ca22515715a03b4e4",
"parameters": [
{
"name": "id",
"in": "path",
"description": "ProductMap ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/productMapPatchInput"
}
}
}
},
"responses": {
"204": {
"description": "No Content"
}
},
"security": [
{
"basicAuth": []
}
]
}
},
"/productMaps/{id}": {
"delete": {
"tags": [
"Products"
],
"summary": "Delete a product on a lead",
"operationId": "7aa410de8a00f46edf22043fee324e39",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LeadProductMapResponse"
}
}
}
},
"204": {
"description": "No Content"
}
},
"security": [
{
"basicAuth": []
}
]
}
},
"/productmaps": {
"get": {
"tags": [
"Products"
],
"summary": "Get lead products",
"description": "A product map is an instance of a product attached to a lead, including quantity and custom pricing information. This endpoint returns all mappings between products and leads.",
"operationId": "4bc737ff6f91aab43dc7617f2c36ab3c",
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LeadProductMapResponse"
}
}
}
}
},
"security": [
{
"basicAuth": []
}
]
}
},
"/quotes/{id}": {
"get": {
"tags": [
"Quotes"
],
"summary": "Get a quote",
"description": "Get a single quote by the ID provided.",
"operationId": "4c251930a518927960cce7d1211a0945",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Quote ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Quote",
"content": {
"application/json": {
"schema": {
"properties": {
"quotes": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Quote"
},
"example": [
{
"id": "123-quotes",
"type": "quotes",
"number": "1000-01",
"displayStatus": "SENT",
"total": {
"amount": "5000.00",
"currency": "USD",
"formatted": "$5,000.00"
},
"productLineItems": [
{
"id": "1-quoteProductLineItems",
"position": 0,
"product": "100-products",
"name": "Consulting Services",
"description": "Monthly consulting retainer",
"sku": "CONS-001",
"quantity": 2,
"term": null,
"price": {
"amount": "2500.00",
"currency": "USD",
"formatted": "$2,500.00"
},
"total": {
"amount": "5000.00",
"currency": "USD",
"formatted": "$5,000.00"
},
"discountUnit": null,
"discountNumber": null
}
],
"subtotalLineItems": [
{
"id": "1-quoteSubtotalLineItems",
"position": 0,
"label": "Discount",
"modifierUnit": "%",
"modifierValue": 10,
"operation": "-",
"total": {
"amount": "500.00",
"currency": "USD",
"formatted": "$500.00"
}
}
],
"recipient": {
"id": "321-contacts",
"name": "Jane Doe",
"email": "jane@example.com"
},
"validThroughTime": "2024-12-31T23:59:59Z",
"createdTime": "2024-01-15T10:30:00Z",
"publishedTime": "2024-01-16T14:20:00Z",
"sentTime": "2024-01-17T09:15:00Z",
"acceptedTime": null,
"acceptedName": null,
"acceptedEmail": null,
"deletedTime": null,
"links": {
"lead": "456-leads"
}
}
]
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
}
]
}
},
"/quotes/{id}/status": {
"post": {
"tags": [
"Quotes"
],
"summary": "Update the status of a quote",
"description": "Updates a quote to a native Nutshell status (READY, SENT, REVOKED, ACCEPTED, ARCHIVED). Odoo-specific fulfillment states should be stored on the lead via custom fields.",
"operationId": "9809f001604e5cbe8f478e14b6ec6295",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Quote ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"required": [
"status"
],
"properties": {
"status": {
"type": "string",
"enum": [
"READY",
"SENT",
"REVOKED",
"ACCEPTED",
"ARCHIVED"
],
"example": "SENT"
},
"acceptedName": {
"description": "Optional name recorded when accepting the quote",
"type": "string"
},
"acceptedEmail": {
"description": "Optional email recorded when accepting the quote",
"type": "string"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "Quote",
"content": {
"application/json": {
"schema": {
"properties": {
"quotes": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Quote"
},
"example": [
{
"id": "123-quotes",
"type": "quotes",
"number": "1000-01",
"total": {
"amount": "5000.00",
"currency": "USD",
"formatted": "$5,000.00"
},
"validThroughTime": "2024-12-31T23:59:59Z",
"createdTime": "2024-01-15T10:30:00Z",
"publishedTime": "2024-01-16T14:20:00Z",
"sentTime": "2024-01-17T09:15:00Z",
"acceptedTime": "2024-01-20T16:45:00Z",
"acceptedName": "Jane Customer",
"acceptedEmail": "jane@example.com",
"deletedTime": null,
"links": {
"lead": "456-leads"
}
}
]
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
}
]
}
},
"/quotes/{id}/invoice": {
"post": {
"tags": [
"Quotes"
],
"summary": "Create an invoice from a quote",
"description": "Creates a new invoice by duplicating the quote (same as in-app create invoice from quote). Line items, recipient, and most document fields are copied from the quote; invoice template defaults apply for payment/body/footer fields. No request body is required.",
"operationId": "8ce989ecb071d43420747aa852f155db",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Quote ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"201": {
"description": "Invoice",
"content": {
"application/json": {
"schema": {
"properties": {
"invoices": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Invoice"
}
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
}
]
}
},
"/quotes": {
"get": {
"tags": [
"Quotes"
],
"summary": "Get a list of quotes",
"operationId": "1aee48fe1472d38116c60c87e2ca4161",
"parameters": [
{
"name": "filter[lead]",
"in": "query",
"description": "Filter quotes by lead",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "filter[dateMin]",
"in": "query",
"description": "Filter quotes created after this date. Date expected in the format YYYY-MM-DD",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "filter[dateMax]",
"in": "query",
"description": "Filter quotes created before this date. Date expected in the format YYYY-MM-DD",
"required": false,
"schema": {
"type": "string"
}
},
{
"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": "A list of quotes",
"content": {
"application/json": {
"schema": {
"properties": {
"quotes": {
"description": "An array of quote objects",
"type": "array",
"items": {
"$ref": "#/components/schemas/Quote"
},
"example": [
{
"id": "123-quotes",
"type": "quotes",
"number": "1000-01",
"displayStatus": "SENT",
"total": {
"amount": "5000.00",
"currency": "USD",
"formatted": "$5,000.00"
},
"productLineItems": [
{
"id": "1-quoteProductLineItems",
"position": 0,
"product": "100-products",
"name": "Consulting Services",
"description": "Monthly consulting retainer",
"sku": "CONS-001",
"quantity": 2,
"term": null,
"price": {
"amount": "2500.00",
"currency": "USD",
"formatted": "$2,500.00"
},
"total": {
"amount": "5000.00",
"currency": "USD",
"formatted": "$5,000.00"
},
"discountUnit": null,
"discountNumber": null
}
],
"subtotalLineItems": [
{
"id": "1-quoteSubtotalLineItems",
"position": 0,
"label": "Discount",
"modifierUnit": "%",
"modifierValue": 10,
"operation": "-",
"total": {
"amount": "500.00",
"currency": "USD",
"formatted": "$500.00"
}
}
],
"recipient": {
"id": "321-contacts",
"name": "Jane Doe",
"email": "jane@example.com"
},
"validThroughTime": "2024-12-31T23:59:59Z",
"createdTime": "2024-01-15T10:30:00Z",
"publishedTime": "2024-01-16T14:20:00Z",
"sentTime": "2024-01-17T09:15:00Z",
"acceptedTime": null,
"acceptedName": null,
"acceptedEmail": null,
"deletedTime": null,
"links": {
"lead": "456-leads"
}
},
{
"id": "124-quotes",
"type": "quotes",
"number": "1000-02",
"displayStatus": "READY",
"total": {
"amount": "7500.00",
"currency": "USD",
"formatted": "$7,500.00"
},
"productLineItems": [
{
"id": "2-quoteProductLineItems",
"position": 0,
"product": "101-products",
"name": "Implementation",
"description": "Onboarding package",
"sku": "IMPL-001",
"quantity": 1,
"term": null,
"price": {
"amount": "7500.00",
"currency": "USD",
"formatted": "$7,500.00"
},
"total": {
"amount": "7500.00",
"currency": "USD",
"formatted": "$7,500.00"
},
"discountUnit": null,
"discountNumber": null
}
],
"subtotalLineItems": [],
"recipient": null,
"validThroughTime": "2024-11-30T23:59:59Z",
"createdTime": "2024-02-01T08:00:00Z",
"publishedTime": "2024-02-02T10:00:00Z",
"sentTime": null,
"acceptedTime": null,
"acceptedName": null,
"acceptedEmail": null,
"deletedTime": null,
"links": {
"lead": "457-leads"
}
}
]
},
"meta": {
"$ref": "#/components/schemas/meta"
},
"links": {
"description": "Pagination links",
"type": "object",
"example": {
"self": "/rest/quotes?page[page]=0&page[limit]=25",
"first": "/rest/quotes?page[page]=0&page[limit]=25",
"last": "/rest/quotes?page[page]=0&page[limit]=25"
}
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
}
]
}
},
"/sources/{id}": {
"delete": {
"tags": [
"Sources"
],
"summary": "Delete a Source",
"description": "Delete a source by ID. Deleted sources are removed from the sources tab, and can be restored from the trash within 30 days of deletion via the undelete endpoint.",
"operationId": "4d0d83bd963cdf17734d5dacc8fe4235",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Ids are of the form 'n-sources', where n is an integer.",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"description": "Returns the deleted source",
"properties": {
"sources": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Source"
}
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
}
]
}
},
"/sources/{id}/undelete": {
"post": {
"tags": [
"Sources"
],
"summary": "Undelete a Source",
"description": "Undelete a source by id.",
"operationId": "80894cc152322d74d5a4115aca5297f9",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Ids are of the form 'n-sources', where n is an integer.",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"description": "Returns the undeleted source",
"properties": {
"sources": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Source"
}
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
}
]
}
},
"/sources": {
"get": {
"tags": [
"Sources"
],
"summary": "Get a list of sources",
"description": "Returns a list of all possible sources for leads in your Nutshell instance.",
"operationId": "2d07cb07b45de2ae13701b873b26cf9e",
"parameters": [
{
"name": "q",
"in": "query",
"description": "Query for sources that match a specific string",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"properties": {
"sources": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Source"
}
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
}
]
},
"post": {
"tags": [
"Sources"
],
"summary": "Create a new source",
"description": "Create a new source for leads in your Nutshell instance. Sources are used to track how leads arrive at your website and learn about your business.",
"operationId": "cd431c40f2b57127c71b15044d270a13",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"sources": {
"type": "array",
"items": {
"properties": {
"name": {
"description": "The name of the source",
"type": "string"
},
"channel": {
"description": "The channel of the source. 0 = no channel, 1 = organic search, 2 = paid search, 3 = organic social, 4 = paid social, 5 = email, 6 = referrer, 7 = traditional, 8 = direct to website",
"type": "integer",
"enum": [
0,
1,
2,
3,
4,
5,
6,
7,
8
]
}
},
"type": "object"
}
}
},
"type": "object"
}
}
}
},
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"properties": {
"sources": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Source"
}
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
}
]
}
},
"/stages": {
"get": {
"tags": [
"Stagesets (Pipelines)"
],
"summary": "Get a list of stages",
"operationId": "14af5dd687ab31f65e5af1a2b1fa5527",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Stage"
}
}
}
}
}
},
"security": [
{
"basicAuth": []
}
]
}
},
"/stagesets": {
"get": {
"tags": [
"Stagesets (Pipelines)"
],
"summary": "Get a list of pipelines",
"description": "Gets a list of pipelines that leads can be assigned to. Pipelines are also known as stagesets.",
"operationId": "7e925de7233253ea915fdf486fb23321",
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Stageset"
}
}
}
}
}
},
"security": [
{
"basicAuth": []
}
]
}
},
"/stagesets/{id}/export": {
"get": {
"tags": [
"Stagesets (Pipelines)"
],
"summary": "Get a CSV export of lead movements through a pipeline",
"description": "Get a CSV export of lead movements through a pipeline",
"operationId": "add7f9ef66629fa4ccee5dcc0479795b",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Stageset ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "CSV file"
}
},
"security": [
{
"basicAuth": []
}
]
}
},
"/tags/{id}": {
"delete": {
"tags": [
"Tags"
],
"summary": "Delete a tag",
"description": "Delete a tag by id. Deleted tags are removed from the list of tags, and can be restored from the trash within 30 days of deletion via the undelete endpoint.",
"operationId": "796b8e738949a2a0563da5032e29a12c",
"parameters": [
{
"name": "id",
"in": "path",
"description": "id of the form n-tags, where n is an integer.
Ids can be listed in a comma-separated format to delete multiple tags at once.",
"required": true,
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"properties": {
"tags": {
"description": "Contains the deleted tags",
"type": "array",
"items": {
"$ref": "#/components/schemas/Tag"
}
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
}
]
}
},
"/tags": {
"get": {
"tags": [
"Tags"
],
"summary": "Get a list of tags",
"description": "Get a list of all tags in a Nutshell instance.",
"operationId": "422aa2c0d6493b41248e46c6ac93a43b",
"parameters": [
{
"name": "q",
"in": "query",
"description": "Used to query for tags that match a specific string",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "filter[tagType]",
"in": "query",
"description": "Used to get tags of a specific type",
"required": false,
"schema": {
"type": "string",
"enum": [
"leads",
"contacts",
"accounts"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"properties": {
"tags": {
"description": "The list of tags",
"type": "array",
"items": {
"$ref": "#/components/schemas/Tag"
}
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
}
]
},
"post": {
"tags": [
"Tags"
],
"summary": "Create a tag",
"description": "Create a tag. Tags are used to organize leads, contacts, and accounts into groups.",
"operationId": "88c135d662e0a79e2a0c5fdf337ba537",
"requestBody": {
"description": "Name and tagType are required.",
"required": true,
"content": {
"json": {
"schema": {
"properties": {
"tags": {
"type": "array",
"items": {
"properties": {
"name": {
"type": "string",
"example": "Enterprise"
},
"colorType": {
"description": "Use '1' for default, '2' for grey, '3' for red, '4' for light red, '5' for orange, '6' for light orange, '7' for yellow, '8' for light yellow, '9' for blue, '10' for light blue, '11' for green, '12' for light green, '13' for purple, '14' for light purple",
"type": "string",
"enum": [
"1",
"2",
"3",
"4",
"5",
"6",
"7",
"8",
"9",
"10",
"11",
"12",
"13",
"14"
]
},
"tagType": {
"description": "Use '1' for leads, '2' for contacts, '3' for accounts",
"type": "string",
"enum": [
"1",
"2",
"3"
]
},
"links": {
"description": "Array of entity IDs to link the tag to",
"properties": {
"entities": {
"type": "array",
"items": {
"type": "string"
}
}
},
"type": "object"
}
},
"type": "object"
}
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"properties": {
"tags": {
"description": "Contains the created tag",
"type": "array",
"items": {
"$ref": "#/components/schemas/Tag"
}
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
}
]
}
},
"/tags/{id}/undelete": {
"post": {
"tags": [
"Tags"
],
"summary": "Undelete a tag",
"description": "Undelete a tag by id. Tags can be restored from the trash within 30 days of deletion.",
"operationId": "f09a0e050d70fe8d55b68a0ddddd3df0",
"parameters": [
{
"name": "id",
"in": "path",
"description": "id in the form n-tags, where n is an integer",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"properties": {
"tags": {
"description": "Contains the undeleted tag",
"type": "array",
"items": {
"$ref": "#/components/schemas/Tag"
}
}
},
"type": "object"
}
}
}
}
},
"security": [
{
"basicAuth": []
}
]
}
},
"/tasks/{id}": {
"get": {
"tags": [
"Tasks"
],
"summary": "Get a task",
"description": "Get a single task by the ID provided.",
"operationId": "04c249286f1032bdf6d8178e0e9f384c",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Task ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Task",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Task"
}
}
}
}
},
"security": [
{
"basicAuth": []
}
]
},
"delete": {
"tags": [
"Tasks"
],
"summary": "Delete a task.",
"description": "Delete a task by the ID provided.",
"operationId": "8df89ef1ffa672b94c860d2b6b77ee16",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Task ID",
"required": true,
"style": "simple",
"explode": false,
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
}
],
"responses": {
"200": {
"description": "Task",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Task"
}
}
}
}
},
"security": [
{
"basicAuth": []
}
]
},
"patch": {
"tags": [
"Tasks"
],
"summary": "Update a task",
"description": "Update a task by id.
op is the operation to be performed, and path specifies what resource to patch.
Use the path tasks/0/links/assignee to update the assigned user, using their ID. ",
"operationId": "fab5f8833c76cb64c8e82ec09416f467",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Ids are of the form 'n-tasks', where n is an integer.",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/patchInput"
}
}
}
},
"responses": {
"204": {
"description": "No Content"
}
},
"security": [
{
"basicAuth": []
}
]
}
},
"/tasks": {
"get": {
"tags": [
"Tasks"
],
"summary": "Get a list of tasks",
"operationId": "2fe0bcdbe5941e2cfdc54a7c09b54200",
"parameters": [
{
"name": "q",
"in": "query",
"description": "Query for tasks that match a specific string",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "filter[assignee]",
"in": "query",
"description": "Filter tasks by assignee",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
},
{
"name": "filter[relatedEntity]",
"in": "query",
"description": "Filter tasks by related entity",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "filter[dateMin]",
"in": "query",
"description": "Filter tasks created after this date. Date expected in the format YYYY-MM-DD",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "filter[dateMax]",
"in": "query",
"description": "Filter tasks created before this date. Date expected in the format YYYY-MM-DD",
"required": false,
"schema": {
"type": "string"
}
},
{
"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": "A list of tasks"
}
},
"security": [
{
"basicAuth": []
}
]
},
"post": {
"tags": [
"Tasks"
],
"summary": "Create a new task",
"operationId": "6558005d25c656d862228999ac70bcc2",
"requestBody": {
"description": "Task to create",
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"title": {
"description": "The title of the task",
"type": "string"
},
"description": {
"description": "The description of the task",
"type": "string"
},
"dueTime": {
"description": "The due time of the task. Formatted as a Unix timestamp",
"type": "string"
},
"recurrenceRule": {
"$ref": "#/components/schemas/RecurrenceRule"
},
"links": {
"description": "Entities that are related to the task",
"properties": {
"relatedEntity": {
"description": "The entity to attach the task to",
"type": "string",
"example": "3-contacts"
},
"assignee": {
"description": "The user to assign the task to",
"type": "string",
"example": "1-users"
}
},
"type": "object",
"example": "3-contacts"
}
},
"type": "object"
}
}
}
},
"responses": {
"200": {
"description": "A list of tasks"
}
},
"security": [
{
"basicAuth": []
}
]
}
},
"/territories": {
"get": {
"tags": [
"Territories"
],
"summary": "Get a list of territories",
"operationId": "cf95ba52f86fef3511b456449ca9f9a9",
"responses": {
"200": {
"description": "Successful response",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Territory"
}
}
}
}
}
},
"security": [
{
"basicAuth": []
}
]
}
},
"/users": {
"get": {
"tags": [
"Users"
],
"summary": "Get a list of users",
"operationId": "d3997a48c80629bf9a63637c4fde9aab",
"responses": {
"200": {
"description": "User",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UserResponse"
}
}
}
}
},
"security": [
{
"basicAuth": []
}
]
}
},
"/users/{id}": {
"get": {
"tags": [
"Users"
],
"summary": "Get a user",
"operationId": "69176b892afb5ae1c99520250d4bd331",
"parameters": [
{
"name": "id",
"in": "path",
"description": "User ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "User",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UserResponse"
}
}
}
}
},
"security": [
{
"basicAuth": []
}
]
}
}
},
"components": {
"schemas": {
"accountResponse": {
"description": "A full response object for an account-related endpoint.",
"properties": {
"meta": {
"$ref": "#/components/schemas/meta"
},
"accounts": {
"description": "An array of returned accounts.",
"type": "array",
"items": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Account"
},
{
"$ref": "#/components/schemas/HtmlLinkable"
},
{
"$ref": "#/components/schemas/Avatarable"
}
]
}
},
"creators": {
"description": "An array of creators for the accounts",
"type": "array",
"items": {
"$ref": "#/components/schemas/User"
}
},
"owners": {
"description": "An array of owners for the accounts",
"type": "array",
"items": {
"$ref": "#/components/schemas/User"
}
},
"origins": {
"description": "An array of origins for the accounts",
"type": "array",
"items": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Origin"
},
{
"$ref": "#/components/schemas/HtmlLinkable"
},
{
"$ref": "#/components/schemas/Avatarable"
}
]
}
},
"contacts": {
"description": "An array of contacts for the accounts",
"type": "array",
"items": {
"$ref": "#/components/schemas/Contact"
}
},
"accountTypes": {
"description": "An array of account types for the accounts",
"type": "array",
"items": {
"$ref": "#/components/schemas/AccountType"
}
},
"industries": {
"description": "An array of industries for the accounts",
"type": "array",
"items": {
"$ref": "#/components/schemas/Industry"
}
}
},
"type": "object"
},
"activityPostInput": {
"properties": {
"activities": {
"type": "array",
"items": {
"properties": {
"name": {
"description": "The name of the activity",
"type": "string",
"example": "Call with Andy Fowler"
},
"description": {
"description": "The agenda for the activity",
"type": "string",
"example": "Discuss the new feature set"
},
"note": {
"description": "An internal note about the activity",
"type": "string",
"example": "Andy was very excited about the new feature set"
},
"location": {
"description": "Where the activity will take place",
"type": "string",
"example": "Andy's office"
},
"activityType": {
"description": "See GET /activitytypes",
"type": "string",
"example": "1-activityTypes"
},
"startTime": {
"description": "Unix timestamp",
"type": "integer"
},
"endTime": {
"description": "Unix timestamp",
"type": "integer"
},
"transcription": {
"description": "The transcription of the activity",
"type": "string",
"example": "Speaker 1: Hello.\\n Speaker 2: Good morning!"
},
"isFlagged": {
"description": "Whether the activity is marked as important or not",
"type": "boolean",
"example": false
},
"isLogged": {
"description": "Whether the activity has occurred yet or not",
"type": "boolean",
"example": true
},
"isAllDay": {
"description": "Whether the activity is an all-day event",
"type": "boolean",
"example": false
},
"links": {
"description": "The entity IDs of activity participants",
"properties": {
"participants": {
"type": "array",
"items": {
"type": "string"
}
}
},
"type": "object"
}
},
"type": "object"
}
}
},
"type": "object"
},
"contactPostInput": {
"description": "The fields to be updated",
"properties": {
"contacts": {
"type": "array",
"items": {
"properties": {
"name": {
"description": "The new full name of the contact.",
"type": "string"
},
"description": {
"description": "The new description of the contact, which appears under their name.",
"type": "string"
},
"phones": {
"$ref": "#/components/schemas/phones"
},
"emails": {
"$ref": "#/components/schemas/emails"
},
"urls": {
"$ref": "#/components/schemas/urls"
},
"addresses": {
"$ref": "#/components/schemas/addresses"
},
"customFields": {
"description": "Custom fields to add to the Contact.",
"type": "object",
"example": {
"Favorite Number": "12"
},
"additionalProperties": {
"$ref": "#/components/schemas/CustomFieldInput"
}
},
"links": {
"description": "Enter API IDs to link to the contact.",
"properties": {
"accounts": {
"description": "Enter an array of API IDs for each account to associate with the contact. Including an empty array will clear all associated accounts.",
"type": "array",
"items": {
"type": "string"
}
},
"territory": {
"description": "Enter an API ID for the territory to associate with the contact.",
"type": "string"
},
"owner": {
"description": "Enter an API ID for the owner to associate with the contact.",
"type": "string"
},
"tags": {
"description": "Enter an array of API IDs for each tag to associate with the contact.",
"type": "array",
"items": {
"type": "string"
}
},
"emAudiences": {
"description": "Enter an array of API IDs ({id}-emAudiences) for each audience to associate with the contact.",
"type": "array",
"items": {
"type": "string"
}
}
},
"type": "object"
}
},
"type": "object"
}
}
},
"type": "object"
},
"FilterInput": {
"description": "The key-value pair for the filter, ex. filter[tags]=1-tags",
"type": "string"
},
"LeadInstallmentValue": {
"properties": {
"currency": {
"type": "string",
"example": "USD"
},
"amount": {
"type": "number",
"format": "float",
"example": 1000
}
},
"type": "object"
},
"LeadInstallment": {
"properties": {
"id": {
"type": "string",
"example": "1-installments"
},
"dueTime": {
"type": "string",
"example": "2026-01-01T00:00:00+0000"
},
"description": {
"type": "string",
"example": "Q1 payment"
},
"value": {
"$ref": "#/components/schemas/LeadInstallmentValue"
},
"failedTime": {
"type": "string",
"example": "2026-01-01T12:00:00+0000"
},
"isPaid": {
"type": "boolean",
"example": true
}
},
"type": "object"
},
"dueTime": {
"description": "When the lead is due.",
"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"
},
"notePostInput": {
"properties": {
"data": {
"properties": {
"body": {
"description": "The text to display on the note",
"example": "Hello World!"
},
"links": {
"description": "The entity to attach the note to",
"properties": {
"parent": {
"description": "The entity to attach the note to",
"type": "string",
"example": "3-contacts"
}
},
"type": "object",
"example": "3-contacts"
}
},
"type": "object"
}
},
"type": "object"
},
"productMapPatchInput": {
"type": "array",
"items": {
"properties": {
"op": {},
"path": {
"description": "The path to the value you want to update"
},
"value": {
"description": "The updated value"
}
},
"type": "object"
}
},
"patchInput": {
"type": "array",
"items": {
"properties": {
"op": {
"description": "The operation to perform",
"type": "string",
"enum": [
"add",
"remove",
"replace",
"move",
"copy"
],
"example": "add"
},
"path": {
"description": "The path to the attribute to patch. Can be used to update custom fields as well, such as using /leads/0/{customFieldName}",
"type": "string",
"example": "/leads/0/links/accounts/337-accounts"
},
"value": {
"description": "The value to set, can be various types, please refer to our guide on JSON Patch for more information",
"type": "string",
"example": "337-accounts"
}
},
"type": "object"
}
},
"commentLinkIds": {
"description": "Returns an array of all potential link configurations for the current object.\nSupported keys for each link config are:\n- string type\nThe `type` key of the top-level link configuration.\n- array groups\nWhich groups this link will be included in; 'base' for all.\n- array compoundGroups\nWhich groups will include the linked model(s) as compound documents by default.\n- string urlPrefix\nOverwrites the `href` link config value with i.e. \"https://app01.nutshell.com/rest/$urlPrefix\".\n- boolean isResourceObject\nIf `true`, no top-level link config will be included in the response for this\nlink. Every linked model will be render as a resource object of the form:\n{ id: \"ApiId\", type: \"ApiType\", href: \"ApiHref\" }",
"type": "array",
"items": {
"type": "string"
}
},
"Account": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Peep"
},
{
"$ref": "#/components/schemas/Avatarable"
},
{
"$ref": "#/components/schemas/HtmlLinkable"
},
{
"properties": {
"href": {
"type": "string"
},
"revenue": {
"properties": {
"amount": {
"type": "string",
"example": "8675309.00"
},
"formatted": {
"type": "string",
"example": "$8,675,309.00"
}
},
"type": "object"
},
"employeeCount": {
"type": "integer"
}
},
"type": "object"
}
]
},
"accountLinks": {
"properties": {
"accounts.creator": {
"properties": {
"href": {
"type": "string"
},
"type": {
"type": "string"
}
},
"type": "object"
},
"accounts.owner": {
"properties": {
"href": {
"type": "string"
},
"type": {
"type": "string"
}
},
"type": "object"
},
"accounts.territory": {
"properties": {
"href": {
"type": "string"
},
"type": {
"type": "string"
}
},
"type": "object"
},
"accounts.tags": {
"properties": {
"href": {
"type": "string"
},
"type": {
"type": "string"
}
},
"type": "object"
},
"accounts.origin": {
"properties": {
"href": {
"type": "string"
},
"type": {
"type": "string"
}
},
"type": "object"
},
"accounts.mergedWith": {
"properties": {
"href": {
"type": "string"
},
"type": {
"type": "string"
}
},
"type": "object"
},
"accounts.files": {
"properties": {
"href": {
"type": "string"
},
"type": {
"type": "string"
}
},
"type": "object"
},
"accounts.relatedFiles": {
"properties": {
"href": {
"type": "string"
},
"type": {
"type": "string"
}
},
"type": "object"
},
"accounts.followup": {
"properties": {
"href": {
"type": "string"
},
"type": {
"type": "string"
}
},
"type": "object"
},
"accounts.recurringTask": {
"properties": {
"href": {
"type": "string"
},
"type": {
"type": "string"
}
},
"type": "object"
},
"accounts.contacts": {
"properties": {
"href": {
"type": "string"
},
"type": {
"type": "string"
}
},
"type": "object"
},
"accounts.accountType": {
"properties": {
"href": {
"type": "string"
},
"type": {
"type": "string"
}
},
"type": "object"
},
"accounts.industry": {
"properties": {
"href": {
"type": "string"
},
"type": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
},
"AccountType": {
"properties": {
"id": {
"description": "The API ID of this entity, formatted {integer}-{entityType}",
"type": "string",
"example": "3-contacts"
},
"name": {
"type": "string"
},
"modifiedTime": {
"type": "integer",
"format": "int64"
}
},
"type": "object"
},
"ActivityResponse": {
"description": "A full response object for a activity-related endpoint",
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/HtmlLinkable"
},
{
"properties": {
"activities": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FullActivity"
}
},
"id": {
"description": "The API ID of this entity, formatted {integer}-{entityType}",
"type": "string",
"example": "3-contacts"
},
"agenda": {
"description": "The list of things to accomplish in the activity",
"example": "Sign a contract with Andy"
},
"createdTime": {
"type": "integer"
},
"endTime": {
"type": "integer"
},
"deletedTime": {
"type": "integer"
},
"href": {
"description": "The URL to fetch this contact.",
"type": "string",
"example": "https://app.nutshell.com/rest/contacts/3-contacts"
},
"isAllDay": {
"description": "Whether the activity is an all-day event",
"type": "boolean",
"example": "false"
},
"isEditable": {
"description": "Whether the activity can still be modified",
"type": "boolean",
"example": "true"
},
"isCancelled": {
"description": "Whether the activity occurred as planned or not",
"type": "boolean",
"example": "false"
},
"isFlagged": {
"description": "Whether the activity is marked as important or not",
"type": "boolean",
"example": "false"
},
"isLogged": {
"description": "Whether the activity has occurred yet or not",
"type": "boolean",
"example": "true"
},
"isOverdue": {
"description": "Whether the activity was supposed to be logged by now or not",
"type": "boolean",
"example": "false"
},
"loggedTime": {
"type": "integer"
},
"modifiedTime": {
"type": "integer"
},
"name": {
"description": "The name of the activity",
"type": "string",
"example": "Meeting with Andy"
},
"startTime": {
"type": "integer"
},
"isMediaLogged": {
"type": "boolean"
},
"transcription": {
"description": "The transcription on the activity",
"type": "string",
"example": "Speaker 1: Hello.\\n Speaker 2: Good morning!"
}
},
"type": "object"
}
]
},
"FullActivity": {
"description": "An individual activity with all fields",
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Activity"
},
{
"$ref": "#/components/schemas/HtmlLinkable"
},
{
"properties": {
"id": {
"description": "The API ID of this entity, formatted {integer}-{entityType}",
"type": "string",
"example": "3-contacts"
}
},
"type": "object"
}
]
},
"Activity": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/HtmlLinkable"
},
{
"properties": {
"id": {
"description": "The API ID of this entity, formatted {integer}-{entityType}",
"type": "string",
"example": "3-contacts"
}
},
"type": "object"
}
]
},
"ActivityTypeResponse": {
"description": "A full response object for an activity type-related endpoint.",
"properties": {
"meta": {
"$ref": "#/components/schemas/meta"
},
"activityTypes": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ActivityType"
}
}
},
"type": "object"
},
"ActivityType": {
"properties": {
"id": {
"description": "The API ID of this entity, formatted {integer}-{entityType}",
"type": "string",
"example": "3-contacts"
},
"name": {},
"modifiedTime": {
"type": "integer"
},
"isBenchmarkable": {
"type": "boolean"
}
},
"type": "object"
},
"EventResponse": {
"description": "A full response object for an event-related endpoint.",
"properties": {
"meta": {
"allOf": [
{
"$ref": "#/components/schemas/meta"
},
{
"properties": {
"previous": {
"description": "The URL to the previous page of results",
"type": "string"
}
},
"type": "object"
},
{
"properties": {
"next": {
"description": "The URL to the next page of results",
"type": "string"
}
},
"type": "object"
}
]
},
"events": {
"type": "array",
"items": {
"allOf": [
{
"$ref": "#/components/schemas/ChangeLogEntry"
},
{
"properties": {
"links": {
"$ref": "#/components/schemas/eventLinkIds"
}
},
"type": "object"
}
]
}
}
},
"type": "object"
},
"ChangeLogEntry": {
"properties": {
"id": {
"description": "The API ID of this entity, formatted {integer}-{entityType}",
"type": "string",
"example": "3-contacts"
},
"createdTime": {
"type": "integer"
},
"actorType": {
"description": "The type of entity that performed the action.",
"type": "string",
"example": "users"
},
"payloadType": {
"description": "The type of entity that was changed",
"type": "string",
"example": "contacts"
},
"action": {
"description": "What type of change took place",
"type": "string",
"example": "create"
},
"changes": {
"$ref": "#/components/schemas/changes"
},
"count": {
"type": "string"
}
},
"type": "object"
},
"eventLinkIds": {
"properties": {
"actor": {
"type": "string"
},
"payloads": {
"type": "array",
"items": {
"type": "string"
}
},
"comments": {
"$ref": "#/components/schemas/commentLinkIds"
}
},
"type": "object"
},
"changeLogChange": {
"properties": {
"id": {
"type": "string"
},
"type": {
"type": "string"
},
"name": {
"type": "string"
},
"position": {
"type": "integer"
}
},
"type": "object"
},
"changes": {
"description": "The changed values associated with the event",
"type": "array",
"items": {
"properties": {
"attribute": {
"description": "What value of the entity was changed",
"type": "string",
"example": "value"
},
"oldValue": {
"$ref": "#/components/schemas/changeLogChange"
},
"newValue": {
"$ref": "#/components/schemas/changeLogChange"
}
},
"type": "object"
}
},
"CompetitorResponse": {
"description": "A competitor response object",
"properties": {
"competitors": {},
"id": {
"description": "The API ID of this entity, formatted {integer}-{entityType}",
"type": "string",
"example": "3-contacts"
},
"name": {
"type": "string"
},
"modifiedTime": {
"type": "integer",
"format": "int64"
}
},
"type": "object"
},
"Competitor": {
"properties": {
"id": {
"description": "The API ID of this entity, formatted {integer}-{entityType}",
"type": "string",
"example": "3-contacts"
}
},
"type": "object"
},
"ContactResponse": {
"description": "A full response object for a contact-related endpoint.",
"properties": {
"links": {
"description": "Where to get related entities.",
"type": "object"
},
"contacts": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FullContact"
}
}
},
"type": "object"
},
"FullContact": {
"description": "An individual contact with all fields.",
"allOf": [
{
"$ref": "#/components/schemas/Contact"
},
{
"$ref": "#/components/schemas/HtmlLinkable"
},
{
"$ref": "#/components/schemas/Avatarable"
},
{
"properties": {
"links": {
"description": "The entity IDs of related entities.",
"type": "object"
}
},
"type": "object"
}
]
},
"Contact": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Peep"
},
{
"$ref": "#/components/schemas/Avatarable"
},
{
"$ref": "#/components/schemas/HtmlLinkable"
},
{
"properties": {
"jobTitle": {
"description": "The person's role at their company.",
"example": "CEO"
},
"firstName": {
"description": "The person's given name.",
"example": "Andy"
},
"lastName": {
"description": "The person's family name.",
"example": "Fowler"
},
"href": {
"description": "The URL to fetch this contact.",
"type": "string",
"example": "https://app.nutshell.com/rest/contacts/3-contacts"
}
},
"type": "object"
}
]
},
"contactLinkIds": {
"description": "A collection of IDs for entities associated with a contact. Use the paths in the 'links' object to retrieve the full entity.",
"properties": {
"accounts": {
"type": "array",
"items": {
"type": "string"
}
},
"creator": {
"type": "string"
},
"owner": {
"type": "string"
},
"territory": {
"type": "string"
},
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"origin": {
"type": "string"
},
"mergedWith": {
"type": "string"
},
"files": {
"type": "array",
"items": {
"type": "string"
}
},
"relatedFiles": {
"type": "array",
"items": {
"type": "string"
}
},
"followup": {
"type": "string"
},
"recurringTask": {
"type": "string"
}
},
"type": "object"
},
"contactLinks": {
"description": "A collection of paths for entities associated with a contact. Use the IDs in a contact's 'links' object to retrieve the full entity.",
"properties": {
"contacts.accounts": {
"properties": {
"href": {
"type": "string"
},
"type": {
"type": "string"
}
},
"type": "object"
},
"contacts.creator": {
"properties": {
"href": {
"type": "string"
},
"type": {
"type": "string"
}
},
"type": "object"
},
"contacts.owner": {
"properties": {
"href": {
"type": "string"
},
"type": {
"type": "string"
}
},
"type": "object"
},
"contacts.territory": {
"properties": {
"href": {
"type": "string"
},
"type": {
"type": "string"
}
},
"type": "object"
},
"contacts.tags": {
"properties": {
"href": {
"type": "string"
},
"type": {
"type": "string"
}
},
"type": "object"
},
"contacts.origin": {
"properties": {
"href": {
"type": "string"
},
"type": {
"type": "string"
}
},
"type": "object"
},
"contacts.mergedWith": {
"properties": {
"href": {
"type": "string"
},
"type": {
"type": "string"
}
},
"type": "object"
},
"contacts.files": {
"properties": {
"href": {
"type": "string"
},
"type": {
"type": "string"
}
},
"type": "object"
},
"contacts.relatedFiles": {
"properties": {
"href": {
"type": "string"
},
"type": {
"type": "string"
}
},
"type": "object"
},
"contacts.followup": {
"properties": {
"href": {
"type": "string"
},
"type": {
"type": "string"
}
},
"type": "object"
},
"contacts.recurringTask": {
"properties": {
"href": {
"type": "string"
},
"type": {
"type": "string"
}
},
"type": "object"
}
},
"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"
},
"FullCustomField": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/CustomField"
},
{
"properties": {
"value": {
"description": "Custom fields can be many different types, see the guide on Custom Fields for more info.",
"type": "string"
},
"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"
},
"Industry": {
"properties": {
"id": {
"description": "The API ID of this entity, formatted {integer}-{entityType}",
"type": "string",
"example": "3-contacts"
},
"name": {
"description": "The type of industry.",
"example": "Software"
},
"modifiedTime": {
"type": "integer"
}
},
"type": "object"
},
"LeadResponse": {
"description": "A full response object for a lead-related endpoint.",
"properties": {
"meta": {
"$ref": "#/components/schemas/meta"
},
"links": {
"type": "object"
},
"leads": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FullLead"
}
}
},
"type": "object"
},
"FullLead": {
"description": "A fully-fleshed lead.",
"allOf": [
{
"$ref": "#/components/schemas/Lead"
},
{
"$ref": "#/components/schemas/HtmlLinkable"
},
{
"$ref": "#/components/schemas/Avatarable"
}
]
},
"Lead": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/HtmlLinkable"
},
{
"$ref": "#/components/schemas/Avatarable"
},
{
"properties": {
"id": {
"description": "The API ID of this entity, formatted {integer}-{entityType}",
"type": "string",
"example": "3-contacts"
},
"deletedTime": {
"type": "string"
},
"name": {
"description": "The full name of the lead",
"type": "string",
"example": "John Doe"
},
"value": {
"$ref": "#/components/schemas/value"
},
"number": {
"type": "integer",
"format": "int64",
"example": "1234"
},
"description": {
"type": "string",
"example": "This is a description"
},
"createdTime": {
"$ref": "#/components/schemas/createdTime"
},
"closedTime": {
"type": "string"
},
"dueTime": {
"type": "string"
},
"anticipatedClosedTime": {
"type": "string"
},
"ownerType": {
"type": "string",
"example": "users"
},
"status": {
"description": "The current status of the lead",
"type": "string",
"example": "open"
},
"lastContactedTime": {
"description": "When the lead was last contacted.",
"format": "string"
},
"pieState": {
"type": "string"
},
"isOverdue": {
"description": "Whether the lead is overdue to have a final outcome set",
"type": "boolean",
"example": "false"
},
"overdueTime": {
"type": "string"
},
"href": {
"type": "string"
},
"confidence": {
"description": "How confident, as a percentage, that the lead will close",
"type": "integer",
"example": 25
},
"priority": {
"description": "Whether a lead is marked as hot (1) or not (0)",
"type": "integer",
"example": 0
},
"isCurrentUserWatching": {
"description": "Whether the current authenticated user is subscribed to receive notifications about this lead",
"type": "boolean"
}
},
"type": "object"
}
]
},
"value": {
"properties": {
"formatted": {
"description": "The value formatted as a string",
"type": "string",
"example": "$100.00"
},
"amount": {
"description": "The value as a number",
"type": "string",
"example": "100.00"
},
"currency": {
"description": "The currency code",
"type": "string",
"example": "USD"
}
},
"type": "object"
},
"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"
},
"LeadCompetitorMapResponse": {
"properties": {
"competitorMaps": {
"type": "array",
"items": {
"$ref": "#/components/schemas/LeadCompetitorMap"
}
},
"leads": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Lead"
}
},
"competitors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Competitor"
}
}
},
"type": "object"
},
"LeadCompetitorMap": {
"description": "A competitor relationship on a lead represents an entity that you may be competing with for this lead",
"properties": {
"id": {
"description": "The API ID of this entity, formatted {integer}-{entityType}",
"type": "string",
"example": "3-contacts"
},
"relationship": {
"type": "string"
},
"name": {
"description": "A shortcut to the name of the competitor",
"type": "string"
},
"status": {
"type": "string",
"enum": [
"potential",
"stole",
"beat",
null
]
},
"links": {
"properties": {
"lead": {
"type": "string"
},
"competitor": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
},
"LeadOutcome": {
"properties": {
"id": {
"description": "The API ID of this entity, formatted {integer}-{entityType}",
"type": "string",
"example": "3-contacts"
},
"name": {
"type": "string"
},
"status": {
"type": "string"
},
"type": {
"type": "string"
}
},
"type": "object"
},
"LeadProductMapResponse": {
"description": "A full response object for a lead product map.",
"properties": {
"meta": {
"$ref": "#/components/schemas/meta"
},
"productMaps": {
"type": "array",
"items": {
"$ref": "#/components/schemas/LeadProductMap"
}
}
},
"type": "object"
},
"LeadProductMap": {
"properties": {
"id": {
"description": "The API ID of this entity, formatted {integer}-{entityType}",
"type": "string",
"example": "3-contacts"
},
"relationship": {},
"price": {
"$ref": "#/components/schemas/value"
},
"name": {},
"unit": {},
"quantity": {
"type": "number",
"format": "float"
},
"productType": {
"type": "string",
"example": "product"
},
"links": {
"properties": {
"product": {
"description": "The product this map is for",
"type": "string",
"example": "1-products"
}
},
"type": "object"
}
},
"type": "object"
},
"ListItem": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/HtmlLinkable"
},
{
"$ref": "#/components/schemas/Avatarable"
},
{
"properties": {
"id": {
"description": "The API ID of this entity, formatted {integer}-{entityType}",
"type": "string",
"example": "3-contacts"
},
"primaryName": {
"type": "string"
},
"primaryInfo": {
"type": "string"
},
"relatedName": {
"type": "string"
},
"relatedInfo": {
"type": "string"
},
"relatedType": {
"type": "string"
},
"relatedUrl": {
"type": "string"
},
"relatedUrlPath": {
"type": "string"
},
"primaryContact": {
"type": "string"
},
"primaryAccount": {
"type": "string"
},
"latlon": {
"type": "string"
},
"mapUrl": {
"type": "string"
},
"isDeleted": {
"type": "boolean"
},
"fields": {
"description": "Various additional fields for the list item. View the example response for more details.",
"type": "array",
"items": {
"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 combined with AND/OR logic (allows 'any' vs 'all' selection)",
"type": "boolean",
"example": false
},
"isNullable": {
"description": "Whether the property can have a null/empty value",
"type": "boolean",
"example": true
},
"relationships": {
"description": "For relationship-type properties, array of related entity types (e.g., ['users', 'teams'])",
"type": "array",
"items": {
"type": "string"
},
"example": [
"users",
"teams"
]
},
"enum": {
"description": "For enum-type properties, array of possible values",
"type": "array",
"items": {
"type": "string"
},
"example": [
"Option1",
"Option2"
]
},
"format": {
"description": "Value format specification (e.g., 'uri', 'relative' for date-time)",
"type": "string",
"example": "uri"
}
},
"type": "object"
}
},
"type": "object"
}
},
"type": "object"
},
"creator": {
"properties": {
"value": {
"properties": {
"id": {
"type": "string"
},
"type": {
"type": "string"
},
"name": {
"type": "string"
},
"avatarUrl": {
"type": "string"
},
"initials": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
},
"origin": {
"properties": {
"value": {
"properties": {
"id": {
"type": "string"
},
"type": {
"type": "string"
},
"name": {
"type": "string"
},
"avatarUrl": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
},
"tags": {
"properties": {
"value": {
"type": "array",
"items": {
"type": "string"
}
}
},
"type": "object"
},
"emailOpenCount": {
"properties": {
"value": {
"type": "string"
}
},
"type": "object"
},
"emailClickCount": {
"properties": {
"value": {
"type": "string"
}
},
"type": "object"
},
"emailOpenRate": {
"properties": {
"value": {
"type": "string"
}
},
"type": "object"
},
"emailClickRate": {
"properties": {
"value": {
"type": "string"
}
},
"type": "object"
},
"openedEmailSequenceTemplates": {
"properties": {
"value": {
"type": "array",
"items": {
"type": "string"
}
}
},
"type": "object"
},
"clickedEmailSequenceTemplates": {
"properties": {
"value": {
"type": "array",
"items": {
"type": "string"
}
}
},
"type": "object"
},
"ctctNumberOfEmailsSent": {
"properties": {
"value": {
"type": "string"
}
},
"type": "object"
},
"ctctBounceRate": {
"properties": {
"value": {
"type": "string"
}
},
"type": "object"
},
"ctctClickRate": {
"properties": {
"value": {
"type": "string"
}
},
"type": "object"
},
"ctctOpenRate": {
"properties": {
"value": {
"type": "string"
}
},
"type": "object"
},
"ctctEngagementRating": {
"properties": {
"value": {
"type": "string"
}
},
"type": "object"
},
"ctctLists": {
"properties": {
"value": {
"type": "array",
"items": {
"type": "string"
}
}
},
"type": "object"
},
"ctctStatus": {
"properties": {
"value": {
"properties": {
"value": {
"type": "string"
},
"description": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
},
"ctctLastOpenTime": {
"properties": {
"value": {
"type": "string"
}
},
"type": "object"
},
"ctctLastClickTime": {
"properties": {
"value": {
"type": "string"
}
},
"type": "object"
},
"ctctEmailAddress": {
"properties": {
"value": {
"type": "string"
}
},
"type": "object"
},
"lastContactedTime": {
"properties": {
"value": {
"type": "string"
}
},
"type": "object"
},
"url": {
"properties": {
"value": {
"properties": {
"value": {
"type": "string"
},
"url": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
},
"ListItemAccount": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/ListItem"
},
{
"properties": {
"description": {
"type": "string"
}
},
"type": "object"
}
]
},
"ListItemContact": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/ListItem"
},
{
"properties": {
"description": {
"type": "string"
}
},
"type": "object"
}
]
},
"ListItemLead": {
"description": "Class ListItemLead",
"allOf": [
{
"$ref": "#/components/schemas/ListItem"
}
]
},
"Market": {
"properties": {
"id": {
"description": "The API ID of this entity, formatted {integer}-{entityType}",
"type": "string",
"example": "3-contacts"
},
"name": {
"type": "string"
},
"currency": {
"type": "string"
},
"currencySymbol": {
"type": "string"
},
"isDefault": {
"type": "boolean"
}
},
"type": "object"
},
"Note": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/HtmlLinkable"
},
{
"properties": {
"id": {
"description": "The API ID of this entity, formatted {integer}-{entityType}",
"type": "string",
"example": "3-contacts"
},
"createdTime": {
"type": "string"
},
"deletedTime": {
"type": "string"
},
"href": {
"type": "string"
},
"body": {
"type": "string"
},
"bodyHtml": {
"type": "string"
},
"bodyMarkup": {
"type": "string"
},
"isEditable": {
"type": "boolean"
},
"parentType": {
"type": "string"
}
},
"type": "object"
}
]
},
"NutReportOnDemandReport": {
"properties": {
"id": {
"description": "The API ID of this entity, formatted {integer}-{entityType}",
"type": "string",
"example": "3-contacts"
},
"key": {
"type": "string"
},
"data": {
"type": "array",
"items": {
"properties": {
"bucket": {
"$ref": "#/components/schemas/ReportBucket"
}
},
"type": "object"
}
},
"name": {
"type": "string"
},
"prefix": {
"type": "string"
},
"summary": {
"$ref": "#/components/schemas/ReportBucket"
}
},
"type": "object"
},
"ReportCount": {
"description": "Count of the report",
"properties": {
"formatted": {
"description": "The formatted value after applying the prefix and suffix",
"type": "string"
},
"prefix": {
"description": "The prefix to apply to the value",
"type": "string",
"example": "$"
},
"suffix": {
"description": "The suffix to apply to the value",
"type": "string"
},
"value": {
"description": "The raw value to be formatted",
"type": "number",
"example": 100
}
},
"type": "object"
},
"ReportBucket": {
"description": "Bucket of the report",
"properties": {
"bucket": {
"description": "The name of the bucket",
"type": "string",
"example": "best bucket"
},
"count": {
"$ref": "#/components/schemas/ReportCount"
},
"total": {
"$ref": "#/components/schemas/ReportCount"
},
"bucketType": {
"type": "string"
},
"bucketSubtype": {
"type": "string"
},
"filters": {
"description": "The filters applied to the report",
"type": "array",
"items": {
"type": "string"
}
},
"segments": {
"type": "array",
"items": {
"type": "string"
}
}
},
"type": "object"
},
"Origin": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Avatarable"
},
{
"$ref": "#/components/schemas/HtmlLinkable"
},
{
"properties": {
"id": {
"description": "The API ID of this entity, formatted {integer}-{entityType}",
"type": "string",
"example": "3-contacts"
},
"name": {
"type": "string"
},
"modifiedTime": {
"type": "integer",
"format": "int64"
},
"lastseenTime": {
"type": "integer",
"format": "int64"
},
"originType": {
"type": "string"
}
},
"type": "object"
}
]
},
"Peep": {
"properties": {
"id": {
"description": "The API ID of this entity, formatted {integer}-{entityType}",
"type": "string",
"example": "3-contacts"
},
"name": {
"description": "The entity's full name.",
"type": "string",
"example": "Andy Nutshell"
},
"description": {
"description": "A brief explanation of this entity which appears under their name.",
"type": "string",
"example": "CEO / cofounder @ Nutshell. Building growth software, wrangling beagles 🐶"
},
"createdTime": {
"description": "Unix timestamp",
"type": "integer",
"format": "int64"
},
"deletedTime": {
"description": "Unix timestamp",
"type": "integer",
"format": "int64"
},
"emails": {
"$ref": "#/components/schemas/emails"
},
"addresses": {
"$ref": "#/components/schemas/addresses"
},
"phones": {
"$ref": "#/components/schemas/phones"
},
"urls": {
"$ref": "#/components/schemas/urls"
}
},
"type": "object"
},
"emails": {
"description": "All email addresses associated with an entity.",
"type": "array",
"items": {
"properties": {
"isPrimary": {
"description": "If entity has multiple email addresses, which should be used as the primary point of contact.",
"type": "boolean",
"example": true
},
"name": {
"description": "A label for the email address, e.g. 'work', 'personal', 'support'.",
"type": "string",
"example": "personal"
},
"value": {
"description": "The email address itself.",
"type": "string",
"example": "andy@nutshell.com"
}
},
"type": "object"
}
},
"addresses": {
"description": "All addresses associated with an entity.",
"type": "array",
"items": {
"properties": {
"isPrimary": {
"description": "Should this address be used if there are multiple",
"type": "boolean",
"example": true
},
"name": {
"description": "A label for the address, e.g. 'work', 'home', 'shipping'.",
"type": "string",
"example": "address"
},
"value": {
"description": "The geographic coordinates for the address.",
"properties": {
"location": {
"properties": {
"longitude": {
"type": "number",
"example": -83.732124
},
"latitude": {
"type": "number",
"example": 42.279594
}
},
"type": "object"
}
},
"type": "object"
},
"locationAccuracy": {
"description": "How specific the address is. 8 is an exact street address, 1 is only a country.",
"type": "string",
"example": "8"
},
"address_1": {
"description": "Primary street address",
"type": "string",
"example": "206 E Huron St"
},
"address_2": {
"description": "Secondary street address, such as a suite or apartment number",
"type": "string",
"example": "Suite 200"
},
"address_3": {
"type": "string"
},
"city": {
"description": "City or town",
"type": "string",
"example": "Ann Arbor"
},
"state": {
"description": "State or province",
"type": "string",
"example": "MI"
},
"postalCode": {
"description": "ZIP or postal code",
"type": "string",
"example": "48103"
},
"country": {
"description": "Country code",
"type": "string",
"example": "US"
},
"timezone": {
"type": "string"
}
},
"type": "object"
}
},
"phones": {
"type": "array",
"items": {
"properties": {
"isOptedOut": {
"description": "If this number has opted out of receiving SMS messages",
"type": "boolean",
"example": true
},
"isPrimary": {
"description": "Should this phone number be used if there are multiple",
"type": "boolean",
"example": true
},
"name": {
"description": "A label for the phone number, e.g. 'work', 'home', 'mobile'.",
"type": "string",
"example": "phone"
},
"value": {
"properties": {
"countryCode": {
"description": "Phone number prefix for calling individuals in other countries",
"type": "string",
"example": "1"
},
"number": {
"description": "The unformatted phone number with only digits",
"type": "string",
"example": "7341234567"
},
"extension": {
"description": "An additional code to reach a specific person or department which share a number",
"type": "string",
"example": "123"
},
"numberFormatted": {
"description": "The phone number formatted for human readability",
"type": "string",
"example": "734-123-4567"
},
"E164": {
"description": "The phone number formatted for international use; a common programatic standard for working with phone numbers",
"type": "string",
"example": "+17341234567"
},
"countryCodeAndNumber": {
"description": "The phone number formatted for human readability with the country code",
"type": "string",
"example": "+1 734-123-4567"
}
},
"type": "object"
}
},
"type": "object"
}
},
"urls": {
"type": "array",
"items": {
"properties": {
"isPrimary": {
"description": "Should this URL be used if there are multiple",
"type": "boolean",
"example": true
},
"name": {
"description": "A label for the URL, e.g. 'LinkedIn', 'Facebook', 'personal website'.",
"type": "string",
"example": "LinkedIn"
},
"value": {
"description": "The URL itself",
"type": "string",
"example": "https://www.linkedin.com"
}
},
"type": "object"
}
},
"ProductResponse": {
"description": "A full response object for a product-related endpoint.",
"properties": {
"products": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Product"
}
}
},
"type": "object"
},
"Product": {
"properties": {
"id": {
"description": "The API ID of this entity, formatted {integer}-{entityType}",
"type": "string",
"example": "3-contacts"
},
"name": {},
"href": {},
"description": {},
"modifiedTime": {
"type": "integer"
},
"deletedTime": {
"type": "string",
"format": "date-time"
},
"sku": {},
"productType": {},
"prices": {
"properties": {
"1-markets": {
"$ref": "#/components/schemas/productPrice"
}
},
"type": "object"
},
"price": {
"$ref": "#/components/schemas/productPrice"
}
},
"type": "object"
},
"productPrice": {
"properties": {
"amount": {
"type": "number"
},
"currency": {
"type": "string"
},
"formatted": {
"type": "string"
},
"currencySymbol": {
"type": "string"
}
},
"type": "object"
},
"ProductCategoryResponse": {
"description": "A full response object for a product category-related endpoint.",
"properties": {
"productCategories": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ProductCategory"
}
}
},
"type": "object"
},
"ProductCategory": {
"properties": {
"id": {
"description": "The API ID of this entity, formatted {integer}-{entityType}",
"type": "string",
"example": "3-contacts"
},
"name": {},
"modifiedTime": {
"type": "integer"
},
"href": {}
},
"type": "object"
},
"Source": {
"properties": {
"id": {
"description": "The API ID of this entity, formatted {integer}-{entityType}",
"type": "string",
"example": "3-contacts"
},
"name": {
"example": "Google"
},
"href": {
"type": "string"
},
"modifiedTime": {
"description": "Unix Timestamp",
"type": "integer",
"format": "int64",
"example": 1704774720
},
"channel": {
"description": "Channels group sources into broader groups.",
"properties": {
"value": {
"type": "integer",
"example": 1
},
"display": {
"type": "string",
"example": "Organic search"
}
},
"type": "object"
},
"deletedTime": {
"description": "Unix Timestamp",
"type": "integer",
"format": "int64",
"example": 1704774720
}
},
"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"
},
"Stageset": {
"properties": {
"id": {
"description": "The API ID of this entity, formatted {integer}-{entityType}",
"type": "string",
"example": "3-contacts"
},
"name": {
"description": "The name of the pipeline",
"example": "Preimum Prospects Pipeline"
},
"default": {
"description": "Whether this is the default pipeline for new leads.",
"type": "boolean",
"example": true
},
"canAccess": {
"description": "Whether the user can access the stageset based on the current Nutshell plan.",
"type": "boolean",
"example": true
},
"status": {
"description": "The status of the stageset. '1' for active, '2' for draft, '3' for retired",
"type": "integer",
"enum": [
"1",
"2",
"3"
]
}
},
"type": "object"
},
"Tag": {
"properties": {
"id": {
"description": "The API ID of this entity, formatted {integer}-{entityType}",
"type": "string",
"example": "3-contacts"
},
"name": {
"type": "string",
"example": "Enterprise"
},
"href": {
"type": "string",
"example": "https://app.nutshell.com/rest/tags/1-tags"
},
"modifiedTime": {
"description": "Unix timestamp",
"type": "integer",
"format": "int32",
"example": 31536000
},
"deletedTime": {
"description": "Unix timestamp",
"type": "integer",
"format": "int32",
"example": 31536000
},
"tagType": {
"description": "The type of entity the tag corresponds to",
"type": "string",
"example": "leads"
},
"count": {
"description": "The number of entities with this tag",
"type": "integer",
"format": "int32",
"example": "1"
},
"colorType": {
"description": "The color or the tag, returned as a string",
"type": "string",
"example": "COLOR_ORANGE"
}
},
"type": "object"
},
"Task": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/HtmlLinkable"
},
{
"properties": {
"id": {
"description": "The API ID of this entity, formatted {integer}-{entityType}",
"type": "string",
"example": "3-contacts"
},
"recurrenceRule": {
"oneOf": [
{
"$ref": "#/components/schemas/RecurrenceRule"
}
],
"nullable": true
}
},
"type": "object"
}
]
},
"RecurrenceRule": {
"description": "An RRULE-based recurrence pattern for a task.",
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/HtmlLinkable"
},
{
"properties": {
"rule": {
"description": "An RRULE-compatible string defining the recurrence pattern. See https://datatracker.ietf.org/doc/html/rfc5545#section-3.3.10 and https://icalendar.org/iCalendar-RFC-5545/3-3-10-recurrence-rule.html",
"type": "string",
"example": "FREQ=WEEKLY;BYDAY=MO"
},
"mode": {
"description": "How the next due date is calculated. 'dueDate' follows the recurrence sequence regardless of completion; 'completion' schedules the next task relative to when the prior one was completed.",
"type": "string",
"enum": [
"dueDate",
"completion"
],
"example": "dueDate"
},
"id": {
"description": "The API ID of this entity, formatted {integer}-{entityType}",
"type": "string",
"example": "3-contacts"
}
},
"type": "object"
}
]
},
"Territory": {
"properties": {
"id": {
"description": "The API ID of this entity, formatted {integer}-{entityType}",
"type": "string",
"example": "3-contacts"
},
"name": {
"type": "string"
},
"href": {
"type": "string"
},
"modifiedTime": {
"type": "number"
}
},
"type": "object"
},
"UserResponse": {
"description": "A full response object for a user-related endpoint.",
"properties": {
"meta": {
"allOf": [
{
"$ref": "#/components/schemas/meta"
},
{
"properties": {
"next": {
"description": "The URL to the next page of results",
"type": "string"
},
"previous": {
"description": "The URL to the previous page of results",
"type": "string"
},
"total": {
"type": "integer"
}
},
"type": "object"
}
]
},
"users": {
"type": "array",
"items": {
"allOf": [
{
"$ref": "#/components/schemas/User"
},
{
"$ref": "#/components/schemas/Avatarable"
}
]
}
}
},
"type": "object"
},
"User": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Avatarable"
},
{
"properties": {
"id": {
"description": "The API ID of this entity, formatted {integer}-{entityType}",
"type": "string",
"example": "3-contacts"
},
"name": {},
"firstName": {},
"modifiedTime": {
"type": "integer"
},
"isEnabled": {
"type": "boolean"
},
"hasSetPassword": {
"type": "boolean"
},
"isAdministrator": {
"type": "boolean"
},
"isViewingRestricted": {
"type": "boolean"
},
"isHiddenFromFilters": {
"type": "boolean"
},
"canAccessEmailMarketing": {
"type": "boolean"
},
"permissions": {
"$ref": "#/components/schemas/permissions"
},
"emails": {
"type": "array",
"items": {
"type": "string"
}
},
"phonecallerType": {}
},
"type": "object"
}
]
},
"permissions": {
"properties": {
"canAccessSetup": {
"type": "boolean"
},
"canAccessMarketing": {
"type": "boolean"
},
"canBulkEdit": {
"type": "boolean"
},
"canExport": {
"type": "boolean"
},
"canViewSharedEmails": {
"type": "boolean"
},
"canImport": {
"type": "boolean"
},
"canMergeEntities": {
"type": "boolean"
},
"canDeleteEntities": {
"type": "boolean"
},
"canAssignEntities": {
"type": "boolean"
},
"canAccessBilling": {
"type": "boolean"
},
"canManageEmailTemplates": {
"type": "boolean"
},
"canAccessCrm": {
"type": "boolean"
},
"canAccessFullCampaigns": {
"type": "boolean"
},
"canUsePeopleIQ": {
"type": "boolean"
},
"canUseInbox": {
"type": "boolean"
}
},
"type": "object"
},
"Audience": {
"properties": {
"id": {
"description": "The API ID of this entity, formatted {integer}-{entityType}",
"type": "string",
"example": "3-contacts"
},
"name": {
"type": "string"
},
"isWebFX": {
"description": "Whether the audience is a WebFX audience",
"type": "boolean"
}
},
"type": "object"
},
"Edition": {
"properties": {
"id": {
"description": "The API ID of this entity, formatted {integer}-{entityType}",
"type": "string",
"example": "3-contacts"
},
"name": {
"type": "string"
}
},
"type": "object"
},
"Invoice": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/SalesDocument"
},
{
"properties": {
"number": {
"description": "The invoice number",
"type": "string",
"example": "1000-01"
},
"total": {
"$ref": "#/components/schemas/value"
},
"validThroughTime": {
"description": "The date and time when the invoice expires or is due",
"type": "string",
"example": "2024-12-31T23:59:59Z"
},
"createdTime": {
"description": "The date and time when the invoice was created",
"type": "string",
"example": "2024-01-15T10:30:00Z"
},
"publishedTime": {
"description": "The date and time when the invoice was published",
"type": "string",
"example": "2024-01-16T14:20:00Z"
},
"sentTime": {
"description": "The date and time when the invoice was sent to the customer",
"type": "string",
"example": "2024-01-17T09:15:00Z"
},
"paidTime": {
"description": "The date and time when the invoice was paid by the customer",
"type": "string",
"example": "2024-01-20T16:45:00Z"
},
"completionComment": {
"description": "Payment or completion note when the invoice was marked paid or revoked",
"type": "string",
"example": "Paid via ACH",
"nullable": true
},
"deletedTime": {
"description": "The date and time when the invoice was deleted",
"type": "string",
"example": "2024-02-01T12:00:00Z"
}
},
"type": "object"
}
]
},
"Quote": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/SalesDocument"
},
{
"properties": {
"number": {
"description": "The quote number",
"type": "string",
"example": "1000-01"
},
"total": {
"$ref": "#/components/schemas/value"
},
"validThroughTime": {
"description": "The date and time when the quote expires or is no longer valid",
"type": "string",
"example": "2024-12-31T23:59:59Z"
},
"createdTime": {
"description": "The date and time when the quote was created",
"type": "string",
"example": "2024-01-15T10:30:00Z"
},
"publishedTime": {
"description": "The date and time when the quote was published",
"type": "string",
"example": "2024-01-16T14:20:00Z"
},
"sentTime": {
"description": "The date and time when the quote was sent to the customer",
"type": "string",
"example": "2024-01-17T09:15:00Z"
},
"acceptedTime": {
"description": "The date and time when the quote was accepted by the customer",
"type": "string",
"example": "2024-01-20T16:45:00Z"
},
"deletedTime": {
"description": "The date and time when the quote was deleted",
"type": "string",
"example": "2024-02-01T12:00:00Z"
}
},
"type": "object"
}
]
},
"SalesDocumentProductLineItem": {
"title": "Product line item",
"properties": {
"id": {
"description": "The line item ID",
"type": "string",
"example": "1-quoteProductLineItems"
},
"position": {
"description": "Sort order of the line item on the document",
"type": "integer",
"example": 0
},
"product": {
"description": "The product ID this line item references, if any",
"type": "string",
"example": "100-products",
"nullable": true
},
"name": {
"description": "Display name of the line item",
"type": "string",
"example": "Consulting Services"
},
"description": {
"description": "Description of the line item",
"type": "string",
"example": "Monthly consulting retainer"
},
"sku": {
"description": "SKU of the line item",
"type": "string",
"example": "CONS-001"
},
"quantity": {
"description": "Quantity of the line item",
"type": "number",
"format": "float",
"example": 2
},
"term": {
"description": "Billing period unit for the line item, if any (minute, hour, day, week, month, quarter, or year)",
"type": "string",
"example": "month",
"nullable": true
},
"price": {
"$ref": "#/components/schemas/value"
},
"total": {
"$ref": "#/components/schemas/value"
},
"discountUnit": {
"description": "Discount unit: '$' for a fixed amount, or '%' for a percentage",
"type": "string",
"example": "%",
"nullable": true
},
"discountNumber": {
"description": "Discount amount or percentage, depending on discountUnit",
"type": "number",
"format": "float",
"example": 10,
"nullable": true
}
},
"type": "object"
},
"SalesDocumentSubtotalLineItem": {
"title": "Subtotal line item",
"properties": {
"id": {
"description": "The subtotal line item ID",
"type": "string",
"example": "1-quoteSubtotalLineItems"
},
"position": {
"description": "Sort order of the adjustment on the document",
"type": "integer",
"example": 0
},
"label": {
"description": "Display label for the adjustment",
"type": "string",
"example": "Tax"
},
"modifierUnit": {
"description": "Modifier unit: '$' for a fixed amount, or '%' for a percentage",
"type": "string",
"example": "%"
},
"modifierValue": {
"description": "Modifier amount or percentage, depending on modifierUnit",
"type": "number",
"format": "float",
"example": 6.5
},
"operation": {
"description": "Whether the modifier is added (+) or subtracted (-)",
"type": "string",
"enum": [
"+",
"-"
],
"example": "+"
},
"total": {
"$ref": "#/components/schemas/value"
}
},
"type": "object"
},
"SalesDocumentRecipient": {
"description": "The contact or company selected as the document recipient",
"properties": {
"id": {
"description": "The recipient entity ID; entity type is encoded in the API id suffix (e.g. contacts or accounts)",
"type": "string",
"example": "321-contacts"
},
"name": {
"description": "Display name of the recipient",
"type": "string",
"example": "Jane Doe"
},
"email": {
"description": "Email address used for the recipient on this document",
"type": "string",
"example": "jane@example.com",
"nullable": true
}
},
"type": "object",
"nullable": true
},
"salesDocumentProductLineItems": {
"description": "The products and services included in the sales document.",
"type": "array",
"items": {
"allOf": [
{
"$ref": "#/components/schemas/SalesDocumentProductLineItem"
}
]
}
},
"salesDocumentSubtotalLineItems": {
"description": "Adjustments applied after the product subtotal, such as tax, shipping, or discounts.",
"type": "array",
"items": {
"allOf": [
{
"$ref": "#/components/schemas/SalesDocumentSubtotalLineItem"
}
]
}
},
"SalesDocument": {
"properties": {
"id": {
"description": "The API ID of this entity, formatted {integer}-{entityType}",
"type": "string",
"example": "3-contacts"
},
"displayStatus": {
"description": "The current status of the sales document. For invoices, ACCEPTED means paid.",
"type": "string",
"enum": [
"DRAFT",
"READY",
"SENT",
"REVOKED",
"ACCEPTED",
"ARCHIVED",
"EXPIRED"
],
"example": "SENT"
},
"productLineItems": {
"$ref": "#/components/schemas/salesDocumentProductLineItems"
},
"subtotalLineItems": {
"$ref": "#/components/schemas/salesDocumentSubtotalLineItems"
},
"recipient": {
"$ref": "#/components/schemas/SalesDocumentRecipient"
},
"acceptedName": {
"description": "Name recorded when the document was accepted or marked paid",
"type": "string",
"example": "Jane Customer",
"nullable": true
},
"acceptedEmail": {
"description": "Email recorded when the document was accepted or marked paid",
"type": "string",
"example": "jane@example.com",
"nullable": true
}
},
"type": "object"
},
"Field": {
"properties": {
"id": {
"description": "The API ID of this entity, formatted {integer}-{entityType}",
"type": "string",
"example": "3-contacts"
},
"label": {
"type": "string",
"example": "Full Name"
},
"fieldName": {
"type": "string",
"example": "name"
},
"fieldType": {
"type": "string",
"example": "textfield"
},
"entityName": {
"type": "string",
"example": "Contacts"
}
},
"type": "object"
},
"FormResponse": {
"description": "A full response object for a form-related endpoint.",
"properties": {
"meta": {
"$ref": "#/components/schemas/meta"
},
"links": {
"type": "object"
},
"wfForms": {
"type": "array",
"items": {
"allOf": [
{
"$ref": "#/components/schemas/Form"
},
{
"$ref": "#/components/schemas/FormLinks"
}
]
}
}
},
"type": "object"
},
"FormLinks": {
"properties": {
"links": {
"description": "The IDs of the fields in the form",
"properties": {
"fields": {
"type": "array",
"items": {
"type": "string",
"example": "1-wfFields"
}
}
},
"type": "object"
}
},
"type": "object"
},
"Form": {
"properties": {
"id": {
"description": "The API ID of this entity, formatted {integer}-{entityType}",
"type": "string",
"example": "3-contacts"
},
"name": {
"description": "The name of the form",
"type": "string",
"example": "Client Questionnaire"
},
"href": {
"type": "string"
},
"createdTime": {
"type": "string"
}
},
"type": "object"
},
"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"
},
"HtmlLinkable": {
"description": "Adds an htmlUrl string attribute that represents a URL of an HTML representation of the\nresponse model.",
"properties": {
"htmlUrl": {
"description": "The link to the entity within the app.",
"type": "string",
"example": "https://app.nutshell.com/lead/1006"
},
"htmlUrlPath": {
"description": "The path to the entity within the app.",
"type": "string",
"example": "/lead/1006"
}
},
"type": "object"
},
"meta": {
"description": "Information about the Nutshell instance making the request",
"properties": {
"instanceId": {
"description": "The Nutshell instance ID",
"type": "string",
"example": "12345"
},
"siteId": {
"description": "Site ID for WebFX customers",
"type": "string"
}
},
"type": "object"
}
},
"securitySchemes": {
"basicAuth": {
"type": "http",
"scheme": "basic"
}
}
},
"tags": [
{
"name": "Accounts (Companies)",
"description": "Accounts (Companies)"
},
{
"name": "Activities",
"description": "Activities"
},
{
"name": "Audiences",
"description": "Audiences"
},
{
"name": "Competitors",
"description": "Competitors"
},
{
"name": "Leads",
"description": "Leads"
},
{
"name": "Contacts (People)",
"description": "Contacts (People)"
},
{
"name": "Editions",
"description": "Editions"
},
{
"name": "Emails",
"description": "Emails"
},
{
"name": "Events (Timeline)",
"description": "Events (Timeline)"
},
{
"name": "Filter",
"description": "Filter"
},
{
"name": "Forms",
"description": "Forms"
},
{
"name": "Industries",
"description": "Industries"
},
{
"name": "Invoices",
"description": "Invoices"
},
{
"name": "Markets",
"description": "Markets"
},
{
"name": "Notes",
"description": "Notes"
},
{
"name": "Products",
"description": "Products"
},
{
"name": "ProductCategories",
"description": "ProductCategories"
},
{
"name": "Quotes",
"description": "Quotes"
},
{
"name": "Sources",
"description": "Sources"
},
{
"name": "Stagesets (Pipelines)",
"description": "Stagesets (Pipelines)"
},
{
"name": "Tags",
"description": "Tags"
},
{
"name": "Tasks",
"description": "Tasks"
},
{
"name": "Territories",
"description": "Territories"
},
{
"name": "Users",
"description": "Users"
}
]
}