Opportunity

IMPORTANT  The SOAP API entered a limited enhancement phase in Q4 2020. Access deactivation for version 1.5 began in Q1 2022 and will enter its concluding phases in October 2022. Access to version 1.6 will be deactivated in Q4 2024. Visit our SOAP API lifecycle FAQ article to learn more.

This entity describes an Autotask Opportunity. An opportunity is a forecasted piece of business: that is, an identifiable prospect that needs a product or service and offers a potential sale, project, or contract. Autotask Opportunities allow you to describe the amount, due date, and probability of expected sales revenue from an opportunity, track the progress of the opportunity, and generate sales forecasts.

You can track Opportunities for all account types and track multiple opportunities for each account. Opportunities can also be associated with one or more Quotes or eQuotes generated in Autotask. You add and manage Opportunities in Autotask in the CRM module.

Entity details

You can also retrieve this information with the Web Services API call The getEntityInfo() SOAP API call.

Entity Name:	Opportunity
Can Create:
Can Update:
Can Query:
Can Delete:
Can Have UDFs:

Use AccountNote to create opportunity notes via the API

The API does not include an OpportunityNote entity because, in Autotask, Opportunities do not have their own associated notes. To associate a note with an Opportunity via the API, use the AccountNote entity. When creating the AccountNote, set the OpporunityID and ActionType values. The Opportunity ID must reference an active Opportunity associated with the Account referenced by the Account ID. Refer to AccountNote.

Conditions and requirements

General

• This entity's support for the VARStreet integration sunset with the release of Autotask 2022.2.
• The Opportunity entity can have no more than 200 UDFs. Refer to UserDefinedFieldDefinition.
• When an opportunity is created via the API, the default values for all fields stored on the selected opportunity category will be applied.
• An Opportunity with multiple Quotes associated must have one Quote with Quote.PrimaryQuote = True.
• ExternalQuoteNumber for all Quotes associated with the same Opportunity must be unique.
• On update and create:
  If the values of any Cost and/or Revenue billing periods (that is, Onetime, Monthly, Quarterly, Semiannual, and Yearly; for example, OnetimeCost or OnetimeRevenue) are provided on create, or have changed on update, the total cost (Opportunity.Cost) and/or total revenue (Opportunity.Amount) will be recalculated and any Cost or Amount passed in will be ignored.

IMPORTANT  When the API receives a request to update a field that contains Rich Text, the API will update the text-only version of the field and overwrite the data in the Rich Text field with plain text. All text formatting and images will be lost. Refer to The Rich Text editor to learn more.

Special field attributes

Field	Conditions and Requirements
CreateDate	IMPORTANT  The Create Date in the API is called the Start Date in the UI.
DateStamp	IMPORTANT  The DateStamp in the API is the actual create date of the opportunity.
AccountID	The AccountID reference by Opportunity.ContactID must = Opportunity.AccountID, that is, the Opportunity Contact must be associated with the same Account as the Opportunity.
BusinessDivisionSubdivisionID	BusinessDivisionSubdivisionID cannot be cleared via the API. If not included in the response, the current value will remain unchanged. BusinessDivisionSubdivisionID cannot be updated to an inactive BusinessDivisionSubdivision.
ClosedDate	Supply date-only values for this field. The API will automatically remove time values.
ContactID	ContactID must reference an Active Autotask Contact associated with the Account referenced by the AccountID field or from the ParentAccount of the Account referenced by the Quote AccountID.
Description	This field not required, regardless of opportunity category "requiredness" settings.
LostDate	If Status is changed to Lost and a LostDate is supplied, then the supplied LostDate value will remain. If Status is changed to Lost and a LostDate is not supplied, then the LostDate is set to UtcNow. If Status is changed to something other than Lost, then the LostDate field is cleared, even if a value is supplied. If Status has not changed, Status is Lost, and a LostDate value is supplied, then the supplied LostDate value will remain. If Status has not changed, Status is not Lost, and a LostDate value is supplied, then the supplied LostDate value will be ignored (existing LostDate value will remain).
OnetimeRevenue	Invoice.Amount (Revenue) value for Opportunities created via Web Services are written to the One-Time Revenue column in the database. If an Opportunity is later updated via Web Services, any new value provided for Amount will be written to the One-Time Amount column and any values in the Monthly Amount, Quarterly Amount, Semi-Annual Amount, and Yearly Amount database columns will be cleared.
OpportunityCategoryID	The "required" status and available list value settings for fields stored on the opportunity's opportunity category will NOT be respected when creating or editing opportunities in the API. If no opportunity category is specified, the system default opportunity category is used. The default values for all fields stored on the utilized opportunity category are applied. If you specify a value for a field that is also defaulted by the opportunity category, your specified value is used.
OwnerResourceID	OwnerResourceID must reference an Active Autotask Resource with security level access to the CRM module.
OwnerResourceID	Resource Type for Owner resourceThe ownerResourceID must reference an active, standard Autotask resource with security level access to the CRM module. A resource with a non-standard security level, for example, API user (API only), is not a valid selection for ownerResourceID.
Probability	Probability must be >= 0 and <= 100.
ProjectedCloseDate	ProjectedCloseDate must be >= CreateDate. Supply date-only values for this field. The API will automatically remove time values.
ProjectedLiveDate	The ProjectedLiveDate has been relabeled as "PromisedFulfillmentDate." IMPORTANT  We will keep both the "ProjectedLiveDate" and "PromisedFulfillmentDate" fields in the API for one API revision, and will retire "ProjectedLiveDate" in the following revision.
RevenueSpread	If no RevenueSpreadUnit is supplied, this value will be discarded.
RevenueSpreadUnit	If this field is empty and no RevenueSpread value is supplied, this value will default to "all at once."
Status	If the status is changed to Lost through the UI or API, the LostDate field is updated to the current Date and Time. If the Lost status is changed to any other status, the field is cleared. For legacy opportunities, the Lost Date is updated to the last time the opportunity status was set to lost.
ThroughDate	Supply date-only values for this field. The API will automatically remove time values.
UseQuoteTotals	UseQuoteTotals can only = "True" if an Autotask Quote entity references this Opportunity.
UseQuoteTotals	UseQuoteTotals will evaluate against Opportunity.PrimaryQuote.

