Contract
IMPORTANT The SOAP API entered a limited enhancement phase in Q4 2020. Access to version 1.6 will be deactivated.
The Contract entity describes an Autotask Contract. Contracts specify a billing arrangement with an Account. Autotask users manage contracts through the Contracts module. Autotask currently provides six contract types: Time and Materials, Fixed Price, Block Hours, Retainer, Incident, and Recurring Service. When creating a Contract, you must specify a Contract Type (Contract.ContractType).
Several contract types use one or more of the additional Contract related entities that are described in this document in order to create a functional billing arrangement; for example, a Block Hours contract requires the creation of one or more Contract Block entities in order to charge time against the contract. The API also provides two important but optional Contract related entities, ContractNote and ContractFactor(BlockHour).
BEFORE YOU BEGIN If you have not done so already, we recommend that you read our Overview of Autotask contracts article to familiarize yourself with the behavior of Contracts and how they influence other Autotask entities. Then, review the Conditions and requirements and Special field attributes sections of this article before working with this API entity.
Entity details
You can also retrieve this information with the Web Services API call The getEntityInfo() SOAP API call.
Entity Name: | Contract |
Can Create: | |
Can Update: | |
Can Query: | |
Can Delete: | |
Can Have UDFs: |
Conditions and requirements
General
- This entity will be read-only if the contract type is Block Hour, Fixed Price, Per Ticket, or Retainer, and the corresponding contract module is not active. For more information, refer to Activations.
- Resources with security levels that specify limited or no contract visibility cannot create, update, or query this entity.
- If the Multi-currency Installed Module is enabled, the following fields will return the relevant Customer Currency values instead of the Internal Currency values: OverageBillingRate, and SetupFee.
- create() and update() are allowed only for active Customer type Accounts (Account.AccountType = 1)
- The Contract entity can have no more than 50 UDFs. Refer to UserDefinedFieldDefinition.
The following fields will return the saved Internal Currency values: InternalCurrencyOverageBillingRate, and InternalCurrencySetupFee.
- Recurring Service type Contracts can NOT use the following three fields: EstimatedCost, EstimatedHours, and EstimatedRevenue.
- For all Contracts except Recurring Service, the following fields are Required: EstimatedCost, EstimatedHours, and EstimatedRevenue.
- Contract.
Special field attributes
Field | Conditions and Requirements |
---|---|
BillingPreference |
|
BillToAccountID |
When Multi-currency is enabled, BillToAccountID must have the same currency as AccountID. BillToAccountID is required if supplying a value for BillToAccountContactID. |
Compliance | Contract.Compliance can be set to True for all ContractTypes, but can only be set to False for ContractType = 7 (Recurring Service contract). Recurring Service is the only contract type that includes a compliance component. |
Contact-Old |
Contact-Old is a system generated user-defined field that Autotask may create when mapping Contract.ContractName string format data to an Active Contact. If Autotask cannot map Contract.ContactName to an active Contact, then the Contract.ContactName string is stored in the Contact-Old UDF and the Contract.ContactName field is cleared. |
ContactID |
On create() and update():
|
ContactName
|
On create() and update(), Contract.ContactName must be in Firstname, Lastname format. |
ContractExclusionSetID | The ContractExclusionSetID field must reference an active ContractExclusionSet when making a create call or when changing the field value during an update call. |
ContractPeriodType |
|
ExclusionContractID | ExclusionContractID cannot equal Contract.id. |
TimeReportingRequiresStartStopTime | TimeReportingRequiresStartStopTime allows only 0 or 1. |
OpportunityID | An associated opportunity must belong to the contract’s account or to any child account of the contract’s account. That is, Contract.OpportunityID must reference an Opportunity where Opportunity.AccountID either equals Contract.AccountID or references an Account where Account.ParentAccountID equals Contract.AccountID |
SetupFee | SetupFee field is Required for Recurring Service type Contracts. |
SetupFeeAllocationCodeID |
You cannot select the RMA system material code for SetupFeeAllocationCodeID. |
StartDate | Contract.StartDate must be < Contract.EndDate. |
Field definitions
The following table describes the standard Autotask field objects for this entity.
- To retrieve more detailed information specific to a particular Autotask implementation, use the Web Services API call The getFieldInfo() SOAP API call.
- For information on entity UDFs, use getUDFInfo().
- For String datatypes, the number in parentheses ( ) indicates the maximum number of characters allowed.
- LT indicates Local Term.
For more information about fields marked as picklists, review our Understanding picklists article.
Field Name | Label | Datatype | Read Only | Is Required | Reference Name | Picklist |
---|---|---|---|---|---|---|
AccountID | {LT:Account} | integer | Account | |||
BillingPreference | Billing Preference | integer | ||||
BillToAccountContactID | Bill To Account Contact ID | integer | Contact | |||
BillToAccountID | Bill To Account ID | integer | Account | |||
BusinessDivisionSubdivisionID | Business Division Subdivision ID | integer | Contract | |||
Compliance | Contract Compliance | boolean | ||||
ContactID | Contact ID | integer | Contact | |||
ContactName | Contract Contact | string (250) | ||||
ContractCategory | Category | integer | ||||
ContractExclusionSetID | Contract Exclusion Set ID | integer | ContractExclusionSet | |||
ContractName | Contract Name | string (100) | ||||
ContractNumber | Contract Number | string (50) | ||||
ContractPeriodType | Contract Period Type | string (1) | ||||
ContractType | Contract Type | integer | ||||
Description | Description | string (2000) | ||||
EndDate | End Date | date | ||||
EstimatedCost | Estimated Cost | double | ||||
EstimatedHours | Estimated Hours | double | ||||
EstimatedRevenue | Estimated Revenue | double | ||||
ExclusionContractID | Exclusion Contract ID | long | Contract | |||
id | id | long | ||||
InternalCurrencyOverageBillingRate (Multi-currency module only) | Internal Currency Overage Billing Rate | double | ||||
InternalCurrencySetupFee (Multi-currency module only) | Internal Currency Setup Fee | double | ||||
IsDefaultContract | Default Contract | boolean | ||||
OpportunityID | opportunity_id | integer | Opportunity | |||
OverageBillingRate | Contract Overage Billing Rate | double | ||||
PurchaseOrderNumber | Purchase Order Number | string (50) | ||||
RenewedContractID | Renewed Contract ID | long | ||||
ServiceLevelAgreementID | Service Level Agreement ID | integer | ||||
SetupFee | Contract Setup Fee | double | ||||
SetupFeeAllocationCodeID | Contract Setup Fee Allocation Code ID | long | ||||
StartDate | Start Date | date | ||||
Status | Status | integer | ||||
TimeReportingRequiresStart AndStopTimes |
Time Reporting Requires Start and Stop Times | integer |