File exports

Every download in the TruTec app is available through one call. POST /v1/exports names what you want, and the response is a link that opens or downloads the file for 24 hours, with no API key. Hand the link to a person, or fetch it yourself.

• The app's own file. The link runs the same code as the app's Download button, so the PDF, spreadsheet or map is the one your team would get.
• Made when opened. Nothing is made or stored up front. Each time the link is opened, the file is made from the data as it is at that moment.
• The app's rules. The export acts as the person who created the API key. Their role and your workspace's products decide what they may export, exactly as in the app.
• Built for assistants. An AI assistant can't hand you a file, but it can give you a link. The MCP tool export_file does this (see AI assistants).

For whole tables of data for a warehouse, the bulk export streams JSON Lines; workspace_data below gives a link to the same streams.

Get a link#

curl -X POST https://trutec.ai/api/v1/exports \
  -H "X-API-Key: sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"kind": "proposal", "id": 512}'

{
  "data": {
    "kind": "proposal",
    "title": "Proposal PDF",
    "format": "pdf",
    "id": 512,
    "options": {},
    "filename": "Northgate-Plaza-Sealcoat.pdf",
    "content_type": "application/pdf",
    "url": "https://trutec.ai/api/v1/export-files/eyJ2IjoxLCJrIjoicHJvcG9zYWwifQ.ZxY1aQ.k3j9/Northgate-Plaza-Sealcoat.pdf",
    "expires_at": "2026-10-14T15:04:11Z"
  }
}

Field
kind	What to export. Required. See Kinds
format	One of the kind's formats. Leave out for its default (listed first)
id	The record, for kinds that export one record. Kinds that cover the workspace take no id
options	Kind-specific settings, such as a date range. Unknown options are refused
firm_id	Partner keys only: the workspace to act on

A few kinds let an option stand in for id: job_id picks the job's newest work order, warranty or certificate, and estimate_id picks an estimate's proposal. The response's id is the record it picked.

Payroll for a week, as a spreadsheet:

curl -X POST https://trutec.ai/api/v1/exports \
  -H "X-API-Key: sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"kind": "time_entries", "format": "xlsx", "options": {"from": "2026-10-05", "to": "2026-10-11"}}'

A takeoff's shapes for Google Earth:

curl -X POST https://trutec.ai/api/v1/exports \
  -H "X-API-Key: sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"kind": "takeoff_geometry", "id": 90311, "format": "kmz"}'

GET /v1/export-kinds lists every kind with its formats, what id names, its options and what it needs, so a script or assistant can discover them.

Open the link#

Open url in a browser, or GET it. PDFs and images open in the browser tab; spreadsheets, CSV, zip and map files download. The response carries the file name in Content-Disposition.

• Lasts 24 hours. After that, or if anything below changes, the link returns 404. Ask for a new link.
• Checked every time. Each open checks that the key is still active, that your workspace still has API access, that the key's creator is still in the workspace and still allowed this export, and that the record is still there. Revoking the key stops every link it made.
• Big files take a moment. A file still being made returns 503 with Retry-After (seconds). In a browser, the page says so and reloads by itself. Takeoff maps are drawn once and reused.
• HEAD is free. A HEAD request returns the content type and file name without making the file, so link previews don't build it.
• Treat the link like a password. Anyone with it can open the file until it expires, and files can hold prices, pay and customer details. Share it only with the person who asked.

Each open makes the file again, the same as clicking Download in the app. Payroll exports are logged the same way the app logs them.

Kinds#

Permission: Read jobs, except the takeoff kinds, which need Read measurements. Needs is what the app requires of your workspace and of the key's creator.

Estimating & proposals#

kind	Formats	id	Options	Needs
proposal	pdf	proposal, or estimate_id	estimate_id	Estimating Pro, pricing access
estimate_workbook	xlsx	estimate		Estimating Pro, estimator or admin
estimate_cost_codes	csv	estimate		Estimating Pro, estimator or admin, estimate won
catalog	xlsx			Estimating Pro, estimator or admin
work_order	pdf	work-order sheet, or job_id	job_id	Estimating Pro

• proposal: the customer proposal, the file from Download PDF in the proposal builder.
• estimate_workbook: the estimate's lines and prices as Excel (Share › Download Excel).
• estimate_cost_codes: a won estimate's cost and price by cost code, for QuickBooks.
• catalog: the whole catalog as Excel (Catalog › Download Excel).
• work_order: the printable work order a crew takes to the job (Work orders › Print / PDF).

