Integration guide
HCSS HeavyJob & HeavyBid and Viewpoint Vista integration
Jobs, cost codes and employees flow from Vista to HeavyJob; approved time cards and quantities flow back to payroll and job cost. The tight limit is HCSS's: 100 requests per minute, company-wide and shared with every other integration, against Vista's 2,000 per minute per key.
System facts last verified October 2026 against the vendors' documentation (sources below). Confirm details with HCSS and Trimble before you build.
HCSS and Vista side by side
- API style
- HCSSREST/JSON, one API per product: HeavyJob, HeavyBid Pre-Construction and Estimate Insights, Equipment360, Safety, Setups, Contacts, Attachments and others.
- VistaREST/JSON on the Trimble App Xchange platform. Reads are GETs against a cache; writes are POSTed actions such as add, replace, upsert and post.
- Authentication
- HCSSOAuth 2.0 through HCSS Identity. Most integrations use client credentials with space-separated product scopes such as heavyjob:read; an authorization code flow exists for partner apps. Tokens last an hour, and a missing scope returns 403.
- VistaAn API key in the X-Application-Key header over HTTPS. Keys come through your Trimble sales representative; third-party vendors get their own scoped key from the customer.
- Webhooks / events
- HCSSYes, for Pre-Construction, HeavyJob and Setups. Subscriptions confirm with a challenge handshake, can be signed (X-HCSS-Signature), and retry up to five times before the subscription stops and must be recreated.
- VistaNone in the API docs. Through App Xchange flows, creates, updates and deletes detected in the cache can trigger integration flows.
- Rate limits
- HCSS100 requests per minute and 20 concurrent requests, applied at the company level and shared by every client. Throttled calls return 429 with Retry-After.
- Vista2,000 requests per minute per API key (rolling 60 seconds, subject to change); 429 with Retry-After when exceeded. Multi-record GETs return up to 1,000 records with continuation tokens.
- Sandbox
- HCSSPartners only: HCSS says you must be logged in to an approved partner account to generate a sandbox, which comes with sample data in several products.
- VistaTrimble says you can purchase and connect a test environment to your Vista test instance. No free developer program.
- Exports and files
- HCSSNot researched. Confirm with vendor.
- VistaAttachments download through a cache-file action that returns a download URL.
- Marketplace / partners
- HCSSHCSS Marketplace partner program (registration through the HCSS Partner Portal).
- VistaTrimble App Xchange.
Who owns what
- Jobs, cost codes and employees flow from accounting to the field system.
- Approved time cards and quantities flow back to payroll and job cost.
What syncs between HCSS and Vista
The typical shape for this pair. Every row is typical: confirm it against your configuration in discovery.
| Object | Direction | System of record | |
|---|---|---|---|
| Jobs | Vista to HCSS | Vista (company plus job number) | Hourly |
| Typical frequency: Hourly. Notes: Key on company plus job, since a Vista job number is only unique within a company.(Typical: confirm against your configuration.) | |||
| Cost codes | Vista to HCSS | Vista (phases and cost types) | At job setup, then on change |
| Typical frequency: At job setup, then on change. Notes: Map Vista phases to HeavyJob cost codes in a reviewed table; reject unknown codes.(Typical: confirm against your configuration.) | |||
| Employees | Vista to HCSS | Vista (payroll) | Daily |
| Typical frequency: Daily. Notes: Confirm the Vista API exposes the employee fields HeavyJob needs for your license; they're not in the object list we verified.(Typical: confirm against your configuration.) | |||
| Vendors | Vista to HCSS | Vista | Daily |
| Typical frequency: Daily. Notes: For HeavyJob materials and subcontractor tracking; reference the Vista vendor number.(Typical: confirm against your configuration.) | |||
| Estimate → original budget | HCSS to Vista | HeavyBid at award; Vista after | Once at award |
| Typical frequency: Once at award. Notes: HeavyBid pre-construction estimates seed Vista budget codes and original estimates. Estimate structure rarely matches job cost structure, so map it first.(Typical: confirm against your configuration.) | |||
| Approved time cards | HCSS to Vista | HeavyJob until approved; Vista for payroll | Daily, after approval |
| Typical frequency: Daily, after approval. Notes: Only approved time cards. Vista writes are async actions; store each action ID and poll, and confirm the payroll actions your Vista license includes.(Typical: confirm against your configuration.) | |||
| Quantities installed | HCSS to Vista | HeavyJob | Daily |
| Typical frequency: Daily. Notes: Feed units to Vista job cost and projections so cost-to-complete reflects production.(Typical: confirm against your configuration.) | |||
Directions, owners and frequencies are the typical pattern from our integration guides and mapping workbook. Confirm each one against your configuration in discovery.
Is a native connector enough?
Both systems sit close to Trimble App Xchange: Vista's API runs on it, and App Xchange connectors exist for HCSS HeavyBid, HeavyJob, Safety and equipment (Charley built connectors there as a Trimble integrations engineer). Check App Xchange and the HCSS Marketplace for a standard flow before commissioning a build; build when your cost code mapping or approval rules need more than it offers.
Compare native connectors with a custom buildCommon gotchas
- HCSS allows 100 requests per minute and 20 concurrent requests per company, shared by every client. A time card backfill has to be throttled to fit around the contractor's other HCSS integrations.
- A stopped HCSS webhook subscription doesn't resume on its own after five failed retries. Check subscriptions on a schedule and recreate them.
- Vista reads come from a cache typically refreshed hourly, and writes are queued actions. A new job reaches HeavyJob after the next refresh, not instantly.
- Trimble's eligibility docs name cloud-hosted Vista on Trimble Construction One. On-premises Vista customers should confirm what their license allows, or use another route.
Sources
- HCSS developer portal
- HCSS: rate limits
- HCSS: requesting tokens
- HCSS: API scopes
- HCSS: webhooks overview
- HCSS: partner sandbox companies
- Trimble Vista API documentation
- Vista API: authentication
- Vista API: rate limits
- Vista API: concepts (cache, async actions)
- Trimble Help: Vista API documentation resources
- Vista API: setup and connection
Frequently asked questions
Can HeavyJob time cards flow into Vista?
Yes, as a daily push of approved time cards. Vista accepts writes as async actions, so the flow stores each action ID, polls for the result and routes failures (a closed job, an invalid phase) to a person.
What limits a HeavyJob and Vista sync?
HCSS's company-wide limit of 100 requests per minute and 20 concurrent requests, shared with every other HCSS integration. Vista allows 2,000 requests per minute per API key.
Is there an HCSS connector on Trimble App Xchange?
App Xchange connectors have been built for HCSS products, including HeavyBid, HeavyJob, Safety and equipment. Check what's currently listed for your Vista environment before scoping a custom build.
Next step
Connecting HCSS and Vista?
Bring one real job and the records you want to move. We'll walk through what syncs, who owns each record, and what to check first.