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.
- If this entity has a Parent relationship, you must perform all Create, Update, and Delete actions on the parent entity.
- If this entity is a child of a parent, you can leverage our Swagger instance to find the URLs you should use in your API calls. For more information, refer to Finding resource and child access URLs of REST API entities.
- To learn how to access Swagger, refer to Using Swagger UI to explore REST API requests.
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 |
|
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:
|
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. |
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:
- The entityInformation REST API call
- Making basic query calls to the REST API
- Advanced query features of the REST API
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 |
|
|
|
|
overageBillingRate | decimal | ||||
purchaseOrderNumber | string (50) | ||||
renewedContractID | long | ||||
serviceLevelAgreementID | integer | ||||
setupFee | decimal | ||||
setupFeeBillingCodeID | long | ||||
startDate | datetime | ||||
status | integer | ||||
timeReportingRequiresStart AndStopTimes |
integer |