Skip to navigation

Update an opportunity

View as Markdown

Update an opportunity. Only the fields you send are changed.

Returns 404 if the opportunity doesn’t exist. Returns 403 if you don’t have access to its lead, or if another user owns it and you don’t have permission to manage other users’ opportunities.

lead_id, created_by and date_created can’t be changed: sending a different value returns 400.

Moving the opportunity to a status with type won sets date_won to today’s date if it isn’t already set or sent in the request.

Custom fields: set a custom field by setting custom.{custom_field_id} to its value, or to null to clear it, e.g.:

{ "custom.cf_v6S011I6MqcbVvB2FA5Nk8dr5MkL8sWuCiG8cUleO9c": "value", "custom.cf_8wtBWsdRU2Fur7GDnEeXQ7ra2Vu7R4hG1SNYdiEhh0F": null }

For a custom field with accepts_multiple_values: true, pass the full list of values, or add or remove a single value by appending .add or .remove to the key, e.g.:

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

See Custom Fields for more details.

Authentication

AuthorizationBasic
Use your API key as the username and leave the password empty.
OR
AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

idstringRequired

Request

This endpoint expects an object.
attachmentslist of objectsOptional

Files attached to the opportunity, up to 20 files and 25 MB in total. Replaces all of the opportunity’s attachments: include its current attachments to keep them, or pass [] to remove them all. Upload new files with the Files API first.

confidenceintegerOptional

Likelihood of winning the opportunity, as a percentage from 0 to 100. Opportunities with a won or lost status always have a confidence of 100 or 0.

contact_idstringOptional

ID of the contact to associate the opportunity with, e.g. cont_o0kP3Nqyq0wxr5DLWIEm8mVr6ZpI0AhonKLDG0V5Qjh. The contact must belong to the opportunity’s lead.

date_wondatetime or nullOptional

Date the opportunity was won, or is expected to close if it’s still active, e.g. 2013-02-20. Any time part is ignored. If neither the opportunity nor the request sets it, it’s set to today’s date when the status changes to one with type won. Pass your UTC offset in the x-tz-offset header to use your local date.

notestringOptional

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 or nullOptional

Rich text 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. Pass null to clear note_html; note is cleared as well.

status_idstringOptional

ID or label of the opportunity’s status, e.g. stat_4ZdiZqcSIkoGVnNOyxiEY58eTGQmFNG3LPlEVQ4V7Nk or Won. Labels are matched ignoring case. See Opportunity Statuses.

user_idstringOptional

ID of the user who owns the opportunity, e.g. user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA. Must be a member of your organization.

valueintegerOptional

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

value_periodenumOptional

How often value is paid: one_time, monthly or annual

Allowed values:

Response

Successful response
annualized_expected_valueinteger or null

expected_value as a yearly amount, in cents: multiplied by 12 when value_period is monthly, unchanged otherwise.

annualized_valueinteger or null

value as a yearly amount, in cents: multiplied by 12 when value_period is monthly, unchanged otherwise.

confidenceinteger

Likelihood of winning the opportunity, as a percentage from 0 to 100. Always 100 when status_type is won and 0 when it is lost.

contact_idstring or null

ID of the contact that the opportunity is associated with, e.g. cont_q4xYmlGhA3060dEl0NDJuHRxPMuVjqLn30AFSzh1fRk

created_bystring or null

ID of the user who created the opportunity, e.g. user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA

date_createddatetime
When the opportunity was created, as an ISO 8601 timestamp in UTC
date_lostdatetime or null

When the opportunity was lost, as an ISO 8601 timestamp in UTC. Set automatically when the opportunity moves to a lost status.

date_updateddatetime
When the opportunity was last updated, as an ISO 8601 timestamp in UTC
date_wondate or null

Date the opportunity was won, or is expected to close if it’s still active, as an ISO 8601 date, e.g. 2013-02-20. Set to today’s date when the opportunity moves to a won status without one.

