> ## Documentation Index
> Fetch the complete documentation index at: https://developers.nutshell.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a lead

Create a new lead. Only one lead can be created at a time.

# OpenAPI definition

```json
{
  "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": {
    "/leads": {
      "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": []
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "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"
      },
      "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"
      },
      "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"
      },
      "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": "integer"
          },
          "productType": {
            "type": "string",
            "example": "product"
          },
          "links": {
            "properties": {
              "product": {
                "description": "The product this map is for",
                "type": "string",
                "example": "1-products"
              }
            },
            "type": "object"
          }
        },
        "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"
      }
    },
    "securitySchemes": {
      "basicAuth": {
        "type": "http",
        "scheme": "basic"
      }
    }
  },
  "tags": [
    {
      "name": "Leads",
      "description": "Leads"
    }
  ]
}
```