Opportunities

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.

NOTE  You can refer to the Online Help to find root and child access URLs of the entity you wish to query. Refer to Finding resource and child access URLs of REST API entities for more information.

Entity details

Entity Name:	Opportunities
Entity Path:	/atservicesrest/v1.0/Opportunities
Can Create:
Can Update:
Can Query:
Can Delete:
Can Have UDFs:

IMPORTANT  Requests to this entity require special handling. Refer to the Entity URLs and relationships section of this article for details.

Use CompanyNote 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 CompanyNote entity. When creating the CompanyNote, set the OpporunityID and actionType values. The Opportunity ID must reference an active Opportunity associated with the Company referenced by the Company ID. Refer to CompanyNotes.

Conditions and requirements

General

• If Autotask receives a create, update, or delete request for this entity and its corresponding module is unavailable, the API will return the error message, "The logged in Resource does not have the adequate permissions to update this entity type." For more information about installed modules, refer to our Modules article.
• The Opportunity entity can have no more than 200 UDFs. Refer to UserDefinedFieldDefinitions.
• 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.
• This entity's support for the VARStreet integration sunset with the release of Autotask 2022.2.
• 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
organizationalLevelAssociationID	organizationalLevelAssociationID cannot be cleared via the API. If not included in the response, the current value will remain unchanged. organizationalLevelAssociationID cannot be updated to an inactive OrganizationalLevelAssociation.
closedDate	Supply date-only values for this field. The API will automatically remove time values.
companyID	The companyID reference by Opportunity.contactID must = Opportunity.companyID, that is, the Opportunity Contact must be associated with the same Company as the Opportunity.
contactID	contactID must reference an isActive Autotask Contact associated with the Company referenced by the companyID field or from the parentCompany of the Company referenced by the Quote companyID.
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 isActive 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 >= startDate. Supply date-only values for this field. The API will automatically remove time values.
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."
startDate	IMPORTANT  The startDate in the API is what is the actual create date of the opportunity.
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	Datatype	Read-Only	Is Required	Reference Name	Picklist
advancedField1	decimal
advancedField2	decimal
advancedField3	decimal
advancedField4	decimal
advancedField5	decimal
amount	decimal
assessmentScore	decimal
barriers	string (500)
closedDate	datetime
companyID	integer			Companies
contactID	integer			Contacts
cost	decimal
createDate	datetime
creatorResourceID	integer
description	string (8,000)
helpNeeded	string (500)
id	long
impersonatorCreatorResourceID	integer			Resources
lastActivity	datetime
leadSource	integer
lossReason	integer
lossReasonDetail	string (500)
lostDate	datetime
market	string (500)
monthlyCost	decimal
monthlyRevenue	decimal
nextStep	string (500)
onetimeCost	decimal
onetimeRevenue	decimal
opportunityCategoryID	integer
organizationalLevelAssociationID	integer			OrganizationalLevelAssociations
ownerResourceID	integer			Resources
primaryCompetitor	integer
probability	integer
productID	integer			Products
projectedCloseDate	datetime
promisedFulfillmentDate	datetime
promotionName	string (50)
quarterlyCost	decimal
quarterlyRevenue	decimal
rating	integer
relationshipAssessmentScore	decimal
revenueSpread	integer
revenueSpreadUnit	string (6)
salesOrderID	integer			SalesOrders
salesProcessPercentComplete	decimal
semiannualCost	decimal
semiannualRevenue	decimal
stage	integer
startDate	datetime
status	integer
technicalAssessmentScore	decimal
throughDate	datetime
title	string (128)
totalAmountMonths	integer
useQuoteTotals	boolean
winReason	integer
winReasonDetail	string (500)
yearlyCost	decimal
yearlyRevenue	decimal

Additional resources

• Using Postman to explore the REST API
• Using Swagger UI to explore REST API requests
• Working with attachments in the REST API