---
title: "Create an opportunity"
method: POST
path: "/opportunity/"
tags: ["opportunities"]
---

# Create an opportunity

`POST /opportunity/`

Create an opportunity, optionally linked to an existing lead.

**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 an Opportunity 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.

## Request body

- CreateOpportunity
  - `attachments` AttachmentIn[], nullable
    - `content_type` string
    - `filename` string, required
    - `url` string, required
  - `confidence` integer, nullable
  - `contact_id` string, nullable
  - `created_by` string, nullable
  - `date_created` string, date-time, nullable
  - `date_won` string, date-time, nullable — If not set on the resource or in the request, `date_won` will be set automatically to today's date when setting `status_id` to a status with type `won`. The `x-tz-offset` header, used to pass your timezone's UTC offset, will be taken into account.
  - `lead_id` string, nullable — Opportunities belong to exactly one Lead. If not provided, a new lead will be created (appearing as "Untitled" in the UI).
  - `note` string, nullable — Plaintext/markdown version of the note. If `note_html` is also provided in the same request, this value is ignored and `note` is derived from the HTML instead.
  - `note_html` string, nullable — Rich-text HTML version of the note. When set, `note` is automatically populated with the plaintext version (tags become markdown), overriding any `note` value passed in the same request.
  - `pipeline_id` string, nullable — Specify which pipeline this opportunity should belong to. When supplied without `status_id`, the opportunity will be created with the first available status of that pipeline. When supplied with `status_id`, the status must belong to the specified pipeline or a 400 error will be returned. If the pipeline does not exist, a 400 error will be returned. See the [Pipelines API](https://developer.close.com/api/resources/pipelines).
  - `status_id` string, nullable — Post a `status_id` to create an opportunity with a specific status. If omitted, the organization's default (first) status will be used (or the first status of the `pipeline_id` if provided). See the [Opportunity Status API](https://developer.close.com/api/resources/opportunity-statuses).
  - `user_id` string, nullable
  - `value` integer, nullable
  - `value_period` 'one_time' | 'monthly' | 'annual'

## Response `200`

Successful response

- 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

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