Connect your other systems
Recipes for syncing TruTec with your estimating and field systems, your accounting or ERP system and your CRM. Match records with external_ref, turn won estimates into budgets, set up jobs, bring field time and costs back, and keep everything in step.
View as MarkdownThis page shows how the pieces of the API fit together when TruTec runs next to other software: an estimating or field system that holds budgets and crew time, an accounting or ERP system that holds job cost and receivables, and a CRM that holds companies, contacts and deals. Each recipe links to the full reference for the endpoints it uses.
Every example uses the base URL https://trutec.ai/api and an API key in X-API-Key (Authentication). Build against a sandbox first: it runs the same API on sample data, and nothing you do there can reach your real customers.
Note
When an owner creates a key in Settings › API keys, they pick Read only, Read and write or Read, write and delete. Give each system its own key, and use Read only for any system that only pulls data. See Permissions.
Match records with external_ref#
TruTec ids are integers that never change. Store them in your systems, and store your ids in TruTec: every record you sync has an external_ref field for your other system's id.
| Record | Create-or-match call | Look up with ?external_ref= |
|---|---|---|
| Customer | POST /v1/client-accounts |
GET /v1/client-accounts |
| Site | POST /v1/locations |
GET /v1/locations |
| Job | POST /v1/jobs |
GET /v1/jobs |
| Contact | POST /v1/contacts |
GET /v1/contacts |
| Estimate | POST /v1/estimates |
GET /v1/estimates |
| Invoice | POST /v1/invoices |
GET /v1/invoices, GET /v1/jobs/{id}/invoices |
| Job cost | POST /v1/jobs/{id}/costs |
GET /v1/jobs/{id}/costs |
| Time entry | POST /v1/time-entries |
GET /v1/time-entries |
| Crew | POST /v1/crews |
GET /v1/crews |
| Crew member | POST /v1/crews/{id}/members |
GET /v1/people |
| Catalog service or cost item | POST /v1/catalog/services, POST /v1/catalog/{item_type} |
GET /v1/catalog/services, GET /v1/catalog/{item_type} |
The rules are the same everywhere:
external_refis a string, up to 255 characters (customers and sites: 120). It is read back on every record,nullwhen unset.- It is unique per workspace for each kind of record. A crew member's ref is unique within its crew, so one employee id can sit on each of a person's crews. Catalog refs are unique within their item type.
- A create call with a ref TruTec already holds is an upsert. The matching record is updated with that record's
PATCHrules, and you get200with"created": falseinstead of a twin. A new record returns201. Customers and sites also match by name or address when no ref matches (Customers & sites). PATCHsets, changes or clears it (nullor""). A ref another record of the same kind already holds is a409naming the holder:"code": "external_ref_conflict"withexisting_id(jobs:existing_job_id); customers and sites answer with"field": "external_ref",conflicting_idandconflicting_archivedinstead.- The
?external_ref=filter is an exact match and returns 0 or 1 rows indata. - A ref held by a cost or invoice on a different job is a
409: costs and invoices never move between jobs. A time entry matched by ref can't change its person or work order (409).
Look up a job by your accounting system's job id:
curl "https://trutec.ai/api/v1/jobs?external_ref=erp-26-118" \
-H "X-API-Key: $TRUTEC_API_KEY"
{
"data": [
{
"id": 70412,
"name": "Northgate Plaza Mill and Pave",
"external_ref": "erp-26-118",
"job_number": 1015,
"display_job_number": "J-1015",
"accounting_job_number": "26-118",
"status": "won",
"...": "..."
}
],
"pagination": { "total": 1, "limit": 50, "offset": 0 }
}
Tip
Pick one system as the owner of each ref. A common split: the CRM's ids on customers, contacts and jobs; the accounting system's ids on invoices; the field system's ids on time entries, job costs, crews and crew members. Write your ref the first time you create or see a record, and from then on every call is safe to repeat.
Estimating & field systems (budgets, cost codes, time and quantities)#
Won estimate to a job budget#
When a bid is won, your field or job-cost system needs the budget: one row per cost code with quantity, unit, cost by type and hours. Every estimate line item carries those.
- Find out the bid was won. Subscribe to
estimate_approved(an estimate is awarded) orjob_won(Keeping in sync). Theestimate_approveddelivery hasdata.estimate_idand the whole estimate underestimate. - Or list won estimates for the job:
GET /v1/estimates?job_id=70412&status=won. - Read the estimate with its line items:
GET /v1/estimates/{id}.
curl "https://trutec.ai/api/v1/estimates/9840" \
-H "X-API-Key: $TRUTEC_API_KEY"
Each area's services are the line items. One line, trimmed:
{
"id": 9840,
"external_ref": "erp-est-5521",
"status": "won",
"job_id": 70412,
"totals": { "price": 48500.0, "cost": 34852.1, "margin": 13647.9, "margin_pct": 0.2814 },
"areas": [
{
"id": 22018,
"name": "Front lot",
"services": [
{
"id": 55120,
"name": "2\" mill and overlay",
"cost_code": "02-100",
"quantity": 48250,
"unit": "SF",
"unit_cost": 0.6012,
"cost": 29007.9,
"price": 40125.0,
"labor_hours": 96.0,
"crew_hours": 16.0,
"man_days": 12.0,
"cost_by_type": {
"labor": 6240.0,
"equipment": 7120.5,
"materials": 12880.0,
"trucking": 2767.4,
"subcontractors": 0.0,
"overhead": 0.0,
"misc": 0.0
},
"is_optional": false,
"is_bundle_master": false,
"bundle_parent_service_id": null
}
]
}
]
}
How the fields map to a budget:
| TruTec line field | Budget field |
|---|---|
cost_code |
Cost code. null when the estimator didn't set one; map by name or the catalog item (assembly_id) instead. |
quantity, unit |
Budget quantity and unit of measure. |
cost_by_type |
Cost by type: labor, equipment, materials, trucking, subcontractors, overhead and misc (dump fees and anything else). The buckets add up to the line's cost. |
labor_hours |
Man-hours (every crew member's hours added up). |
crew_hours |
How long the crew works the line (duration, not man-hours). |
man_days |
Man-days. |
id |
Keep it: it is the estimate_service_id that visits, time entries and job costs carry, so actuals line up with the budget. |
labor_hours,crew_hours,man_daysandcost_by_typearenulluntil the estimate is priced.- Bundles: a bundle line (
is_bundle_master: true) already includes its sub-lines, and itscost_by_typedoes too. Send either the bundle line or its sub-lines (bundle_child_service_ids), not both. - Optional lines (
is_optional: true) are not intotals.price. Leave them out unless the customer took them. - For resource-level detail (each crew, piece of equipment and material with its own quantity and unit cost), read
GET /v1/estimates/{id}/line-items/{line_item_id}and use itscost_lines(The cost line object). - Store your system's id on the estimate:
PATCH /v1/estimates/{id}with{"external_ref": "erp-est-5521"}.
Cost codes#
GET /v1/cost-codes lists the workspace's job cost codes. These are the code values on job costs and time entries. Use it to build or check your mapping table to your other systems' cost codes.
curl "https://trutec.ai/api/v1/cost-codes?active=true" \
-H "X-API-Key: $TRUTEC_API_KEY"
{
"data": [
{
"id": 312,
"firm_id": 958,
"code": "02-100",
"name": "Asphalt paving labor",
"category": "labor",
"description": "Crew time on paving",
"is_active": true,
"created_at": "2026-09-02T15:10:00Z",
"updated_at": "2026-10-21T18:44:05Z"
}
],
"pagination": { "total": 1, "limit": 50, "offset": 0 }
}
Filters: active, category, updated_after, limit (max 200), offset. Listing never adds or changes codes. See Cost codes.
Field time back into TruTec#
Send crew time and field costs to TruTec so the job's budget-vs-actual, labor cost and month-end report stay current.
Note
Time entries need Operations. Scheduling, crews and timesheets must be turned on for the workspace, or POST /v1/time-entries returns 403 Operations not enabled. Cost writes need Job costing turned on, or they return 403 with the reason. Both act as the person who created the API key: adding time needs the Edit timesheets permission in TruTec, and cost writes need someone who can see pricing.
Each timecard line becomes one time entry: one person, one visit (work order), one shift.
curl -X POST "https://trutec.ai/api/v1/time-entries" \
-H "X-API-Key: $TRUTEC_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"user_id": 344,
"work_order_id": 4120,
"date": "2026-11-03",
"clock_in": "07:00",
"clock_out": "15:30",
"category": "work",
"reason": "Field system timecard",
"external_ref": "field-tc-88213-1"
}'
date,clock_inandclock_outare local (HH:MM) in the workspace's time zone.reasonis required and kept in the audit trail.user_idmust be a TruTec login in the workspace, andwork_order_ida visit on the job. Find visits withGET /v1/work-orders?job_id=.... Find people withGET /v1/people, which also returns the employee ids you stored as crew memberexternal_ref.- Upsert: send the same
external_refagain and the entry is corrected, not duplicated (200,"created": false). Times that didn't change keep the approval. - Cost code: a time entry's
cost_code,estimate_service_idandestimate_line_item_idcome from its visit's estimate line. You don't send them (unknown fields are a400). - New entries land unapproved. Approve them in TruTec or with
POST /v1/time-entries/{id}/approve. - An employee with no TruTec login can't have a time entry. Send that labor as a
laborcost instead (below).
Read time back with GET /v1/time-entries?updated_after=... (it also filters by external_ref). See Timesheets.
To hear about time as it happens, subscribe to time_entry_created and time_entry_updated. They fire for crew clock-ins and clock-outs, office corrections and API writes, and when an entry is approved, unapproved, voided or restored (data.approved, data.voided, data.changed). The payload carries the time entry with external_ref and cost_code (Record events).
Field costs back into TruTec#
Equipment hours, materials, trucking tickets and subcontractor bills become job costs:
curl -X POST "https://trutec.ai/api/v1/jobs/70412/costs" \
-H "X-API-Key: $TRUTEC_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"category": "equipment",
"cost_code": "02-100",
"description": "Milling machine, 8 hr",
"qty": 8,
"unit": "HR",
"unit_cost": 310.0,
"incurred_on": "2026-11-03",
"work_order_id": 4120,
"estimate_service_id": 55120,
"external_ref": "field-eq-88213-4"
}'
{
"data": {
"id": 88311,
"job_id": 70412,
"work_order_id": 4120,
"estimate_service_id": 55120,
"category": "equipment",
"cost_code": "02-100",
"source": "manual",
"description": "Milling machine, 8 hr",
"qty": 8.0,
"unit": "HR",
"unit_cost": 310.0,
"total_cost": 2480.0,
"external_ref": "field-eq-88213-4",
"...": "..."
},
"created": true
}
categoryislabor,material,equipment,trucking,subcontractor,overheadorother.cost_codedefaults to the workspace's code for the category.estimate_service_id(the line itemidfrom the estimate) ties the cost to its budget line.work_order_idties it to one visit. Either one from another job is a400.- Upsert: the same
external_refon the same job updates the cost (200,"created": false).unitandincurred_onstay as first recorded. - New costs are
pendingoffice review. Labor from TruTec's own crew clock (source: "clock") is rebuilt from time entries; change the time entry, not the cost. - Events:
job_cost_createdandjob_cost_updatedcarry the cost withexternal_ref,cost_codeandreview_status(clock labor included), so you can post approved costs to your accounting system as they land.
See Record costs.
Accounting / ERP (jobs, customers, invoices, payments, job cost)#
Job setup#
A won job carries what an accounting system needs to open the job:
| Need | Where it is |
|---|---|
| Job number | display_job_number (as TruTec prints it, for example J-1015) and job_number (digits only). |
| Accounting job number | accounting_job_number: the job's number in your accounting system. Set it with PATCH /v1/jobs/{id}/details (up to 80 characters) (Job details). |
| Your id | external_ref. |
| Customer | client_account_id and client_account_external_ref. Read the customer with GET /v1/client-accounts/{id}. |
| Site address | address on the job; the site is location_id and location_external_ref (GET /v1/locations/{id} for coordinates). |
| Dates | start_date, end_date (YYYY-MM-DD). |
| Contract value | The won estimate's totals.price. estimated_value on the job is the sales value. |
| Won reason | close_reason, close_notes. |
Write your accounting system's job number back so both systems print the same number:
curl -X PATCH "https://trutec.ai/api/v1/jobs/70412/details" \
-H "X-API-Key: $TRUTEC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"accounting_job_number": "26-118"}'
The job's scheduled visits (work orders, with crew and date) are in GET /v1/work-orders?job_id=70412 (Schedule & crews). A visit built from a won estimate carries the line's estimate_service_id.
Job cost#
Read everything recorded against a job with GET /v1/jobs/{id}/costs (cost entries and a summary), GET /v1/jobs/{id}/labor (crew time with cost_code and labor_cost_at_wage_rate) and GET /v1/jobs/{id}/invoices. Each cost entry carries cost_code, category, estimate_service_id and external_ref. See Job costing.
Invoices and payments#
TruTec drafts and sends customer invoices. Read them into your receivables and match payments.
curl "https://trutec.ai/api/v1/invoices?updated_after=2026-11-04T06:00:00Z" \
-H "X-API-Key: $TRUTEC_API_KEY"
- Each invoice has
job_id,estimate_id,doc_number,status,line_items({description, amount}),subtotal,discount,tax,amount,due_date,payment_terms,issued_at,paid_atandexternal_ref. See The invoice object. - Store your receivables invoice id on the TruTec invoice:
PATCH /v1/invoices/{id}with only{"external_ref": "acct-ar-10442"}. A body with onlyexternal_refworks on any invoice and changes nothing else. - Payments:
GET /v1/payments?paid_after=...returns each payment recorded on an invoice (amount,method, check number inreference,external_ref) and each invoice paid in full with none recorded. Invoices carryamount_paid,balance_dueandpayment_status(unpaid,partial,paid). - When your accounting system records a payment, part or whole, record it in TruTec:
POST /v1/invoices/{id}/paymentswithamount,paid_at,method,referenceand yourexternal_ref. The one that pays the rest marks the invoice paid. See Record a payment. - When your accounting system records a check, mark the TruTec invoice paid:
POST /v1/invoices/{id}/mark-paid(manualcheckinvoices only; online invoices follow the payment processor). -
Events:
invoice_createdandpayment_received. Each carries the whole invoice asGET /v1/invoices/{id}returns it (invoice:external_ref,job_id, amounts,status,paid_at, line items), next todata(invoice_id,doc_number,amount_cents). -
Payables: costs carry the vendor, the vendor's bill number and dates, and
ap_status. Pull unpaid bills withGET /v1/costs?ap_status=unpaid&updated_after=..., and match vendors on theirexternal_ref. See Vendor bills and payables. - Retainage: read it from the job's pay applications (AIA G702):
GET /v1/jobs/{id}/retainagefor what's held now,GET /v1/pay-applications?updated_after=...for every application's figures. See Retainage.
CRM (companies, contacts, deals)#
| CRM object | TruTec | Endpoints |
|---|---|---|
| Company / account | Customer (client account) | GET/POST /v1/client-accounts, PATCH /v1/client-accounts/{id} |
| Contact | Contact | GET/POST /v1/contacts, PATCH /v1/contacts/{id} |
| Deal | Job | GET/POST /v1/jobs, PATCH /v1/jobs/{id} |
| Deal stage | Pipeline stage | GET /v1/job-stages, POST /v1/jobs/{id}/move |
| Quote | Estimate and proposal | GET /v1/estimates, GET /v1/proposals |
- Deal fields: a job has
status(stage key),status_label,estimated_value,probability,start_date,assigned_to_user_id,client_account_idandclient_account_external_ref. - Stages:
GET /v1/job-stageslists the workspace's stages withstage_type(open,won,lostorexcluded). Map bystage_type, since workspaces rename stages. - Won and lost reasons: read
close_reasonandclose_noteson the job. To mark a deal lost from the CRM,POST /v1/jobs/{id}/movewith{"status": "lost", "reason": "Price", "competitor": "Acme Sealcoat"}; lost stages list theoutcome_questionsthey require. - Link a deal to its company by your id: send
client_account_external_refinstead ofclient_account_idonPOSTorPATCH /v1/jobs. - Quote activity: webhooks
proposal_sent,proposal_viewed,proposal_acceptedandproposal_declined; business eventsestimate_issued,estimate_revised,estimate_approvedandestimate_declined. Use the estimate'srevision_countfor a "times sent" count. - Order: create the customer, then the site, then the job, then contacts. See Customers & sites, Contacts and Jobs.
- Changes made in TruTec:
customer_created/customer_updated,contact_created/contact_updatedandsite_created/site_updatedsend the record (withexternal_ref) whenever someone adds or edits one, in the app or through the API.data.changednames the fields that changed.
Keeping in sync#
Use webhooks for speed and a pull for completeness.
Webhooks. POST /v1/webhooks with a target_url, an event_type and a secret. event_type: "all" sends every business event (job_won, job_scheduled, work_order_completed, estimate_approved, change_order_approved, invoice_created, payment_received, ...) and the record events for customers, contacts, sites, time entries and job costs (customer_updated, time_entry_updated, job_cost_created, ...). "*" sends the job and proposal events (job_created, job_updated, job_status_changed, proposal_*). They are separate, so create two subscriptions to get both. An all subscription made before November 5, 2026 gets the record events once you PATCH it with {"include_record_events": true}.
curl -X POST "https://trutec.ai/api/v1/webhooks" \
-H "X-API-Key: $TRUTEC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"event_type": "all", "target_url": "https://sync.example.com/trutec", "secret": "whsec_7f3a9c..."}'
- Signing:
X-TruTec-Signature: sha256=<hex>, HMAC-SHA256 with yoursecretover{X-TruTec-Timestamp}.{raw body}. Verify against the raw bytes (Verifying signatures). - Reply fast: any
2xxwithin 8 seconds, then do the work on a queue. - Retries: 7 attempts with backoff (1 min, 5 min, 30 min, 2 h, 6 h, 24 h), about 33 hours in all.
- Dedupe on
event_id. Delivery is at least once and can be out of order.event_idis the same in every retry, every replay and the feed;X-TruTec-Deliverychanges on each attempt. - Replay:
POST /v1/webhooks/replaywithsubscription_idandsincere-sends a time window (Replay and redelivery).
Event feed. GET /v1/events?after_id=<cursor> returns business events oldest first. Save next_after_id and page while has_more is true. It does not hold job_updated or proposal_*.
Nightly bulk export. GET /v1/exports/{dataset}.jsonl, or .csv for CSV (add .gz to either for gzip), with ?updated_after=<watermark> streams JSON Lines or CSV for customers, properties, jobs, estimates, estimate_lines, change_orders, invoices, job_costs, work_orders, time_entries, allocations, saved_routes and events. Save the X-TruTec-Export-Watermark response header and send it as updated_after next time. A full export now and then catches deletes. The CSV has the same records as the JSON Lines: objects with fixed keys become parent.child columns (cost_by_type.labor, totals.price) and arrays are JSON text in one cell, so a system that imports files instead of calling an API can load it as is (CSV). See Bulk data export.
Recommended architecture#
- Map once, by ref. Write your id into
external_refon every record you create or first see, and look records up with?external_ref=before creating. Every write is then an upsert you can retry. - Webhooks trigger, reads confirm. On a webhook, store
event_id, reply2xx, then read the current record by id (GET /v1/estimates/{id},GET /v1/jobs/{id}) before writing to your other systems. - Follow the feed as the source of truth. Every few minutes, page
GET /v1/eventsfrom your saved cursor so nothing is lost while your receiver was down. - Reconcile nightly. Pull each bulk export dataset with its watermark and upsert by
id; weekly, run a full export to catch deletes. - One owner per field. Decide which system owns each field (budgets and field time in the field system, receivables in accounting, deals in the CRM, estimates and the schedule in TruTec) and write in that direction only.
Build against a sandbox first#
Ask [email protected] for a sandbox workspace. It runs the same API with sample customers, sites, jobs, estimates, job costs and invoices, and its keys can't see your real records. Tell us you are building a field or accounting sync and we'll also load crews, scheduled visits and time entries (Operations turned on) so the time and cost recipes work. Point webhooks at a test endpoint, build every recipe above, then swap in a production key. IDs differ between sandbox and production, so match on external_ref, never on TruTec ids. See Sandbox & testing.