Update an opportunity
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.:
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.:
See Custom Fields for more details.
Authentication
Bearer authentication of the form Bearer <token>, where token is your auth token.
Path parameters
Request
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.
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.
ID of the contact to associate the opportunity with, e.g. cont_o0kP3Nqyq0wxr5DLWIEm8mVr6ZpI0AhonKLDG0V5Qjh. The contact must belong to the opportunity’s lead.
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.
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.
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.
ID or label of the opportunity’s status, e.g. stat_4ZdiZqcSIkoGVnNOyxiEY58eTGQmFNG3LPlEVQ4V7Nk or Won. Labels are matched ignoring case. See Opportunity Statuses.
ID of the user who owns the opportunity, e.g. user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA. Must be a member of your organization.
Monetary value of the opportunity in cents, e.g. 340000 for $3,400.00. The currency is the organization’s currency.
How often value is paid: one_time, monthly or annual
Response
expected_value as a yearly amount, in cents: multiplied by 12 when value_period is monthly, unchanged otherwise.
value as a yearly amount, in cents: multiplied by 12 when value_period is monthly, unchanged otherwise.
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.
ID of the contact that the opportunity is associated with, e.g. cont_q4xYmlGhA3060dEl0NDJuHRxPMuVjqLn30AFSzh1fRk
ID of the user who created the opportunity, e.g. user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA
When the opportunity was lost, as an ISO 8601 timestamp in UTC. Set automatically when the opportunity moves to a lost status.
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.
value multiplied by confidence, in cents, rounded down. For example, a value of 300000 with 75% confidence has an expected value of 225000.
The opportunity’s ID, e.g. oppo_8eB77gAdf8FMy6GsNHEy84f7uoeEWv55slvUjKQZpJt
ID of the lead the opportunity belongs to, e.g. lead_IIDHIStmFcFQZZP0BRe99V1MCoXWz2PGCm6EDmR9v2O. Every opportunity belongs to exactly one lead.
The opportunity’s note as plain text, with note_html formatting converted to markdown
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>
The owning organization’s ID, e.g. orga_RbREgmiiwcr1w2b4cOnCMQaQPSIFxMqAD2Dh243uxcH
ID of the opportunity’s status, e.g. stat_4ZdiZqcSIkoGVnNOyxiEY58eTGQmFNG3LPlEVQ4V7Nk. The status determines the opportunity’s pipeline.
ID of the user who last updated the opportunity, e.g. user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA
ID of the user who owns the opportunity, e.g. user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA
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.
How often value is paid: one_time, monthly or annual
Whether Close has flagged the opportunity as stalled, and the flag hasn’t been dismissed. Only returned when requested in _fields.
Display name of the opportunity’s lead. See the lead’s display_name.
First email address of the lead’s first contact that has one. Only returned when requested in _fields.
First phone number of the lead’s first contact that has one, as a single-item list. Only returned when requested in _fields.
ID of the pipeline that the opportunity’s status belongs to, e.g. pipe_04fC628PVB0HjK2Qq5EqEf
Name of the pipeline that the opportunity’s status belongs to, e.g. Sales
Deprecated: use suggested_action instead. Why the opportunity is stalled and a suggested next step. Only returned when requested in _fields.
Label of the opportunity’s status, prefixed with its pipeline’s name when the organization has more than one pipeline, e.g. Sales: Active
Label of the opportunity’s status, e.g. Active
Type of the opportunity’s status: active, won or lost
Suggested next step for the stalled opportunity. Only returned when requested in _fields.
ISO 4217 code of the organization’s currency, which value is in, e.g. USD
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.