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

# Update Lead

> Update an existing lead in your campaigns

Update a lead by providing the lead ID and the fields you want to modify. Only the fields provided in the request will be updated.

## Path Parameters

<ParamField path="id" type="integer" required>
  The ID of the lead to update
</ParamField>

## Body Parameters

<ParamField body="campaign_id" type="integer" optional>
  The ID of the campaign to assign the lead to
</ParamField>

<ParamField body="phone_number" type="string" optional>
  The phone number of the lead (will be formatted to E164)
</ParamField>

<ParamField body="status" type="string" optional>
  The status of the lead. Must be one of: `created`, `completed`, `reached-max-retries`
</ParamField>

<ParamField body="variables" type="object" optional>
  Custom variables to merge with existing lead variables
</ParamField>

## Response

<ResponseField name="message" type="string">
  Success message indicating the lead was updated
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X PUT "https://api.example.com/api/leads/123" \
    -H "Authorization: Bearer YOUR_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "campaign_id": 456,
      "phone_number": "+1234567890",
      "variables": {
        "name": "John Doe",
        "company": "Acme Corp"
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.example.com/api/leads/123', {
    method: 'PUT',
    headers: {
      'Authorization': 'Bearer YOUR_API_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      campaign_id: 456,
      phone_number: '+1234567890',
      variables: {
        name: 'John Doe',
        company: 'Acme Corp'
      }
    })
  });

  const data = await response.json();
  ```

  ```php PHP theme={null}
  $response = Http::withToken('YOUR_API_TOKEN')
      ->put('https://api.example.com/api/leads/123', [
          'campaign_id' => 456,
          'phone_number' => '+1234567890',
          'variables' => [
              'name' => 'John Doe',
              'company' => 'Acme Corp'
          ]
      ]);
  ```

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

  response = requests.put(
      'https://api.example.com/api/leads/123',
      headers={'Authorization': 'Bearer YOUR_API_TOKEN'},
      json={
          'campaign_id': 456,
          'phone_number': '+1234567890',
          'variables': {
              'name': 'John Doe',
              'company': 'Acme Corp'
          }
      }
  )
  ```
</RequestExample>

<ResponseExample>
  ```json Success Response theme={null}
  {
    "message": "Lead updated successfully"
  }
  ```

  ```json Error Response - Lead Not Found theme={null}
  {
    "message": "Lead not found"
  }
  ```

  ```json Error Response - Campaign Not Found theme={null}
  {
    "message": "Campaign not found"
  }
  ```

  ```json Error Response - Invalid Phone Number theme={null}
  {
    "message": "Invalid phone number"
  }
  ```

  ```json Error Response - Validation Failed theme={null}
  {
    "message": "Validation failed",
    "errors": {
      "campaign_id": ["The selected campaign does not exist"],
      "status": ["This status is assigned automatically and cannot be set manually"],
      "variables": ["Variables must be an array"]
    }
  }
  ```

  ```json Error Response - Invalid Fields theme={null}
  {
    "message": "Invalid fields: invalid_field, another_invalid_field"
  }
  ```
</ResponseExample>

## Notes

* The lead must belong to the authenticated user
* If updating the campaign, the new campaign must also belong to the authenticated user
* Phone numbers are automatically formatted and validated
* Variables are merged with existing variables (not replaced)
* Only allowed fields can be updated: `campaign_id`, `phone_number`, `status`, `variables`
* The `status` field has restricted values for data integrity