Field definitions

Field Name	Label	Datatype	Read Only	Is Required	Reference Name	Picklist
AccountID	Account Object ID	integer			Account
AdvancedField1	Number Of Users	double
AdvancedField2	Setup Fee	double
AdvancedField3	Hourly Cost	double
AdvancedField4	Daily Cost	double
AdvancedField5	Monthly Cost	double
Amount	Amount	double
AssessmentScore	Assessment Score	double
Barriers	Barriers	string (500)
BusinessDivisionSubdivisionID	Business Division Subdivision ID	integer			Opportunity
ClosedDate	Closed Date	datetime
ContactID	Contact Object ID	integer			Contact
Cost	Cost	double
CreateDate	Create Date	datetime
CreatorResourceID	Creator Resource ID	integer
DateStamp	Date Stamp	datetime
Description	Description	string (8,000)
HelpNeeded	Help Needed	string (500)
id	Object ID	long
ImpersonatorCreatorResourceID	Impersonator Creator Resource ID	integer			Resource
LastActivity	Last Activity	datetime
LeadReferral	Lead Referral Object ID	integer
LossReason	Loss Reason	integer
LossReasonDetail	Loss Reason Detail	string (500)
LostDate	Lost Date	datetime
Market	Market	string (500)
MonthlyCost	Monthly Cost	double
MonthlyRevenue	Monthly Revenue	double
NextStep	Next Step	string (500)
OnetimeCost	One-Time Cost	double
OnetimeRevenue	One-Time Revenue	double
OpportunityCategoryID	Opportunity Category ID	integer
OwnerResourceID	Creator Object ID	integer			Resource
PrimaryCompetitor	Primary Competitor	integer
Probability	Probability	integer
ProductID	Product Object ID	integer			Product
ProjectedCloseDate	Projected Close	datetime
PromisedFulfillmentDate	Promised Fulfillment Date	datetime
PromotionName	Promotion Name	string (50)
QuarterlyCost	Quarterly Cost	double
QuarterlyRevenue	Quarterly Revenue	double
Rating	opportunity_rating_id	integer
RelationshipAssessmentScore	Relationship Assessment Score	double
RevenueSpread	Spread Revenue Recognition Value	integer
RevenueSpreadUnit	Spread Revenue Recognition Unit	string (6)
SalesOrderID	Sales Order ID	integer			SalesOrder
SalesProcessPercentComplete	Sales Process Percent Complete	double
SemiannualCost	Semi-Annual Cost	double
SemiannualRevenue	Semi-Annual Revenue	double
Stage	Stage Object ID	integer
Status	Status	integer
TechnicalAssessmentScore	Technical Assessment Score	double
ThroughDate	Through Date	datetime
Title	Name	string (128)
TotalAmountMonths	number_months_for_estimating_total_profit	integer
UseQuoteTotals	Use Quote Total Amount	boolean
WinReason	Win Reason	integer
WinReasonDetail	Win Reason Detail	string (500)
YearlyCost	Yearly Cost	double
Yearly Revenue	Yearly Revenue	double