CLclose
opportunities

Create an opportunity

Changed on

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.:

{ "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 for more details.

post/opportunity/

Request

  • Base URL
    https://api.close.com/api/v1
  • URL
    https://api.close.com/api/v1/opportunity/
  • Auth
    • HTTP basic
    • or OAuth 2
      Authorization code: https://app.close.com/oauth2/authorize/
      Token URL: https://api.close.com/oauth2/token/

Request body

confidenceinteger nullable
contact_idstring nullable
created_bystring nullable
date_createdstring date-time nullable
date_wonstring 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_idstring nullable

Opportunities belong to exactly one Lead. If not provided, a new lead will be created (appearing as "Untitled" in the UI).

notestring 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_htmlstring 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_idstring 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.

status_idstring 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.

user_idstring nullable
valueinteger nullable

Monetary value of the opportunity in cents, e.g. 340000 for $3,400.00. The currency is the organization's currency.

value_period'one_time' | 'monthly' | 'annual'

Response

Successful response

annualized_expected_valueinteger nullable required

Annualized expected value in cents.

annualized_valueinteger nullable required

Annualized value in cents.

confidenceinteger required
contact_idstring nullable required
contact_namestring nullable
created_bystring nullable required
created_by_agent_idstring nullable

ID of the agent that created the opportunity, or null if no agent created it.

created_by_namestring nullable
date_createdstring date-time required
date_loststring date-time nullable required
date_updatedstring date-time required
date_wonstring date nullable required
expected_valueinteger nullable required

Value multiplied by confidence, in cents.

idstring required
is_stalledboolean
lead_idstring required
lead_namestring nullable
notestring nullable required
note_htmlstring nullable required
organization_idstring required
pipeline_idstring nullable
pipeline_namestring nullable
status_display_namestring
status_idstring required
status_labelstring
status_type'won' | 'lost' | 'active'
updated_bystring nullable required
updated_by_agent_idstring nullable

ID of the agent that last updated the opportunity, or null if the last update wasn't made by an agent.

updated_by_namestring nullable
user_idstring required
user_namestring nullable
valueinteger nullable required

Monetary value of the opportunity in cents, e.g. 340000 for $3,400.00. See value_formatted for a human-readable version.

value_currencystring nullable
value_formattedstring nullable
value_period'one_time' | 'monthly' | 'annual' required

Changes

  • 8e360c61058cRevision changes
    • info

      added the pattern property ^custom\.(cf|lcf|ccf|acf|gcf|scf)_[A-Za-z0-9]+$ to the response body for the status

  • 7bdb9cfcca22Revision changes
    • breaking

      added the pattern property ^custom\.(cf|lcf|ccf|acf|gcf|scf)_[A-Za-z0-9]+(\.(add|remove))?$ to the request body

    • info

      removed the pattern property ^custom\. from the request body