Introduction - Guardhouse

The Guardhouse API gives external systems programmatic access to your incident reports, live operations, timesheets, staff, customers, sites, and webhook event subscriptions. It is a JSON REST API over HTTPS, secured with short-lived JWT bearer tokens that you obtain by exchanging an API key.

Base URLs

Use the base URL for your Guardhouse region:

Region	Base URL
AU	`https://gateway-api.guardhousehq.com`
UK	`https://gateway-api.guardhousehq.co.uk`

Authentication

All read endpoints expect a JWT bearer token sent as Authorization: Bearer <token>. Authentication is a two-step flow: 1. Obtain a token — POST your API key to POST /api/external/token/request:

POST /api/external/token/request
Content-Type: application/json

{
  "apiKey": "your-api-key-here"
}

A successful response returns an accessToken valid for 60 minutes:

{
  "status": { "code": 0, "errorMessage": "" },
  "data": {
    "accessToken": "<jwt>",
    "expiresIn": 3600,
    "tokenType": "Bearer"
  }
}

2. Send the token — include it as a bearer token on every subsequent request:

Authorization: Bearer <accessToken>

Re-issue a new token before it expires — there is no refresh mechanism.

Generating an API key

API keys are generated inside the Guardhouse web app. You need SuperAdmin access to do this.

Log in to the Guardhouse web app.
Go to Organization → Company Settings.
Open the Guardhouse API & Integrations tab.
Select the Guardhouse API sub-tab.
Find the API type you need and click Generate API Key:

API type	`KeyType`	Grants access to
Developer API	`developer`	Webhook subscriptions, staff, and developer endpoints
Live Operations API	`liveops`	Live Operations endpoint
Incident Reporting API	`incidentreport`	Incident report endpoints
Timesheet API	`timesheet`	Timesheet endpoints

The generated key is shown immediately in the field next to the button. Copy and store it securely — it is not shown again after you navigate away.

Request headers

Every API request requires two headers:

Header	Value
`Authorization`	`Bearer <accessToken>` — JWT obtained from `POST /api/external/token/request`
`external-gh-apim-sub-key`	Guardhouse API Management subscription key — contact Guardhouse Support for the subscription key

Scopes and key types

Every API key is issued with a KeyType that controls which endpoints it can call:

`KeyType`	Endpoints
`incidentreport`	All `/api/external/incidentreport` and `/api/external/incidentreports/` endpoints
`liveops`	Live Operations endpoint
`developer`	All `/api/webhook/` endpoints and all `/api/external/staffs` endpoints
`timesheet`	`/api/external/timesheets`, `/api/external/timesheets/{id}`, and `/api/external/timesheets/{id}/rates`

All Staff endpoints (/api/external/staffs*) require a developer API key. The remaining read endpoints (/api/external/customers, /api/external/sites) require any authenticated Public key. All are scoped by your CompanyId, CustomerId, and SiteId claims. Calling an endpoint with the wrong KeyType returns 403 Forbidden. Keys are also scoped by CompanyId, CustomerId, and SiteId claims — passing IDs outside that scope is also rejected with 403.

Response envelope

Every JSON endpoint returns the same wrapper:

{
  "status": { "code": 0, "errorMessage": "" },
  "data":   { /* endpoint payload */ },
  "count":  null,
  "message": "",
  "errors": []
}

Paginated incident-report endpoints add full cursor metadata:

{
  "status":            { "code": 0, "errorMessage": "" },
  "data":              [ /* items */ ],
  "recordCount":       100,
  "totalRecordCount":  4823,
  "prevPageEndpoint":  null,
  "prevPageParams":    null,
  "nextPageEndpoint":  "/api/external/incidentreports/getall",
  "nextPageParams":    "direction=next&referenceId=8429"
}

The newer paginated endpoints (/api/external/timesheets, /api/external/staffs, /api/external/customers, /api/external/sites) use a slimmer cursor envelope:

{
  "status":             { "code": 0, "errorMessage": "" },
  "data":               [ /* items */ ],
  "nextPageParameter":  "direction=next&referenceId=8429",
  "prevPageParameter":  null
}

The Live Operations endpoint uses its own envelope with isSuccess, numeric status, statusMessage, errorMessages, and errorMessagesAsString fields. See the Errors guide for the meaning of status.code and the shape of the errors array.

Pagination

List endpoints use cursor-based pagination. To page forward:

Issue the initial request with direction=next (the default).
Read the last item’s identifier from data (typically incidentReportId).
Pass that value as referenceId on the next request, keeping direction=next.

To page backward, set direction=prev and pass referenceId from the first item. The response’s nextPageParams and prevPageParams give you the exact query string to use for the next call — you can append them directly to the endpoint URL.

Rate limits

External and webhook endpoints are limited to 60 requests per minute per API key. Requests beyond the limit return 429 Too Many Requests. The token-issuance endpoints (/api/token/*) are not rate-limited.

Webhooks

If your KeyType=developer key is provisioned, you can register subscribers and event subscriptions so Guardhouse pushes notifications to your systems when reports or timesheets change. See the Webhooks guide for the registration flow, signature validation, and the supported event catalog.

​Base URLs

​Authentication

​Generating an API key

​Request headers

​Scopes and key types

​Response envelope

​Pagination

​Rate limits

​Webhooks