Autotask Contracts

Autotask Contracts Management

Overview

Contracts in Autotask define the service relationship with clients - what services you provide, how you bill for them, and what service levels apply. Contracts control how time and expenses flow to invoices and are critical for MSP financial management.

Anti-triggers

• The invoice or billing item a contract produced — use autotask-billing.
• The catalog definition behind a contract service — services and bundles exist in the catalog independently of any contract; use autotask-product-catalog.
• Kaseya BMS agreements — BMS is a separate Kaseya PSA with its own contract objects that do not sync with Autotask; use kaseya-bms-api-patterns.
• A HaloPSA agreement — Halo models coverage, prepaid hours, and SLA on its own contract object, which does not sync with Autotask; use halopsa-contracts.

Key Concepts

Contract Types

Contract Fields

Contract Status

Service/Service Bundle

Services define what's included in a contract:

MCP Tool Reference

The autotask-mcp server exposes typed contract tools — prefer these over autotask_raw_request. Read tools return contract header fields only (no service lines), keeping responses light.

Search Contracts

Tool: autotask_search_contracts
Args: {
  "companyID": 12345,
  "status": 1,
  "contractType": 7,
  "endDateFrom": "2026-01-01",
  "endDateTo": "2026-12-31",
  "searchTerm": "Managed",
  "pageSize": 25
}

All filters optional: searchTerm (contains-match on contract name), companyID, status, contractType (picklist ID), endDateFrom/endDateTo (ISO dates bounding the end date), pageSize (default 25, max 500).

Get a Single Contract

Tool: autotask_get_contract
Args: { "id": 54321 }

Expiring / Expired Contracts Report

The renewal-pipeline tool. Lists contracts whose endDate falls within the next daysAhead days (default 60), org-wide or scoped to one company:

Tool: autotask_list_expiring_contracts
Args: {
  "daysAhead": 90,
  "companyID": 12345,
  "includeExpired": true,
  "status": 1,
  "pageSize": 100
}

• Pair with status: 1 to get "in effect but lapsing" contracts — the renewal call list.
• includeExpired: true drops the today lower bound, surfacing contracts already past their end date. Autotask does not auto-deactivate expired contracts, so status: 1 + includeExpired: true finds clients still receiving service on expired paper — the compliance-risk case.

Create a Contract

Tool: autotask_create_contract
Args: {
  "companyID": 12345,
  "contractName": "Acme Corp - Managed Services",
  "contractType": 1,
  "contractCategory": 3,
  "startDate": "2026-01-01",
  "endDate": "2026-12-31",
  "status": 1
}

Required: companyID, contractName, contractType, contractCategory, startDate, endDate

Create Contract Shells in Bulk

For multi-contract onboarding (e.g. one contract per client location), pass up to 50 shells in one call — same fields per item as autotask_create_contract:

Tool: autotask_create_contracts_bulk
Args: {
  "contracts": [
    { "companyID": 12345, "contractName": "Acme - HQ", "contractType": 1, "contractCategory": 3, "startDate": "2026-01-01", "endDate": "2026-12-31" },
    { "companyID": 12345, "contractName": "Acme - Branch", "contractType": 1, "contractCategory": 3, "startDate": "2026-01-01", "endDate": "2026-12-31" }
  ]
}

Shells are created sequentially (Autotask has no batch endpoint); a failure on one shell does not abort the rest. Each item reports {index, contractName, success, id | error} — retry only the failures.

Update a Contract

Tool: autotask_update_contract
Args: { "id": 54321, "endDate": "2027-12-31", "status": 1 }

Only fields provided change — the typical renewal move is extending endDate.

Contract Service Lines

autotask_create_contract_service (required: contractID, serviceID, unitPrice) and autotask_update_contract_service (required: id, contractID) manage the ContractServices line items on a contract.

API Patterns

Raw REST shapes for reference — the typed tools above cover these; reach for autotask_raw_request only for entities without typed tools (ContractBlocks, ContractRetainers, etc.).

Creating a Contract