expected_valueinteger or null

value multiplied by confidence, in cents, rounded down. For example, a value of 300000 with 75% confidence has an expected value of 225000.

idstring

The opportunity’s ID, e.g. oppo_8eB77gAdf8FMy6GsNHEy84f7uoeEWv55slvUjKQZpJt

lead_idstring

ID of the lead the opportunity belongs to, e.g. lead_IIDHIStmFcFQZZP0BRe99V1MCoXWz2PGCm6EDmR9v2O. Every opportunity belongs to exactly one lead.

notestring or null

The opportunity’s note as plain text, with note_html formatting converted to markdown

note_htmlstring or null

The opportunity’s note as rich text, a restricted subset of XHTML wrapped in a <body> tag, e.g. <body><p>Ready to sign next week.</p></body>

organization_idstring

The owning organization’s ID, e.g. orga_RbREgmiiwcr1w2b4cOnCMQaQPSIFxMqAD2Dh243uxcH

status_idstring

ID of the opportunity’s status, e.g. stat_4ZdiZqcSIkoGVnNOyxiEY58eTGQmFNG3LPlEVQ4V7Nk. The status determines the opportunity’s pipeline.

updated_bystring or null

ID of the user who last updated the opportunity, e.g. user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA

user_idstring

ID of the user who owns the opportunity, e.g. user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA

valueinteger or null

Monetary value of the opportunity in cents, e.g. 340000 for $3,400.00, in the organization’s currency (see value_currency). See value_formatted for a human-readable version.

value_periodenum

How often value is paid: one_time, monthly or annual

Allowed values:
attachmentslist of objectsOptional
Files attached to the opportunity
contact_namestring or nullOptional
Full name of the opportunity's contact
created_by_agent_idstring or nullOptional
ID of the agent that created the opportunity, or null if no agent created it.
created_by_namestring or nullOptional
Full name of the user who created the opportunity
is_stalledbooleanOptional

Whether Close has flagged the opportunity as stalled, and the flag hasn’t been dismissed. Only returned when requested in _fields.

lead_namestring or nullOptional

Display name of the opportunity’s lead. See the lead’s display_name.

lead_primary_emailobject or nullOptional

First email address of the lead’s first contact that has one. Only returned when requested in _fields.

lead_primary_phonelist of objects or nullOptional

First phone number of the lead’s first contact that has one, as a single-item list. Only returned when requested in _fields.

pipeline_idstring or nullOptional

ID of the pipeline that the opportunity’s status belongs to, e.g. pipe_04fC628PVB0HjK2Qq5EqEf

pipeline_namestring or nullOptional

Name of the pipeline that the opportunity’s status belongs to, e.g. Sales

stall_statusobject or nullOptional

Deprecated: use suggested_action instead. Why the opportunity is stalled and a suggested next step. Only returned when requested in _fields.

status_display_namestringOptional

Label of the opportunity’s status, prefixed with its pipeline’s name when the organization has more than one pipeline, e.g. Sales: Active

status_labelstringOptional

Label of the opportunity’s status, e.g. Active

status_typeenumOptional

Type of the opportunity’s status: active, won or lost

Allowed values:
suggested_actionobject or nullOptional

Suggested next step for the stalled opportunity. Only returned when requested in _fields.

updated_by_agent_idstring or nullOptional
ID of the agent that last updated the opportunity, or null if the last update wasn't made by an agent.
updated_by_namestring or nullOptional
Full name of the user who last updated the opportunity
user_namestring or nullOptional
Full name of the user who owns the opportunity
value_currencystring or nullOptional

ISO 4217 code of the organization’s currency, which value is in, e.g. USD

value_formattedstring or nullOptional

value formatted in the organization’s currency, followed by value_period unless it’s one_time, e.g. $500 or $50 monthly. Empty if value is null or 0.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
429
Too Many Requests Error