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,
  "searchTerm": "Managed",
  "pageSize": 25
}

All filters optional: searchTerm (contains-match on contract name), companyID, status, pageSize (default 25, max 500). This is the only read tool for contracts — there is no contractType or end-date filter; filter on contractType/endDate client-side from the returned records.

Fetch a Single Contract or Build a Renewal Pipeline

There is no autotask_get_contract tool. There is no autotask_list_expiring_contracts tool either — autotask_search_contracts is the only read path for contracts. To fetch one contract, call autotask_search_contracts (scoped by companyID when known) and match the target id from the results. To build a 30/60/90-day renewal pipeline or find contracts already past their end date, call autotask_search_contracts with status: 1 (scoped by companyID when reviewing one account, otherwise paged across the portfolio) and filter/sort the returned records client-side by endDate:

• endDate on or before today → expired but still Active — the compliance-risk case. Autotask does not auto-deactivate expired contracts, so this is how clients still receiving service on expired paper are found.
• endDate within the next 30/60/90 days → the renewal call list, in ascending urgency order.

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

1. Add services

• Define included services
• Set pricing and quantities

1. Configure billing

• Invoice frequency
• Payment terms

1. Assign to tickets

• Set as default for company
• Route work appropriately

Contract Renewal

1. Identify expiring contracts

• autotask_search_contracts with status: 1, windowed client-side by endDate into 30/60/90-day buckets
• Filter for endDate before today to catch already-lapsed contracts still marked active

1. Review contract performance

• Compare budgeted vs actual hours
• Analyze profitability

1. Negotiate renewal

• Adjust pricing if needed
• Update service scope

1. 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)

1. Replenish as needed

• Add new block purchase
• Invoice for new hours

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