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

# Update Lead Status

> Update the status of a lead

Manually update a lead's status. This is useful for marking leads as opportunities or not interested based on external information. You can update either the campaign status, custom lead status, or both in a single request.

## Request

<ParamField header="X-API-Key" type="string" required>
  Your API key
</ParamField>

<ParamField path="id" type="string" required>
  The lead ID
</ParamField>

<ParamField body="status" type="string">
  The campaign status for the lead. Options:

  * `MEETING_BOOKED` - Mark as meeting booked
  * `OPPORTUNITY` - Mark as a sales opportunity
  * `NOT_INTERESTED` - Mark as not interested
  * `DONE` - Mark as completed
</ParamField>

<ParamField body="customLeadStatus" type="string">
  The custom lead status for CRM categorization. Options:

  * `LEAD` - New lead (default)
  * `INTERESTED` - Lead has shown interest
  * `MEETING_BOOKED` - Meeting has been scheduled
  * `MEETING_COMPLETE_NOT_CLOSED` - Meeting completed but deal not closed
  * `CLOSED` - Deal closed/won
  * `WRONG_PERSON` - Wrong contact/person
  * `NOT_INTERESTED` - Lead is not interested
  * `NO_RESPONSE` - No response received
</ParamField>

<ParamField body="note" type="string">
  Optional note to add to the lead's history
</ParamField>

<Note>
  At least one of `status` or `customLeadStatus` must be provided. You can update both in a single request.
</Note>

## Response

<ResponseField name="success" type="boolean">
  Whether the update was successful
</ResponseField>

<ResponseField name="leadId" type="string">
  Lead identifier
</ResponseField>

<ResponseField name="status" type="string">
  The new status
</ResponseField>

<ResponseField name="message" type="string">
  Confirmation message
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X PATCH https://api.sendpilot.ai/v1/leads/lead_abc123/status \
    -H "X-API-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "status": "OPPORTUNITY",
      "note": "Interested in enterprise plan"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.sendpilot.ai/v1/leads/lead_abc123/status', {
    method: 'PATCH',
    headers: {
      'X-API-Key': process.env.SENDPILOT_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      status: 'OPPORTUNITY',
      note: 'Interested in enterprise plan'
    })
  });
  const result = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.patch(
      'https://api.sendpilot.ai/v1/leads/lead_abc123/status',
      headers={
          'X-API-Key': 'YOUR_API_KEY',
          'Content-Type': 'application/json'
      },
      json={
          'status': 'OPPORTUNITY',
          'note': 'Interested in enterprise plan'
      }
  )
  result = response.json()
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "leadId": "lead_abc123",
    "status": "OPPORTUNITY",
    "message": "Lead status updated to 'OPPORTUNITY'"
  }
  ```

  ```json 400 theme={null}
  {
    "statusCode": 400,
    "error": "Bad Request",
    "message": "Invalid status value"
  }
  ```

  ```json 404 theme={null}
  {
    "statusCode": 404,
    "error": "Not Found",
    "code": "LEAD_NOT_FOUND",
    "message": "Lead with ID 'lead_abc123' not found in this workspace"
  }
  ```
</ResponseExample>

<Note>
  When a lead's status is updated, a `lead.updated` webhook event will be sent to your registered webhook endpoints.
</Note>


## OpenAPI

````yaml PATCH /v1/leads/{id}/status
openapi: 3.0.0
info:
  title: SendPilot External API
  description: >
    The SendPilot API enables you to programmatically manage LinkedIn outreach
    campaigns,

    add leads, update lead statuses, send messages, and receive real-time
    webhook notifications.
  version: 1.0.0
  contact:
    name: SendPilot Support
    email: support@sendpilot.ai
    url: https://sendpilot.ai
servers:
  - url: https://api.sendpilot.ai
    description: Production server
security:
  - ApiKeyAuth: []
tags:
  - name: Credits
    description: Credits and quota management
  - name: Campaigns
    description: Campaign management endpoints
  - name: Leads
    description: Lead management endpoints
  - name: Lead Database
    description: Lead Database search endpoints
  - name: Lead Extractor
    description: Lead extraction campaign endpoints
  - name: Inbox
    description: Direct messaging endpoints
paths:
  /v1/leads/{id}/status:
    patch:
      tags:
        - Leads
      summary: Update lead status
      description: Update the status of a lead
      operationId: updateLeadStatus
      parameters:
        - name: id
          in: path
          required: true
          description: Lead ID
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateLeadStatusRequest'
      responses:
        '200':
          description: Lead status updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateLeadStatusResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    UpdateLeadStatusRequest:
      type: object
      properties:
        status:
          type: string
          enum:
            - PENDING
            - CONNECTION_SENT
            - CONNECTION_ACCEPTED
            - MESSAGE_SENT
            - REPLY_RECEIVED
            - DONE
          description: New status for the lead
        note:
          type: string
          description: Optional note for the status change
      required:
        - status
    UpdateLeadStatusResponse:
      type: object
      properties:
        success:
          type: boolean
        leadId:
          type: string
        status:
          type: string
        message:
          type: string
      required:
        - success
        - leadId
        - status
        - message
    Error:
      type: object
      properties:
        statusCode:
          type: integer
        error:
          type: string
        code:
          type: string
        message:
          type: string
      required:
        - statusCode
        - message
  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key for authentication

````