> ## 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.

# Update the status of a lead.

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.

# 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/{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": []
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "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"
    }
  ]
}
```