Contract

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.

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
  • BillingPreference field is required for all Contract types.
  • On create(), if no value is provided for Contract.BillingPreference, the value defaults to 2 (Reconcile Billing, that is, Manually).
  • On update(), if no value is provided for Contract.BillingPreference, the existing value will not update.
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():

  • The API will first look for a ContactID. If one is provided and it is valid, it will be associated with the Contract and Contract.ContactName will be ignored.
  • If an invalid ContactID is provided, the call will fail.
  • If no ContactID is provided, the API will compare ContactName (sorting full name) to active Contacts with Account.id equal to Contract.AccountID and to active Contacts associated with that Account's ParentAccount, if applicable.
    • If a match is found, Contract.ContactName will map to ContactID for that Contact.
    • If no match is found, Contract.ContactID will be set to Null, but the call will not fail.

ContactName

 
  • On create() and update(), Contract.ContactName must be in Firstname, Lastname format.

    • On create() and update(), Contract.ContactName must be in Firstname, Lastname format.

  • Query on ContactName must use sorting full name formatting "FirstName, LastName."
  • If multiple Contacts are returned with the same sorting full name and associated with the same account, the Active contact with the most recent LastActivityDate value (based on ContactId) will be selected.
  • ContactName will accept contact names from a ParentAccount associated with the Contract.AccountID.
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
  • ContractPeriodType field is required for Recurring Service type contracts.
    		•
    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