---
title: "Create a new lead"
method: POST
path: "/lead/"
tags: ["leads"]
---

# Create a new lead

`POST /lead/`

Contacts, addresses, and custom fields can all be nested in the lead. Activities, tasks, and opportunities must be posted separately.

**status / status_id** (optional): Post either `status` or `status_id` (but not both). If neither is provided, the organization's default (first) status will be used. Using `status_id` is recommended so that users can rename statuses in the UI without breaking your implementation.

**custom.FIELD_ID** (optional): Set custom fields by setting `custom.FIELD_ID` to the field value, where FIELD_ID is the ID of the custom field, e.g.:

```json
{ "custom.cf_v6S011I6MqcbVvB2FA5Nk8dr5MkL8sWuCiG8cUleO9c": "value", "custom.cf_8wtBWsdRU2Fur7GDnEeXQ7ra2Vu7R4hG1SNYdiEhh0F": "other value" }
```

If a custom field has `accepts_multiple_values: true`, the entire value will be replaced. For example, given a Lead has a Custom Choice Field with value `["A", "B"]`, adding choice `"C"` would mean setting the value to `["A", "B", "C"]`.

Note that using the `custom` field dict or the `custom.FIELD_NAME` syntax (instead of custom field IDs) is deprecated and will be removed from the API. See [Custom Fields](https://developer.close.com/api/resources/custom-fields) for more details.

## 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)