Operations#

kind	Formats	id	Options	Needs
change_order	pdf, csv	change order		Operations; pricing access for csv
daily_report	pdf	daily report		Operations
daily_log	pdf	daily log, or job_id + date	job_id, date	Operations
schedule	pdf		week	Operations
warranty	pdf	warranty, or job_id	job_id	Operations
warranty_certificate	pdf	warranty certificate, or job_id	job_id
payroll	csv		from, to, include_unapproved	Operations, payroll permission
time_entries	xlsx, csv		from, to, include_unapproved	Operations, payroll permission
payroll_hours	xlsx, csv		from, to, include_unapproved	Operations, payroll permission
equipment_entries	xlsx, csv		from, to	Operations, Estimating Pro, pricing access
materials_used	xlsx, csv		from, to, include_unapproved	Operations
billing_worksheet	xlsx		week	Operations, Estimating Pro, pricing access

• change_order: the PDF, or the CSV for accounting (header plus lines by cost code).
• daily_log: one visit's field log (id from GET /v1/daily-logs), or every visit on a job that day.
• schedule: the printable week of the crew schedule. Money columns show only for people with pricing access.
• payroll: closed time entries with an overtime summary per worker-week (Timesheets › Export payroll). Approved time only unless include_unapproved.
• time_entries, equipment_entries, billing_worksheet: the Accounting reports.
• payroll_hours, materials_used: the field log exports (hours only; quantities only).
• Payroll permission is Approve and export payroll in Settings › Team › Roles (owners have it).

Money#

kind	Formats	id	Options	Needs
job_costing	xlsx, csv		job_id, from, to	Operations, Estimating Pro, pricing access
job_cost_out	xlsx		job_id (required), from, to	Operations, Estimating Pro, pricing access
month_end_job_cost	xlsx, csv		month	Operations, Estimating Pro, pricing access
invoice	pdf	invoice	with_lien_waiver, disputed_amount	pricing access

• job_costing: budget against actual by category and the cost ledger for one job (job_id), or every costed job in the workspace (xlsx takes from and to).
• job_cost_out: one job's cost-out workbook for accounting.
• month_end_job_cost: the Accounting › Month-end report: every job with revenue or cost in the month, with revenue invoiced, direct cost by type, gross profit and GP %, plus job to date. The same numbers as GET /v1/reports/month-end-job-cost. Without month, last month (pinned when the link is made).
• invoice: the invoice as the customer sees it. with_lien_waiver adds the conditional lien waiver as the last page; the waiver must be turned on in Settings › Payments & Invoicing.

Jobs & field#

kind	Formats	id	Options	Needs
site_assessment	pdf	site assessment, or job_id	job_id
job_photos	zip		job_id (required)
company_portfolio	pdf	customer

• site_assessment: the branded report: every observation, photo and video, and the aerial with the pins.
• job_photos: every photo on the job, full size, in one zip (up to 500).
• company_portfolio: a customer's 11x17 paving portfolio: every site and takeoff map, with areas.

Takeoffs#

kind	Formats	id	Options	Needs
takeoff_map	pdf, png, jpg	measurement	style	Read measurements
takeoff_quantities	xlsx, csv	measurement		Read measurements
takeoff_geometry	kmz, kml, geojson	measurement		Read measurements

• takeoff_map: the map export: the takeoff drawn on the aerial with its legend and logo. style: "aerial" gives the clean imagery instead.
• takeoff_quantities: every quantity the takeoff provides with units, the numbers an estimate pulls from it (the same as GET /v1/measurements/{id}/items).
• takeoff_geometry: the drawn shapes (areas, lines and counted items) with their type, phase and spec, for Google Earth or GIS. GeoJSON coordinates are longitude, latitude.
• The map and shape kinds need a takeoff drawn on the aerial; plan-sheet takeoffs return 422.

Sales & CRM#

kind	Formats	id	Options	Needs
customers	csv		q, include_archived
contacts	csv		q, include_archived
sites	csv		q, type, include_archived
jobs	xlsx, csv		status, updated_after
capital_plan	xlsx, csv		client_account_id, location_id	capital plans turned on

