Contracts

The Contracts entity describes an Autotask Contract. Contracts specify a billing arrangement with a Company. 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, ContractNotes and ContractBlockHourFactors (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

Entity Name: Contracts

Entity Path:

/atservicesrest/v1.0/Contracts
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.

Conditions and requirements

General

  • This entity will be read-only if the module with which it is associated is not active. For more information, refer to Activations.
Parent None
Children ContractBillingRules, ContractBlockHourFactors, ContractBlocks, ContractCharges, ContractExclusionBillingCodes, ContractExclusionRoles, ContractMilestones, ContractNotes, ContractRates, ContractRetainers, ContractRoleCosts, ContractServiceAdjustments, ContractServiceBundleAdjustments, ContractServiceBundles, ContractServiceBundleUnits, ContractServices, ContractServiceUnits, ContractTicketPurchases
URLs Contracts​/query (GET, POST)
Contracts​/{id} (GET)
Contracts​/query​/count (GET, POST)
Contracts (PUT, POST, PATCH)
Contracts​/entityInformation (GET)
Contracts​/entityInformation​/fields (GET)
Contracts​/entityInformation​/userDefinedFields (GET)

Conditions and requirements

General

  • 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, setupFee.
  • create and update are allowed only for active Customer type Companies (Company.companyType = 1)
  • The Contract entity can have no more than 50 UDFs. Refer to UserDefinedFieldDefinitions.

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.

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.
billToCompanyID

When multi-currency is enabled, billToCompanyID must have the same currency as companyID.

billToCompanyID is required if supplying a value for billToCompanyContactID.
isCompliant contract.isCompliant 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 isActive 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 company.id equal to contract.companyID and to active Contacts associated with that Company's parentCompany, 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 isActive contact with the most recent lastActivityDate value (based on ContactId) will be selected.
  • contactName will accept contact names from a parentCompany associated with the contract.companyID.
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.
    timeReportingRequiresStartAndStopTimes timeReportingRequiresStartAndStopTimes 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.companyID either equals contract.companyID or references a Company where company.parentCompanyID equals contract.companyID
    setupFee setupFee field is Required for Recurring Service type Contracts.

    setupFeeBillingCodeID

    You cannot select the RMA system material code for setupFeeBillingCodeID.
    startDate contract.startDate must be < contract.endDate.

    Field definitions

    The following table describes the standard Autotask fields for this entity. Refer to the following articles for more information about working with these fields:

    To learn how to query picklist endpoints, refer to Understanding picklists.

    Notes

    • For string datatypes, the number in parentheses ( ) indicates the maximum number of characters allowed.
    • LT indicates Local Term.
    • If this entity has child collections, they will appear in a Child collection access URLs or an Entity URLs and relationships drop-down in the Entity details section of this article.
    • You can call the /query/count/ endpoint of a resource to determine how many records a collection holds.
    Field Name Datatype Read-Only Is Required Reference Name Picklist
    billingPreference integer    
    billToCompanyContactID integer     Contacts  
    billToCompanyID integer     Companies  
    companyID integer Companies  
    contactID integer     Contacts  
    contactName string (250)        
    contractCategory integer      
    contractExclusionSetID integer     ContractExclusionSets  
    contractName string (100)      
    contractNumber string (50)        
    contractPeriodType integer    
    contractType integer  
    description string (2000)        
    endDate datetime      
    estimatedCost decimal        
    estimatedHours decimal        
    estimatedRevenue decimal        
    exclusionContractID long   Contracts  
    id long    
    internalCurrencyOverageBillingRate (Multi-currency module only) decimal      
    internalCurrencySetupFee (Multi-currency module only) decimal      
    isCompliant boolean        
    isDefaultContract boolean        

    lastModifiedDateTime

    		 datetime  

     

     
    opportunityID integer     Opportunities  

    organizationalLevelAssociationID

    integer

     

     

    OrganizationalLevelAssociations

     
    overageBillingRate decimal        
    purchaseOrderNumber string (50)        
    renewedContractID long        
    serviceLevelAgreementID integer      
    setupFee decimal        
    setupFeeBillingCodeID long        
    startDate datetime      
    status integer    
    timeReportingRequiresStart
    AndStopTimes    		 integer    

    Additional resources