POST /v1.0/Contracts
Content-Type: application/json

{
  "contractName": "Acme Corp - Managed Services",
  "companyID": 12345,
  "contractType": 1,
  "status": 1,
  "startDate": "2024-01-01",
  "endDate": "2024-12-31",
  "setupFee": 500.00,
  "timeReportingRequiresStartStopTimes": true,
  "serviceLevelAgreementID": 1
}

Adding Services to Contract

POST /v1.0/ContractServices
Content-Type: application/json

{
  "contractID": 54321,
  "serviceID": 111,
  "unitPrice": 150.00,
  "adjustedPrice": 150.00,
  "quantity": 50,
  "effectiveDate": "2024-01-01"
}

Creating Block Hours Contract

POST /v1.0/Contracts
Content-Type: application/json

{
  "contractName": "Acme Corp - Block Hours",
  "companyID": 12345,
  "contractType": 4,
  "status": 1,
  "startDate": "2024-01-01",
  "endDate": "2024-06-30"
}

Then add block hours:

POST /v1.0/ContractBlocks
Content-Type: application/json

{
  "contractID": 54322,
  "datePurchased": "2024-01-01",
  "hoursPurchased": 40,
  "hourlyRate": 150.00,
  "isPaid": true
}

Searching Contracts

Active contracts for a company:

{
  "filter": [
    {"field": "companyID", "op": "eq", "value": 12345},
    {"field": "status", "op": "eq", "value": 1}
  ]
}

Contracts expiring soon:

{
  "filter": [
    {"field": "status", "op": "eq", "value": 1},
    {"field": "endDate", "op": "lte", "value": "2024-03-31"},
    {"field": "endDate", "op": "gte", "value": "2024-01-01"}
  ]
}

Checking Block Hour Balance

GET /v1.0/ContractBlocks/query?search={"filter":[{"field":"contractID","op":"eq","value":54322}]}

Calculate remaining hours:

• Sum hoursPurchased - Sum of time entries against contract

Renewing a Contract

1. Create new contract with updated dates
2. Copy services from old contract
3. Update old contract status to Inactive
4. Link any ongoing tickets to new contract

Common Workflows

Contract Setup

1. Create contract

   • Set type, dates, status
   • Assign SLA

2. Add services

   • Define included services
   • Set pricing and quantities

3. Configure billing

   • Invoice frequency
   • Payment terms

4. Assign to tickets

   • Set as default for company
   • Route work appropriately

Contract Renewal

1. Identify expiring contracts

   • autotask_list_expiring_contracts with daysAhead 30/60/90 windows
   • Add includeExpired: true to catch already-lapsed contracts still marked active

2. Review contract performance

   • Compare budgeted vs actual hours
   • Analyze profitability

3. Negotiate renewal

   • Adjust pricing if needed
   • Update service scope

4. Create renewal

   • New contract with new dates
   • Update company default contract

Block Hours Management

1. Monitor balance

   • Track hours remaining
   • Alert at threshold (e.g., 10 hours)

2. Replenish as needed

   • Add new block purchase
   • Invoice for new hours

3. Handle overages

   • Bill at T&M rate
   • Or convert to new block

Service Level Agreements (SLAs)

Contracts can be linked to SLAs:

SLA violations trigger alerts and can affect contract terms.

Error Handling

Common API Errors

Validation Errors

"CompanyID is required" - Must associate with a company

"StartDate is required" - All contracts need start date

"Invalid service for contract type" - Service must match contract type

Best Practices

1. Name consistently - "Company - Contract Type" format
2. Set end dates - Never leave end date empty
3. Review renewals - Quarterly expiration review
4. Track profitability - Compare budgeted vs actual
5. Document terms - Note special conditions
6. Alert on block hours - Proactive replenishment
7. Assign SLAs - Define service expectations
8. Audit regularly - Ensure tickets use correct contracts

Related Skills

• Autotask Tickets - Ticket-contract association
• Autotask CRM - Company relationships
• Autotask Projects - Project billing