Create an opportunity
Create an opportunity. It’s added to the lead given in lead_id, or to the lead of contact_id, or to a new lead if neither is given. A lead can have at most 300 opportunities.
Returns the created opportunity.
Custom fields: set a custom field by setting custom.{custom_field_id} to its value, e.g.:
For a custom field with accepts_multiple_values: true, pass the full list of values, e.g. ["A", "B", "C"].
See Custom Fields for more details.
Authentication
Bearer authentication of the form Bearer <token>, where token is your auth token.
Request
Files to attach to the opportunity, up to 20 files and 25 MB in total. Upload each file with the Files API first.
Likelihood of winning the opportunity, as a percentage from 0 to 100. Defaults to 50. 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.
ID of the user to record as the opportunity’s creator, e.g. user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA. Must be a member of your organization. Defaults to you. Set it when importing opportunities from another system.
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.
ID of the lead to add the opportunity to, e.g. lead_IIDHIStmFcFQZZP0BRe99V1MCoXWz2PGCm6EDmR9v2O. Every opportunity belongs to exactly one lead. If omitted, the opportunity is added to the lead of contact_id, or to a new lead (shown as Untitled) if contact_id isn’t given either.
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.
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.
ID or label of the opportunity’s status, e.g. stat_4ZdiZqcSIkoGVnNOyxiEY58eTGQmFNG3LPlEVQ4V7Nk or Active. Labels are matched ignoring case. If omitted, the organization’s first status is used, or the first status of pipeline_id if given. See Opportunity Statuses.
ID of the user who owns the opportunity, e.g. user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA. Must be a member of your organization. Defaults to created_by.
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. Defaults to one_time.
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.