• customers, contacts, sites: the Companies, Contacts and Locations list exports. customers holds up to 5,000 companies.
• jobs: status, customer, contact, address, type, value, salesperson and dates for the jobs the key's creator can see (up to 20,000, most recently changed first). Value is left out for people without pricing access.
• capital_plan: multi-year plan items by site and year: scope, status, PASER rating and estimated cost.

Reports and the whole workspace#

kind	Formats	id	Options	Needs
management_report	xlsx, csv, pdf, docx		report (required), from, to	owner, or a member allowed management reports; pricing access
workspace_data	jsonl.gz, jsonl		dataset (required), updated_after

• management_report: one of the Reports › Management reports: weekly-summary, week-glance, receivables, cash-forecast, top-customers, zip-code, bid-vs-actual, material-usage, completed-work, bid-schedule, lead-pipeline, win-loss, win-loss-graph, brochure-scans, work-type, market-analysis, data-dump, estimate-totals, item-history, material-history, resource-utilization, sub-utilization, vendor-utilization, minority, weekly-sales, kpi.
• workspace_data: one dataset of the bulk export (customers, properties, jobs, estimates, estimate_lines, change_orders, invoices, job_costs, work_orders, time_entries, allocations, events) as JSON Lines.

Options#

Option	Type
job_id	integer	A job. For kinds that otherwise take id, picks that job's newest record
estimate_id	integer	proposal: that estimate's proposal
client_account_id, location_id	integer	capital_plan: only this customer or site
date	date	daily_log with job_id: the day
from, to	date	The date range. Default this week (management_report: January 1 to today)
week	date	Any day in the week. Default this week
month	string	month_end_job_cost: the month, YYYY-MM. Default last month
include_unapproved	boolean	Also time not yet approved for payroll
include_archived	boolean	Also archived records
with_lien_waiver	boolean	invoice: add the lien waiver page
disputed_amount	number	invoice with the waiver: dollars of disputed claims
style	annotated or aerial	takeoff_map
report	string	management_report: which report
dataset	string	workspace_data: which dataset
updated_after	date-time	jobs, workspace_data: only records changed since
status	string	jobs: one pipeline status
q	string	customers, contacts, sites: search text
type	string	sites: one building type

Dates are YYYY-MM-DD in your workspace's time zone. Date-times are ISO 8601.

Finding the id#

kind	Where the id comes from
proposal	GET /v1/proposals (Proposals)
estimate_workbook, estimate_cost_codes	GET /v1/estimates
work_order	GET /v1/work-order-sheets?job_id=
change_order	GET /v1/change-orders (Change orders)
daily_report, daily_log	GET /v1/daily-reports, GET /v1/daily-logs (Daily logs)
warranty	GET /v1/warranties?job_id=
warranty_certificate	GET /v1/warranty-certificates?job_id=
invoice	GET /v1/invoices (Invoices & payments)
site_assessment	GET /v1/site-assessments (Site assessments)
company_portfolio, capital_plan	GET /v1/client-accounts (Customers & sites)
takeoff kinds	GET /v1/measurements (Measurements)

/v1/work-order-sheets, /v1/warranties and /v1/warranty-certificates list a job's printable documents (newest first; filter by job_id and status; paged with limit and offset). A work-order sheet is the document a crew takes to the job; /v1/work-orders is the crew schedule.

Errors#

Status	When
400	Unknown kind, format, option or field; id or a required option missing
403	The key lacks Read jobs (or Read measurements), the key's creator is no longer in the workspace, or the app does not allow this export for them. message is the app's reason, for example a role without the payroll permission
404	The record is not in this workspace
409	The record can't be exported as it is: the estimate isn't won, the lien waiver is off
413	Too big for one file: a job with more than 500 photos
422	Nothing to export: a takeoff with no mapped shapes, a job with no photos

On the link itself, refusals are a page (or plain text for scripts) with the same reason, and anything that makes the link invalid is 404.

Not available as links#

• Uploaded files (plans, contracts, signed documents): GET /v1/files/{id} already returns a download link (Photos & files).
• Exports built in the takeoff editor from what's on screen: image templates, the export wizard's custom layouts, the legend export, resident notices and earthwork reports. takeoff_map, takeoff_quantities and takeoff_geometry cover the saved takeoff.
• Estimating Expert documents, RoofTrace and landscape reports, and the older proposal builder from before Estimating Pro.