simPRO API Forum

Hi Simpro community,

I'm in the pre-build phase of a third-party integration that connects Simpro to an external workflow. Before committing to the architecture I want to validate a number of technical assumptions. I've worked through the REST API documentation but have several edge-case questions I haven't been able to confirm. I'll group them by topic.

Topic 1 — Webhooks

The integration is triggered by job creation and job updates. I need to confirm webhook behaviour before designing around it.

- When job.created fires, does the webhook payload contain the full job object including all fields and line items, or does it deliver only a job ID requiring a subsequent GET /jobs/{id} call to retrieve the data?
- Is there any way to filter webhook subscriptions by job type, job status, or custom field value at the subscription level? Or does every job.created and job.updated event fire regardless of what changed on the record?
- What is the typical delivery latency under normal platform load?
- Is there a retry mechanism if the receiving endpoint is temporarily unavailable? If so, what is the retry window, frequency, and maximum retry count?

Topic 2 — Job record fields at creation time

The integration needs to read specific fields immediately after a job is created — before any further human interaction with the job inside Simpro.

- Are labour estimate lines populated on the job object at the moment of creation, or are they typically added after the job exists?
- Is due_date consistently present on jobs generated from the maintenance planner at the time of creation, or can it be absent depending on how the job was raised?
- Is there a field that indicates how a job was originated — for example, whether it came from the maintenance planner, a manual raise, or a quote conversion?
- Are custom fields on the job record readable via the REST API at job creation time, and if so, what does the response structure look like?

Topic 3 — Site and asset data

The integration needs to read information stored at the site and asset level, not just at the job level.

- Are site-level contact records readable via the REST API? Can multiple contact types be stored against a single site (for example, a primary contact and a secondary contact with different roles), and are all of them returned via the API?
- Are custom fields on site or customer records readable via the REST API? Can they be used as filter parameters on job queries — for example, retrieving all jobs for sites where a specific custom field equals a specific value?
- When a job is generated from an asset, are the asset's details — including any custom fields or default labour times stored at the asset or catalogue item level — accessible on the job object via the API? Or would a separate call to an asset or catalogue endpoint be required to retrieve those details?
- Is there a reliable way to identify which asset type or catalogue service item a job line relates to from the job record alone?

Topic 4 — Write-back via PATCH

After an external event occurs, the integration needs to write data back to the Simpro job record.

- Can custom field values on a job be updated via PATCH /jobs/{id}?
- Are there any job status values that are write-protected via the API — that is, statuses that can only be set from within the Simpro UI and cannot be written via the API?
- Is there a recommended pattern for storing a small external reference against a job record — for example, a confirmation token, an external status flag, or a timestamp — without interfering with the job's standard workflow?

Topic 5 — Rate limits and query efficiency

The integration will need to handle varying job volumes without hitting limits.

- Does the 10 requests per second rate limit apply per API key, per Simpro build, or per originating IP address?
- For GET /jobs list queries, is server-side filtering available — for example, filtering by job status, due date range, or site — to avoid pulling the full job set on each poll?
- What is the maximum page size for paginated job list responses?

Topic 6 — Sandbox environment

- What is the current process for an independent developer to request a sandbox environment for building and testing an integration?
- Is sandbox access available prior to formal Simpro partner status, or does it require an existing partnership agreement?
- Any guidance appreciated, including pointers to specific API documentation sections I may have missed. Happy to clarify any of the above if the use case needs more context.

I acknowledge that I have asked alot, Your effort is very much appreciated. Thanks in advance.

Hi, thanks for the detailed write-up — this is exactly the kind of validation worth doing before you commit to an architecture. Answers below, grouped by your topics.

Topic 1 — Webhooks

- The webhook payload is not the full job object — it's event metadata plus a reference block with the relevant IDs. You'll need a follow-up GET /jobs/{id} to get the full record and line items.
- There's no field/attribute-level filtering (job type, status, custom field value) at the subscription level. What you can do is subscribe to more specific events rather than the broad job.created/job.updated — the event catalogue includes granular options like stage-transition events (e.g. pending/progress/complete/invoiced/archived) and status events, so if your trigger condition is really "job reached a particular stage/status," subscribing to those specific events avoids a lot of client-side filtering.
- We don't publish a fixed delivery-latency SLA — design your integration to tolerate some variance rather than assuming a fixed number.
- We don't publish specific automatic-retry parameters (window/frequency/max attempts). Failed deliveries are logged and can be retried from the build's System Setup → Webhook Logs. Since webhooks aren't a guaranteed-delivery queue, I'd treat them as a low-latency trigger only, and use the REST API (e.g. polling with If-Modified-Since) as a reconciliation fallback for anything business-critical, in case an event is ever missed.

