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

# Update Lead

> Update lead information, status, assignments, and custom fields

## Authentication

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PATCH "https://app.journeybee.io/api/v1/leads/{leadId}" \
    -H "Authorization: Bearer your-api-key-uuid" \
    -H "Content-Type: application/json" \
    -d '{"status": "contacted", "tags": [1, 2, 3]}'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://app.journeybee.io/api/v1/leads/{leadId}', {
    method: 'PATCH',
    headers: {
      'Authorization': 'Bearer your-api-key-uuid',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      status: "contacted",
      tags: [1, 2, 3]
    })
  });
  ```
</CodeGroup>

## Path Parameters

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

## Request Body Schema

<ParamField body="company_name" type="string">
  Lead company name
</ParamField>

<ParamField body="email" type="string">
  Lead contact email address
</ParamField>

<ParamField body="phone_number" type="string">
  Lead contact phone number
</ParamField>

<ParamField body="first_name" type="string">
  Lead contact first name
</ParamField>

<ParamField body="last_name" type="string">
  Lead contact last name
</ParamField>

<ParamField body="status" type="string">
  Lead status. Options: `new`, `contacted`, `qualified`, `converted`, `lost`
</ParamField>

<ParamField body="assignedUsers" type="array">
  Array of user IDs to assign to this lead (replaces existing assignments)
</ParamField>

<ParamField body="tags" type="array">
  Array of tag IDs to assign to this lead (replaces existing tags)
</ParamField>

<ParamField body="customFields" type="array">
  Array of custom field values to update

  <Expandable title="Custom Field Object">
    <ParamField body="customFieldId" type="number" required>
      ID of the custom field to update
    </ParamField>

    <ParamField body="type" type="string" required>
      Field type: `text`, `textarea`, `number`, `date`, `boolean`, `select`, `multi_select`
    </ParamField>

    <ParamField body="value" type="object" required>
      Field value object matching the field type
    </ParamField>
  </Expandable>
</ParamField>

## Response Schema

<ResponseField name="id" type="number">
  The updated lead ID
</ResponseField>

<ResponseField name="uuid" type="string">
  The lead UUID
</ResponseField>

<ResponseField name="updated_at" type="string">
  Timestamp of when the lead was last updated
</ResponseField>

## Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PATCH "https://app.journeybee.io/api/v1/leads/789" \
    -H "Authorization: Bearer jb_api_1234567890abcdef" \
    -H "Content-Type: application/json" \
    -d '{
      "status": "qualified",
      "company_name": "TechCorp Solutions Inc",
      "phone_number": "+1-555-123-4567",
      "assignedUsers": [123, 456],
      "tags": [10, 11, 12],
      "customFields": [
        {
          "customFieldId": 5,
          "type": "number",
          "value": {
            "number": 150000
          }
        },
        {
          "customFieldId": 6,
          "type": "select",
          "value": {
            "select": 3
          }
        }
      ]
    }'
  ```

  ```javascript JavaScript theme={null}
  const updateData = {
    status: "qualified",
    company_name: "TechCorp Solutions Inc",
    phone_number: "+1-555-123-4567",
    assignedUsers: [123, 456],
    tags: [10, 11, 12],
    customFields: [
      {
        customFieldId: 5,
        type: "number",
        value: {
          number: 150000
        }
      },
      {
        customFieldId: 6,
        type: "select",
        value: {
          select: 3
        }
      }
    ]
  };

  const response = await fetch('https://app.journeybee.io/api/v1/leads/789', {
    method: 'PATCH',
    headers: {
      'Authorization': 'Bearer jb_api_1234567890abcdef',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(updateData)
  });
  ```
</CodeGroup>

## Example Response

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "id": 789,
    "uuid": "lead-uuid-789",
    "updated_at": "2024-01-15T14:30:00Z"
  }
  ```
</ResponseExample>

## Error Responses

<ResponseExample>
  ```json 401 Unauthorized theme={null}
  {
    "error": "Invalid API key or insufficient permissions"
  }
  ```
</ResponseExample>

<ResponseExample>
  ```json 403 Forbidden theme={null}
  {
    "error": "Write access required for this operation"
  }
  ```
</ResponseExample>

<ResponseExample>
  ```json 404 Not Found theme={null}
  {
    "error": "Lead not found or not accessible"
  }
  ```
</ResponseExample>

## Notes

* Requires API key with `write_access` permission
* Only provided fields are updated (selective updates)
* Array fields (assignedUsers, tags) replace existing values
* Custom field updates are validated against field definitions
* Triggers webhook events for integrations