Skip to content
TruTecDevelopers
Get an API key

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 Markdown

A 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, weekdays where 0 is Monday, start_time and end_time), its season, the visits contracted and the price (price_per_visit or a flat season_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.