Topic 2 — Job record fields at creation time
- Labour estimate lines are not populated at creation — POST /jobs/ only creates the job header. Sections/cost-centres/labour lines are added afterward via the job's nested subresources (they can be included in the same POST if you build the nested payload yourself, but nothing is auto-generated).
- due_date is nullable by default and only guaranteed if "Mandatory Due Date" is enabled in that build's System Setup — so don't assume presence in general. One exception: jobs generated by the maintenance/recurring planner always have this field set by the scheduler itself, regardless of that setting.
- Yes — there's an origination indicator: ConvertedFrom on the job object, {ID, Type, Date}, where Type is "Quote" or "Recurring" (maintenance-planner-generated jobs), and null for a manually raised job.
- Custom fields are readable immediately as a CustomFields array directly on GET /jobs/{id} — no separate call needed just to read them.

Topic 3 — Site and asset data
- Site contacts are readable via GET /sites/{siteID}/contacts/ and return the full collection — multiple contacts per site are supported, distinguished by a PrimaryContact flag and a free-text Position field (not a fixed role enum).
- Custom fields on sites/customers are readable via their own custom-field subresources, but they can't be used directly as a filter parameter on the Jobs list query. The workaround is to query the Site/Customer custom-fields endpoint for matching IDs first, then filter Jobs with Site.ID=in(...).
- When a job line references an asset, the job's cost-centre "assets" subresource only gives a thin reference (asset ID + asset type). You'll need a separate call to the Customer Assets endpoint (and the Asset Type/catalogue endpoint) to get custom fields or default labour times.
- You can identify what a job line relates to from the job record itself: asset-based lines carry an AssetType reference, and catalogue-based lines carry a Catalog{ID, PartNo, Name} reference.

Topic 4 — Write-back via PATCH
- Yes — job custom field values are updated via PATCH /jobs/{id}/customFields/{customFieldID} with {"Value": "..."}. They're a dedicated sub-resource, not part of the main job PATCH body.
- One status value is write-protected: Stage can be set to Pending, Progress, Complete, or Archived via PATCH, but not Invoiced — that's set automatically once a completed job is fully invoiced.
- A job custom field is the intended mechanism for stashing a small external reference (confirmation token, external status flag, timestamp) without touching normal workflow fields — that's exactly what they're designed for.

Topic 5 — Rate limits and query efficiency
- The limit is applied per Simpro client build, scoped to your integration's traffic against that specific build — if a single build receives more than 10 requests/second from your integration, subsequent requests get a 429 until you fall back under the threshold. It's not a single shared limit across an API key or IP covering all your builds.
- GET /jobs/ supports server-side filtering, including nested fields (e.g. Site.ID=123) and operators (lt, le, gt, ge, ne, between, in, !in). For polling, sending If-Modified-Since to fetch only changed records is the most efficient pattern.
- Max page size is 250 (pageSize=250); default is 30 if unspecified.

Topic 6 — Sandbox environment
- A dedicated sandbox that simulates a client build is offered as part of Partner-level engagement — it isn't a separate, lighter-weight facility available to an independent developer building a single-client integration outside that program.
- So yes, sandbox access is tied to pursuing formal partner status. If that fits where this integration is headed, you can start the process here: https://www.simprogroup.com/au/partners ... -a-partner. If you're building for one specific client in the meantime, the usual approach is to develop/test against that client's own build directly, with their cooperation.

For field-by-field detail beyond what's above, the full reference is at https://developer.simprogroup.com/apidoc/. Happy to dig into any of this further if it'd help your architecture decision.

Hi Team,

I really appreciate your detailed response.

I am from a product design background so thank you for your patience while I investigate navigating through the backend design validation which I am foreign to.

Your answers have given me a lot of confidence in the architecture direction I am heading and I have a few follow-up questions based on your response.

Follow-up 1 — Stage transition events as a smarter trigger

You mentioned granular stage-transition events as a more targeted alternative to the broad job.created subscription. This is really useful to know.

- Could you confirm which specific stage-transition events are available in the event catalogue?
- Do their payloads include the job ID needed for a follow-up GET /jobs/{id} call, or do they contain something different?
- Is there a specific event that fires at the point a job transitions into a "Pending" state — particularly for jobs originating from the maintenance planner?

Understanding this will help me determine whether I can use a more precise trigger rather than subscribing to every job creation and filtering on my end.

Follow-up 2 — Asset type default labour time

You confirmed that a job line carries an AssetType reference when the job is asset-based. I want to understand where default labour time lives in that chain.

- Is a default labour time for a given asset type accessible directly via the Asset Type endpoint? Or is default labour time only stored at the catalogue item level, meaning I would need a separate catalogue lookup after first retrieving the asset type?

