Service contracts
Read, write and start the recurring work a customer signed up for: the customer and site, term, renewal date, services and how the visits stand.
View as MarkdownA service contract is recurring work a customer signed up for, such as weekly lot sweeping, porter service or a yearly crack fill. In TruTec it lives under Service contracts: the contract puts each visit on the crew schedule, bills on its own plan and comes up for renewal before it ends.
You can read contracts, write a new one, change it, and activate or pause it. Sending the agreement to the customer to sign, invoices and renewals stay in the app. A workspace needs TruTec Bid or Build to have service contracts; other workspaces get 403. Every contract carries the job_id of the job that holds its visits, costs and invoices (empty until it is activated, unless you wrote it on a job).
List contracts#
GET /v1/service-contracts returns the workspace's contracts, most recently changed first, a page at a time (limit, offset).
| Filter | What it does |
|---|---|
status |
draft, active, paused, ended or cancelled |
client_account_id, location_id, job_id |
One customer, one site, or the contract that runs on a job |
renews_before |
Renewal date (or end date when no renewal date is set) on or before this day, YYYY-MM-DD |
updated_after |
Changed after this time (ISO 8601), for syncing |
q |
Words in the contract name or number |
curl "https://trutec.ai/api/v1/service-contracts?status=active&renews_before=2027-03-31" \
-H "X-API-Key: $TRUTEC_API_KEY"
Each contract carries its total for the year in dollars, billing_mode (how it is invoiced), the job_id that holds its visits, costs and invoices, and renews_by_itself.
Get one contract#
GET /v1/service-contracts/{contract_id} adds:
services: each service with how often it runs (frequency,weekdayswhere 0 is Monday,start_timeandend_time), its season, the visits contracted and the price (price_per_visitor a flatseason_price)visits: how many visits are planned, on the schedule, done, skipped, missed or cancelled
Write a new contract#
POST /v1/service-contracts saves a draft. Nothing goes on the schedule, nothing is billed and nothing is sent to the customer until it is activated. Send the site or customer, the term, and the services:
curl -X POST "https://trutec.ai/api/v1/service-contracts" \
-H "X-API-Key: $TRUTEC_API_KEY" -H "Content-Type: application/json" \
-d '{
"location_id": 15520,
"starts_on": "2027-04-01",
"ends_on": "2028-03-31",
"billing_mode": "monthly",
"services": [
{"name": "Night sweep", "frequency": "weekly", "weekdays": [0, 2, 4],
"start_time": "22:00", "end_time": "02:00", "minutes_per_visit": 90, "price_per_visit": 80},
{"name": "Crack fill", "frequency": "dates", "dates": ["2027-05-10"], "season_price": 2400}
]
}'
A service's frequency |
Goes with |
|---|---|
weekly, biweekly |
weekdays (0 is Monday; several are fine) |
every_n_days |
interval_days |
monthly, twice_monthly |
month_days (one day, or two) |
n_per_season |
visits_contracted, spread evenly over the season |
dates |
dates, the days you pick |
once |
One visit on the first day |
on_call |
Nothing planned ahead (snow, call-outs) |
A service is priced per visit (price_per_visit) or with one flat price for the term (season_price), not both. job_id runs the contract on a job you already have, such as the one that was sold; a job carries one contract at a time. Left out, the job is made when the contract is activated.
The contract is checked the same way as the contract screen. When something is missing you get 422 with the first problem in error and all of them in problems, in plain words ("Pick the customer."). Writes act as the key's creator, who needs to be an owner or have See prices and costs, and Invoices and payments to set how it bills.
Change a contract#
PATCH /v1/service-contracts/{contract_id} changes only the fields you send. services is the exception: it replaces the whole list. Read the contract, change what you need in its services, and send them all back with their ids. A service without an id is added. A service you leave out is removed from a draft, or turned off on a running contract so the visits already done stay.
On a running contract, a change to a service's days, how often or crew starts today, or on changes_start_on. Earlier visits and finished ones never change; upcoming ones are planned again. How a contract bills (billing_mode and the other billing fields) can be changed here only while it is a draft; after that it is the contract's Billing card in the app. null clears ends_on, renewal_date, agreed_total, tax_percent, the notes, the site and the account manager.
Activate and pause#
| Call | What it does |
|---|---|
POST /v1/service-contracts/{contract_id}/activate |
Starts a draft, or resumes a paused contract. Its visits are made from today on, its job is made if it has none, and with crew scheduling on the visits go on the crew schedule (crews are told when the schedule is next published) |
POST /v1/service-contracts/{contract_id}/pause |
Takes the upcoming visits off the schedule until it is activated again. Visits already started or done stay |
Neither takes a body, and neither sends the customer anything. A move that is not possible now (pausing a draft, activating a contract with no services) is a 409 that says why.
Contracts that run more than one year#
A customer can sign for 2 or 3 years with a price step each year. TruTec keeps one contract per year of the term, each with its own job, invoices and visits. term.years is how long the customer signed for, term.year is which year this contract is, and term.price_step_percent is how much every price goes up each year. renewed_from_id points at the contract before it, so you can walk a term from its first year.
From ChatGPT or Claude#
get_service_contracts reads: leave contract_id out to list, give it for one contract. create_service_contract writes a draft, update_service_contract changes one, and activate_service_contract and pause_service_contract start and pause it. The assistant asks before it activates, since that puts a season of visits on the crew schedule.