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

# Update Lead

> Update existing lead information and status

# Update Lead

Modify an existing lead's contact information, status, tags, or custom fields. Useful for keeping lead data current and tracking engagement progress.

<Note>Requires the `leads:write` permission.</Note>

## Request

<ParamField path="leadId" type="string" required>
  The unique identifier of the lead to update
</ParamField>

<ParamField header="x-api-key" type="string" required>
  Your API key with `leads:write` permission
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`
</ParamField>

### Body Parameters

<ParamField body="firstName" type="string">
  Lead's first name
</ParamField>

<ParamField body="lastName" type="string">
  Lead's last name
</ParamField>

<ParamField body="email" type="string">
  Primary email address
</ParamField>

<ParamField body="company" type="string">
  Company name
</ParamField>

<ParamField body="title" type="string">
  Job title
</ParamField>

<ParamField body="status" type="string">
  Lead status (e.g., "new", "contacted", "qualified", "converted",
  "unqualified")
</ParamField>

<ParamField body="tags" type="array">
  Array of tag strings for categorization
</ParamField>

<ParamField body="customFields" type="object">
  Object containing custom field key-value pairs
</ParamField>

## Examples

### Update Lead Status

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PUT "https://api.buena.ai/api/v2/leads/lead_123abc" \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "status": "contacted",
      "tags": ["linkedin-outreach", "responded"],
      "customFields": {
        "lastContactDate": "2024-01-20",
        "responseTime": "2 hours",
        "interest": "high"
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.buena.ai/api/v2/leads/lead_123abc", {
    method: "PUT",
    headers: {
      "x-api-key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      status: "contacted",
      tags: ["linkedin-outreach", "responded"],
      customFields: {
        lastContactDate: "2024-01-20",
        responseTime: "2 hours",
        interest: "high",
      },
    }),
  });

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

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

  response = requests.put(
      'https://api.buena.ai/api/v2/leads/lead_123abc',
      headers={
          'x-api-key': 'YOUR_API_KEY',
          'Content-Type': 'application/json'
      },
      json={
          'status': 'contacted',
          'tags': ['linkedin-outreach', 'responded'],
          'customFields': {
              'lastContactDate': '2024-01-20',
              'responseTime': '2 hours',
              'interest': 'high'
          }
      }
  )

  print(response.json())
  ```
</CodeGroup>

## Response

<ResponseField name="success" type="boolean">
  Always `true` for successful requests
</ResponseField>

<ResponseField name="data" type="object">
  The updated lead object
</ResponseField>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "id": "lead_123abc",
      "firstName": "John",
      "lastName": "Doe",
      "email": "john@techcorp.com",
      "company": "Tech Corp",
      "title": "Software Engineer",
      "status": "contacted",
      "tags": ["linkedin-outreach", "responded"],
      "customFields": {
        "lastContactDate": "2024-01-20",
        "responseTime": "2 hours",
        "interest": "high"
      },
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-20T15:30:00Z"
    }
  }
  ```
</ResponseExample>

## Next Steps

<CardGroup cols={2}>
  <Card title="List Leads" icon="list" href="/api-reference/leads/list">
    View all your leads
  </Card>

  <Card title="Delete Lead" icon="trash" href="/api-reference/leads/delete">
    Remove a lead
  </Card>

  <Card title="Enrich Lead" icon="sparkles" href="/api-reference/enrich/leads">
    Add enriched data
  </Card>

  <Card title="Lead Management" icon="book" href="/guides/lead-management">
    Learn lead management
  </Card>
</CardGroup>