Essentially I am trying to understand the minimum number of API calls required to get from a newly created job to a confirmed duration value, and whether that duration can ever be resolved in a single call chain without a catalogue lookup.

Follow-up 3 — Webhook reliability in practice

You recommended treating webhooks as a low-latency trigger and using REST polling with If-Modified-Since as a reconciliation fallback for anything business-critical.

- In practice, how frequently do webhook deliveries fail or get missed in a way that would require the polling fallback to catch them?
Is this something that happens rarely under normal conditions, or is it frequent enough that the polling fallback needs to be treated as an equally active part of the integration rather than just a safety net?

This will help me decide how aggressively to build out the polling fallback in the initial version versus treating it as a lower-priority reliability feature.

Follow-up 4 — Partner program and sandbox access

You mentioned that a dedicated sandbox is offered as part of Partner-level engagement rather than being available to independent developers outside that program.

- Could you give me a general sense of what the partner engagement process involves in terms of timeline, requirements, and any associated costs?
- Is there a lighter-weight developer tier or an interim pathway that provides sandbox access while a full partner application is being assessed?
- If formal partner status isn't immediately viable, is developing and testing directly against a willing client's live build a commonly used and accepted approach in the meantime?

I want to make sure I am taking the right path from the beginning rather than having to reverse course later.

Thanks again for the support — the level of detail in your first response has been genuinely valuable in helping me move forward with confidence.

Hi again — great follow-up questions, glad the first pass was useful. Here's what I can confirm on each.

Follow-up 1 — Stage transition events
- The stage-transition events available are: job.stage.pending, job.stage.progress, job.stage.complete, job.stage.invoiced, and job.stage.archived. There's also a broader job.status event if you need to catch status changes that aren't stage transitions.
- Payloads for these carry the job ID (and company ID) plus the stage value, not the full job object — so you'd still follow up with GET /jobs/{id} for the full record, same as job.created.
- On Pending specifically for maintenance-planner jobs: based on what I can see, when the planner creates a job directly into Pending stage, that's a creation, not a transition — so job.stage.pending does not appear to fire in that specific case, since there's no stage change event happening (the job never moves into Pending, it's created there). job.created is the correct trigger for that scenario. The stage-transition events would apply to any job (regardless of origin) that later moves between stages after creation. I'd recommend confirming this behavior with a quick test in your own build before relying on it, since I don't have full visibility into every path that could land a job in Pending.

Follow-up 2 — Asset type default labour time
Confirmed: the Asset Type record itself does not carry a default/estimated labour time field — nothing like that exists on it. Labour/time estimates live only on the Catalogue Item record (EstimatedTime).
So the minimum call chain depends on what the job line references:
- If the line carries a direct Catalog reference (catalogue-based line), one call to the Catalogue Items endpoint using that ID gets you EstimatedTime directly — that's the shortest path to a duration.
- If the line only carries an Asset Type reference (asset-based line) with no catalogue reference attached, there's no duration value available via the API for that line at all — Asset Type has nothing to offer there, and I didn't find any built-in link from an Asset Type to a specific "default" catalogue item. In that case a duration would need to come from somewhere outside the API (e.g. a business rule you maintain yourself, like "asset type X always maps to catalogue item Y").
So to directly answer your question: yes, it can be resolved in a single call, but only for catalogue-based lines. For pure asset-based lines, there currently isn't a call chain that resolves to a duration at all.

Follow-up 3 — Webhook reliability in practice
I don't have a failure-rate figure I can share — that's not something we publish, and honestly I'd be making it up if I gave you a number. What I can say: the fact that failed deliveries are only recoverable via a manual retry from Webhook Logs (rather than an automatic retry with guaranteed parameters) is itself a signal — I wouldn't build your polling/reconciliation path as a low-priority safety net. Given there's no delivery guarantee and no published failure rate, I'd treat it as an equally active part of the integration from day one, not something you bolt on later if problems show up. It costs you a bit more up front but avoids a rebuild later if webhooks turn out to be less reliable at your volume than expected.

Follow-up 4 — Partner program and sandbox access
This one's outside what I can verify from documentation on my end — timeline, requirements, and any costs for partner engagement are best confirmed directly with the partnerships team rather than me guessing at figures:
https://www.simprogroup.com/au/partners

On your other two questions:
- I'm not aware of a lighter-weight interim developer tier that sits between "no access" and full partner status — the sandbox is tied to the partner track as far as I can confirm.
- Developing/testing against a willing client's own live build is a commonly used approach for single-client integrations while you're not yet pursuing partner status — that's the practical path most independent developers in your position take. Just be mindful you're working against real production data at that point, so scope your test operations accordingly (e.g. avoid destructive writes, use a client-approved test job/site rather than live records).

Hi again,

Thank you once more for the thoroughness of your responses — this has been incredibly valuable in helping me validate the architecture before committing to a build direction.

I have three final clarifying questions based on your last response and I will leave you alone after this.

Catalogue item linkage at job creation

You confirmed that duration lives on the Catalogue Item record via EstimatedTime, and that for asset-based job lines with no catalogue reference attached there is no duration value available via the API at all.

This leads me to a practical question about real-world Simpro usage rather than the API itself:

-When a job is generated from the maintenance planner using an asset, is a Catalogue Item reference typically attached to the job line automatically — or does that depend entirely on how the individual vendor has configured their catalogue and asset setup inside Simpro?
-In your experience, how common is it for an asset-based job line to have no catalogue reference attached at all?

I am trying to understand what percentage of real-world jobs I can expect to have an API-resolvable duration versus needing to fall back to a business rule maintained outside of Simpro. Even a rough sense of whether this is a common or edge-case scenario would help.

If-Modified-Since polling behaviour

Based on your advice I intend to treat polling as an equally active part of the integration from day one rather than a fallback. I want to make sure the polling logic catches everything it needs to.

- When using If-Modified-Since on GET /jobs, does this filter against the job's creation timestamp, its last-modified timestamp, or both?
- If a job undergoes a stage change after creation — for example moving from Pending to Progress — does that stage change update the job's last-modified timestamp in a way that would be caught by this filter?

I want to confirm that a polling loop using this header will reliably surface both newly created jobs that a missed webhook didn't catch, and any subsequent stage changes on existing jobs that are relevant to the integration.

EstimatedTime field format on Catalogue Item

A small but important detail I want to confirm before building duration logic around this field:

- What unit is EstimatedTime stored in on the Catalogue Item record — hours, minutes, or something else?
- Is it always stored as a whole number, or can it be a decimal value such as 1.5 to represent 90 minutes?

Getting this wrong would cause every duration calculation downstream to be incorrect so I want to confirm it explicitly rather than assume.

Thanks again for the time and patience you have extended throughout this exchange. The quality of support here has given me a lot of confidence in building on top of the Simpro API and I look forward to potentially being part of the partner ecosystem down the track.

Hi — happy to close these out, no need to apologize for the questions, this is exactly the kind of diligence that saves a rebuild later.

Catalogue item linkage at job creation

This is vendor-configured, not automatic. A maintenance-planner-generated job only gets a resolvable duration on an asset-based line if the vendor has set up a default Prebuild (assembly) against that specific Asset Type + Service Level combination — or has an override configured at the contract level. If neither is set up, the job simply doesn't get a line item for that asset at all (it's attached at the department level with nothing to look up), so there's no partial state to worry about — it's either fully resolvable or not present.

