Integration API
connect the systems your crews already use

1What the Integration API does

---

One key, one set of endpoints, and the systems your company already runs can talk to ShieldSphere without anyone retyping data.

Most safety data starts life somewhere else. Your roster lives in a payroll system, your equipment in a maintenance platform, your field observations in whatever your superintendents carry. The Integration API is how those systems and ShieldSphere stay in step without a person in the middle copying records across.

Everything in this guide is done by an organization owner. Issuing a key grants standing access to your compliance data, so it is deliberately restricted to the single owner account rather than to every administrator.

2Words you'll see

---

Nine terms cover everything in this guide. Skim them once and the rest reads easily.

Term	What it means
API key	The secret string an outside system sends to prove it is allowed to talk to your ShieldSphere data. You see it once, when you create it.
Permission	One thing a key may do, such as "Read incidents" or "Create employees". A key carries only the permissions you tick.
Location scope	An optional restriction to one site. A scoped key cannot see any other location's records, no matter what it asks for.
Endpoint	One address the other system calls, such as /api/v1/incidents.
Idempotency key	A label the other system attaches to a write so that retrying it cannot create the record twice.
Job	Work that takes longer than a single request - hazard photo analysis. You get a job id immediately and check back for the result.
Webhook	A URL of yours that ShieldSphere calls when something happens, so the other system does not have to keep asking.
Signing secret	The secret used to prove a webhook really came from ShieldSphere and was not forged.
Request id	An identifier on every response. Quote it to support and we can find the exact request in our logs.

3Issuing an API keyAdmin

---

Decide what the key may do and which sites it may see, then hand the secret to whoever is building the integration.

After creation the list shows each key by name, along with the first few characters of the secret so you can tell several keys apart, its permissions, whether it is limited to a location, and when it was last used. A key that has never been used is worth chasing - it usually means the integration was never finished.

4Reading your data

---

What the other system can pull, and the one thing to tell whoever builds it.

This section is for the person writing the integration. These collections are available, each returning JSON:

Endpoint	Returns
/api/v1/profiles	Your locations. Fetch these first - most other calls need a location id.
/api/v1/employees	The roster. Active employees by default.
/api/v1/incidents	OSHA recordable incidents.
/api/v1/assets	Equipment and its inspection status.
/api/v1/chemicals	Chemical inventory by location.
/api/v1/scans	Hazard scan results, with findings on the single-scan endpoint.
/api/v1/inspections	Inspections, with their findings on the single-inspection endpoint. Finalized and archived inspections by default; drafts only when asked for.
/api/v1/training-records	Who completed which training, when, and when it expires. Expired records are included, because they are what a coverage check most needs to see.
/api/v1/training-sessions	Completed training sessions with attendee counts. Sessions still in progress are not listed.

The key travels in a header on every request:

Results come back in pages, oldest first, with a cursor for the next page. Passing updated_since with the timestamp of the last run returns only what has changed, which is what makes a nightly sync cheap.

5Sending records in

---

Outside systems can create employees, incidents, assets, chemicals, inspections and completed training sessions - and one habit prevents the only serious mistake available here.

Creating a record is a POST to the same address you would read it from. The response carries the new record's id, and for incidents also its OSHA case number.

Incidents accept partial information. OSHA allows seven days to complete a 301 form, so the other system can send what it has - location, date, description, employee name and classification - and someone finishes the record in ShieldSphere later.

6Hazard photos from the field

---

Send a photo of a work area and get the same OSHA analysis the AI Hazard Scanner produces in the app.

This is the capability most worth building an integration around. If your crews already record observations with photos somewhere else, that system can hand each photo to ShieldSphere and receive back a list of likely hazards with OSHA citations and corrective actions - without anyone re-uploading anything.

Analysis takes longer than a web request should wait, so it works in two steps. The other system submits the photo and immediately receives a job id. A few moments later it asks for that job and gets the findings, along with a scan id so the result also appears in your ShieldSphere scan history like any other scan.

7Sending records out

---

ShieldSphere does not push whole records into another system. The other system collects them, either on a schedule or the moment a webhook tells it something new is waiting.

Getting records out of ShieldSphere and into a payroll platform, an insurer's portal or your own data warehouse always works the same way: the other system asks for them. There are two ways to know when to ask, and most integrations that need everything use both.

Setting up a scheduled sync

