---
title: "Update an existing lead"
method: PUT
path: "/lead/{id}/"
tags: ["leads"]
---

# Update an existing lead

`PUT /lead/{id}/`

Supports non-destructive patches. Nested `contacts` cannot be updated through this endpoint -- use the Contacts API instead.

**status**: See `status` and `status_id` guidance on the create endpoint.

**custom.FIELD_ID** (optional): See `custom.FIELD_ID` guidance on the create endpoint. You can also unset a single field, e.g.:

```json
{ "custom.cf_v6S011I6MqcbVvB2FA5Nk8dr5MkL8sWuCiG8cUleO9c": null }
```

If the custom field accepts multiple values, you can specify `.add` or `.remove` as part of the field key to add/remove a single value to/from a list of values, e.g.:

```json
{ "custom.cf_v6S011I6MqcbVvB2FA5Nk8dr5MkL8sWuCiG8cUleO9c.add": "Wednesday" }
```

adds "Wednesday" to the list of values which already exist on the given lead.

## Path parameters

- `id` string, required

## Response `200`

Successful response

- Lead
  - `addresses` LeadAddress[]
    - `address_1` string, nullable, required
    - `address_2` string, nullable, required
    - `city` string, nullable, required
    - `country` string, nullable, required
    - `label` string, nullable, required
    - `state` string, nullable, required
    - `tz_ids` string[]
    - `zipcode` string, nullable, required
  - `contact_ids` string[], required
  - `contacts` Contact[]
    - `created_by` string, nullable, required
    - `date_created` string, date-time, required
    - `date_updated` string, date-time, required
    - `display_name` string, required
    - `emails` ContactEmail[]
      - `email` string, required
      - `is_unsubscribed` boolean, required
      - `type` string, required
    - `id` string, required
    - `integration_links` RenderedIntegrationLink[]
      - `name` string, required
      - `url` string, required
    - `lead_id` string, nullable
    - `lead_suggestions_operation_id` string, nullable
    - `name` string, nullable, required
    - `organization_id` string, required
    - `phones` ContactPhone[]
      - `country` string, nullable
      - `outbound_sms_blocked` boolean
      - `phone` string, required
      - `phone_formatted` string
      - `type` string, required
      - `tz_ids` string[]
    - `recent_calls` ContactRecentCall[]
      - `dialer_id` string, nullable, required
      - `duration` integer, required
      - `finish_timestamp` string, date-time, required
      - `id` string, required
      - `status` 'created' | 'in-progress' | 'completed' | 'cancel' | 'no-answer' | 'busy' | 'failed' | 'timeout', required — Current status of the call.
    - `subscriptions` BasicSubscriptionInfoForContact[]
      - `contact_email` string, nullable, required
      - `date_created` string, date-time, required
      - `initial_email_id` string, nullable, required
      - `sequence_id` string, required
      - `sequence_name` string, required
      - `sequence_status` 'active' | 'paused' | 'draft', required
      - `start_date` string, date-time, nullable, required
      - `subscription_id` string, required
      - `subscription_status` 'active' | 'paused' | 'finished' | 'goal' | 'error', required
      - `subscription_status_reason` 'manual' | 'pending-call-timed-out' | 'bulk-action' | 'rate-limited' | 'sequence-deleted' | 'workflow-paused' | 'filter-not-matched' | 'insufficient-ai-credit-balance' | 'reply-received' | 'call-answered' | 'meeting-booked' | 'lead-status-changed' | 'outcome-met' | 'account-invalid' | 'account-failures' | 'sending-throttled-too-long' | 'membership-inactive' | 'send-as-error' | 'email-bounced' | 'call-failed' | 'sms-failed' | 'no-user-phone' | 'billing-error' | 'assignment-field-invalid' | 'lead-status-field-invalid' | 'assignees-missing' | 'run-as-disabled' | 'lead-not-visible' | 'internal-error' | 'field-mapping-error' | 'filter-config-invalid' | 'email-ai-generation-failed', required — Reason for each higher level status on a Workflow run.
    - `timezone` string, nullable
    - `timezone_source` string, nullable
    - `title` string, nullable, required
    - `updated_by` string, nullable, required
    - `urls` ContactUrl[]
      - `type` string, required
      - `url` string, required
  - `contacts_summary` string
  - `created_by` string, nullable, required
  - `created_by_name` string, nullable
  - `date_created` string, date-time, required
  - `date_updated` string, date-time, required
  - `description` string, nullable, required
  - `display_name` string
  - `html_url` string, required
  - `id` string, required
  - `integration_links` RenderedIntegrationLink[]
    - `name` string, required
    - `url` string, required
  - `localtime` string, date-time, nullable
  - `name` string, nullable, required
  - `opportunities` Opportunity[]
    - `annualized_expected_value` integer, nullable, required
    - `annualized_value` integer, nullable, required
    - `attachments` Attachment[]
      - `content_type` string, nullable, required
      - `filename` string, nullable, required
      - `size` integer, nullable, required
      - `thumbnail_url` string, nullable
      - `url` string, required
    - `comment_summary` CommentSummary
      - `comment_count` integer, required
      - `thread_id` string, required
    - `confidence` integer, required
    - `contact_id` string, nullable, required
    - `contact_name` string, nullable
    - `created_by` string, nullable, required
    - `created_by_name` string, nullable
    - `date_created` string, date-time, required
    - `date_lost` string, date-time, nullable, required
    - `date_updated` string, date-time, required
    - `date_won` string, date, nullable, required
    - `expected_value` integer, nullable, required
    - `id` string, required
    - `integration_links` RenderedIntegrationLink[]
      - `name` string, required
      - `url` string, required
    - `is_stalled` boolean
    - `lead_id` string, required
    - `lead_name` string, nullable
    - `lead_primary_email` ContactEmail
      - `email` string, required
      - `is_unsubscribed` boolean, required
      - `type` string, required
    - `lead_primary_phone` ContactPhone[], nullable
      - `country` string, nullable
      - `outbound_sms_blocked` boolean
      - `phone` string, required
      - `phone_formatted` string
      - `type` string, required
      - `tz_ids` string[]
    - `note` string, nullable, required
    - `note_html` string, nullable, required
    - `organization_id` string, required
    - `pipeline_id` string, nullable
    - `pipeline_name` string, nullable
    - `stall_status` StalledOpportunityActionItems
      - `communication_issue` 'no_issue' | 'cant_get_in_touch' | 'no_communication_attempts', required
      - `next_action` ActionItem, required
        - `action` 'mark_as_lost' | 'change_status' | 'follow_up' | 'adjust_close_date' | 'ask_someone_else_to_reach_out' | 'change_communication_method', required
        - `justification` string, required — A short justification for the recommended action in the sales pipeline. Maximum 2 sentences.
    - `status_display_name` string
    - `status_id` string, required
    - `status_label` string
    - `status_type` 'won' | 'lost' | 'active'
    - `suggested_action` OpportunitySuggestedAction
      - `action` 'change_status' | 'adjust_close_date' | 'follow_up_email' | 'follow_up_call' | 'follow_up_sms', required
      - `details` union, required
        - OpportunityChangeStatusActionDetails
          - `status_id` string, required
        - OpportunityFollowUpEmailActionDetails
          - `contact_id` string, required
          - `message_draft` string, required
          - `subject_draft` string, required
        - OpportunityFollowUpSMSActionDetails
          - `contact_id` string, required
          - `message_draft` string, required
        - OpportunityFollowUpCallActionDetails
          - `call_plan` string, required
          - `contact_id` string, required
        - OpportunityAdjustCloseDateActionDetails
          - `close_date` string, date, required
      - `justification` string, required
    - `updated_by` string, nullable, required
    - `updated_by_name` string, nullable
    - `user_id` string, required
    - `user_name` string, nullable
    - `value` integer, nullable, required
    - `value_currency` string, nullable
    - `value_formatted` string, nullable
    - `value_period` 'one_time' | 'monthly' | 'annual', required
  - `organization_id` string, required
  - `primary_address_full` string, nullable
  - `primary_address_summary` string, nullable
  - `primary_email` ContactEmail
    - `email` string, required
    - `is_unsubscribed` boolean, required
    - `type` string, required
  - `primary_phone` ContactPhone
    - `country` string, nullable
    - `outbound_sms_blocked` boolean
    - `phone` string, required
    - `phone_formatted` string
    - `type` string, required
    - `tz_ids` string[]
  - `recent_calls` object[]
  - `source` string, nullable
  - `status_id` string, required
  - `status_label` string
  - `summaries` object[]
  - `tasks` object[]
  - `updated_by` string, nullable, required
  - `updated_by_name` string, nullable
  - `url` string, nullable, required

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `404` — Not found

---

[API](https://skmtc.net/close/apis/close-api.md) · [All operations](https://skmtc.net/close/apis/close-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/close/close-api/revisions/0dcf3303e9d7/schema)