One extra nuance worth building into your design: when the linkage does exist, what's typically attached is a Prebuild, not a single catalogue item. A Prebuild is an assembly that can bundle several catalogue items together, each with its own EstimatedTime. So "duration" in that case may mean summing across the assembly's components rather than reading one field off one item.

On the percentage question — I genuinely can't give you a reliable figure. That's a function of how thoroughly each individual vendor has configured Prebuild defaults against their asset types, which varies build to build and isn't something I can extrapolate globally. If this matters to your rollout, I'd suggest treating "does this asset type have a default Prebuild configured" as something you check per client build early in onboarding (a quick read of the Asset Type / Service Level setup would tell you), rather than assuming a fixed ratio across all Simpro users.

If-Modified-Since polling behaviour
Good news here: If-Modified-Since on GET /jobs filters against the job's last-modified timestamp, not its creation timestamp — and a stage change (e.g. Pending → Progress) does update that same last-modified value as part of the normal save. So a polling loop using this header will reliably catch both newly created jobs and subsequent stage changes on existing jobs — you don't need a separate mechanism for either case.

EstimatedTime field format on Catalogue Item
Precision: confirmed decimal-capable — 1.5 (i.e. 90 minutes) is a valid value, it is not constrained to whole numbers.
Unit: I want to be straight with you rather than guess — I couldn't pin down an explicit "hours" vs. "minutes" label from what I checked, so I'm not going to assert it with false confidence given how much you're relying on getting this right. My honest recommendation: set a known test value (e.g. 1.5) against a catalogue item in a test/sandbox build and check how it's presented back in the UI or in related calculated fields — that'll confirm the unit empirically before you commit duration math to it. If you'd rather not wait on a test cycle, raising this specific point via https://helpdesk.simprogroup.com/ should get you a definitive answer faster than I can from here.

It's great to hear the partner path is on your radar for the future. Feel free to come back if anything else comes up once you start building.