This part is for the person writing the integration.

Using a webhook to know when to look

A webhook is a short notice, not the full record. It names the event, says where the record came from, and carries the record's id, its location and a few summary fields - an incident's case number and date, an inspection's finding count, a scan's risk level. Privacy-case incidents name the employee as "Privacy Case" in the webhook too, and near-miss notices carry no names at all.

The other system then reads the whole record. It needs two things from you, both issued in Settings → Developers:

These are the events you can send:

Event	Sent when
Hazard scan completed	A hazard scan finishes - in the app, on mobile, from a contractor, or a photo sent through the API.
Hazard scan failed	The analysis of a scan fails. Problems with an upload or a save, which ShieldSphere has to fix, are not sent.
Incident recorded	A recordable incident is logged, or one reported through the employee portal or incident chat is approved.
Near miss reported	A near miss is reported, including anonymous reports from a QR code.
Employee added	An employee is added, one at a time or in a bulk upload.
Asset added	An asset is added, one at a time or in a bulk upload.
Chemical added	A chemical is added to an inventory, including from a chemical list import.
Inspection recorded	An inspection is finalized. Drafts are not sent.

Section 8 covers setting a webhook up.

8WebhooksAdmin

---

Instead of another system asking "anything new?" every few minutes, ShieldSphere tells it the moment something happens.

9Revoking and rotating keysAdmin

---

Turning a key off takes effect on the very next request. Do it without hesitating.

Revoke a key whenever it may have been exposed: a developer leaves, a laptop goes missing, a secret gets pasted into a chat or a support ticket. Revoking is instant and free. Leaving a questionable key alive is the expensive choice.

Revoked keys stay in the record rather than disappearing, so the history of what was issued and used survives. That is the same reasoning behind archiving rather than deleting documents in the Resource Library.

10Troubleshooting

---

What the symptom usually means, and what to do about it.

Symptom	Cause and fix
No Developers section in Settings	Either the Integration API is not enabled for your organization, or you are signed in as an administrator rather than the owner. Only the owner can issue keys. Contact ShieldSphere to have it enabled.
The other system reports "Invalid or expired API key"	One of four things: the key was mistyped, it was revoked, it passed its expiry date, or the Integration API was switched off for your organization. All four return the same message on purpose, so an attacker cannot learn which. Check the key list first - if the key is not there, it was revoked.
"This API key does not have the ... scope"	The key is valid but was not given that permission. Issue a new key with the right permissions ticked; permissions cannot be added to an existing key.
A location's records come back empty	The key is probably scoped to a different location. Check the Locations column in the key list. A scoped key sees exactly one site.
Two records were created instead of one	The other system retried a write without an idempotency key. Add one - see section 5. On an incident this also consumes an OSHA case number, so tell whoever maintains your 300 log.
Photo submission is refused	The photo URL must be HTTPS, publicly reachable, under 20MB, and must return the image directly. A link that redirects elsewhere is rejected, because a redirect can point somewhere the original link did not. Pre-signed storage URLs often redirect - resolve them first.
Hazard analysis never finishes	Check the job's status. "Dead" means it failed permanently and the reason is included - usually an unreadable photo or a location that could not be resolved. Resubmit after fixing the cause.
A webhook endpoint shows as paused	Deliveries failed repeatedly and it paused automatically. The panel names the last failure. Fix the endpoint, then click Resume - the secret does not change.
Webhooks are not arriving at all	Open the endpoint's Deliveries view. No entries means no matching event occurred, so check which events are ticked. Entries with error responses mean the events were sent and your server rejected them.
Records created in ShieldSphere never reach the other system	The webhook endpoint has Include records created in ShieldSphere switched off, so it hears only about records sent in through the API. Switch it on in the endpoint's row under Settings → Developers - see section 7.
A webhook arrives but fetching the record says "not found"	The API key cannot see that record: it lacks the Read permission for that kind of record, or it is limited to a different location. Issue a key with the right permissions and locations - see section 7.
A scheduled sync misses some records	Usually the sync saved its start time before the run finished, or it was saved from the end of the run instead of the start. See section 7, steps 2 and 4. Portal and chat incidents also stay out until a safety manager approves them.
Requests start returning "Rate limit exceeded"	The key exceeded its per-minute allowance. Reads and writes are counted separately. The response says how long to wait; a well-behaved integration backs off and retries.