API docs by Redocly

Site App Pro (1.0.0)

Download OpenAPI specification:

E-mail: support@siteapppro.co.nz License: Apache 2.0 Terms of Service

This is the API to interact with Site App Pro.

  • You can find out more about Site App Pro at https://www.siteapppro.co.nz.
  • API calls are authenticated with Firebase uid and Firebase token header parameters.
  • Dates and times are always in epoch milliseconds (see Date & Time Format below).

Date & Time Format

All dates and times in this API — in both requests and responses, e.g. answerDate, whenCreated, whenLastModified, from, to — are represented as epoch milliseconds: the number of milliseconds elapsed since the Unix epoch (00:00:00 UTC on 1 January 1970 — see Unix time). This value is always UTC, so there is no separate time zone offset to account for.

For example, 1770152764556 corresponds to 2026-02-03T21:06:04.556Z.

Most languages provide a built-in way to convert this value to a native date/time object, for example:

  • JavaScript: new Date(1770152764556)
  • Python: datetime.fromtimestamp(1770152764556 / 1000, tz=timezone.utc)

Rate Limiting

To ensure stability and fair usage, this API enforces rate limiting based on a token bucket algorithm.

Limits are governed by two factors: a steady-state request rate (requests per second) and a maximum burst capacity. If you sustain a traffic volume higher than the allowed rate, or if you send a sudden spike of traffic that exceeds the burst capacity, the API will reject the excess requests and respond with an HTTP 429 Too Many Requests status code.

We strongly encourage all clients and automated integrations to implement exponential backoff with jitter when handling 429 responses. Attempting to immediately retry failed requests without a delay queue will result in sustained rejections and degraded performance.

SiteAppPro

API to interact with Site App Pro

Find out more

newStaff

A new Staff record has been created in your Site App Pro Organisation. Webhook

Informs webhook listener (i.e. subscription target URL) that a new Staff record has been created.

header Parameters
X-Hook-Signature
required
string

The HMAC-SHA1 signature of the raw request body, generated using the system-provided X-Hook-Secret as the cryptographic key, and formatted as a hexadecimal digest.

Request Body schema: application/json
payload
required
string

A new Staff record, a new Site, updated Site or a completed Form instance

required
object (WebSubscriptionHook)

Responses

Request samples

Content type
application/json
{
  • "payload": "A new Staff record, a new or updated Site record or a completed Form instance",
  • "hook": {
    }
}

newSite

A new Site has been created in your Site App Pro Organisation. Webhook

Informs listener (i.e. subscription target url) that a new Site has been created.

header Parameters
X-Hook-Signature
required
string

The HMAC-SHA1 signature of the raw request body, generated using the system-provided X-Hook-Secret as the cryptographic key, and formatted as a hexadecimal digest.

Request Body schema: application/json
payload
required
string

A new Staff record, a new Site, updated Site or a completed Form instance

required
object (WebSubscriptionHook)

Responses

Request samples

Content type
application/json
{
  • "payload": "A new Staff record, a new or updated Site record or a completed Form instance",
  • "hook": {
    }
}

updatedSite

A Site has been updated in your Site App Pro Organisation. Webhook

Informs listener (i.e. subscription target url) that a Site has been updated.

header Parameters
X-Hook-Signature
required
string

The HMAC-SHA1 signature of the raw request body, generated using the system-provided X-Hook-Secret as the cryptographic key, and formatted as a hexadecimal digest.

Request Body schema: application/json
payload
required
string

A new Staff record, a new Site, updated Site or a completed Form instance

required
object (WebSubscriptionHook)

Responses

Request samples

Content type
application/json
{
  • "payload": "A new Staff record, a new or updated Site record or a completed Form instance",
  • "hook": {
    }
}

completedFormInstance

An instance of a Form has been completed in your Site App Pro Organisation. Webhook

Informs listener (i.e. subscription target url) that a Form Instance has been completed.

header Parameters
X-Hook-Signature
required
string

The HMAC-SHA1 signature of the raw request body, generated using the system-provided X-Hook-Secret as the cryptographic key, and formatted as a hexadecimal digest.

Request Body schema: application/json
required
object (CompletedFormInstancePayload)

The completed Form Instance, plus a temporary link to its generated PDF report.

required
object (WebSubscriptionHook)

Responses

Request samples

Content type
application/json
{
  • "payload": {
    },
  • "hook": {
    }
}

formInstances

Retrieve a list of Form Instances.

Returns an array of completed and incomplete form instances for the authenticated organisation.

Authorizations:
(firebaseTokenfirebaseUserId)
query Parameters
from
integer <int64>
Example: from=1770083945000

Filter forms submitted from this date (in epoch milliseconds).

to
integer <int64>
Example: to=1770152764000

Filter forms submitted up to this date (in epoch milliseconds).

category
string
Example: category=Others

Filter by form category.

name
string
Example: name=Example Form

Filter by exact form name.

header Parameters
x-organisation-id
required
string

Specifies the target Organisation ID for the request context.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

users

Add a new User to your Site App Pro Organisation.

Create a new user in your organisation.

Authorizations:
(firebaseTokenfirebaseUserId)
header Parameters
x-organisation-id
required
string

Specifies the target Organisation ID for the request context.

Request Body schema: application/json
required

User to be added to your Organisation

firstName
required
string
lastName
required
string
email
required
string

Responses

Request samples

Content type
application/json
{
  • "firstName": "First name",
  • "lastName": "Surname",
  • "email": "admin@example.com"
}

Response samples

Content type
application/json
{
  • "firstName": "First name",
  • "lastName": "Surname",
  • "email": "admin@example.com",
  • "roleName": "Tablet",
  • "externalId": "ExtId",
  • "organisationId": 1234,
  • "organisationName": "Org Name",
  • "organisationGroupName": "Org Group Name",
  • "whenCreated": 0
}

sites

Adds a new Site to your Site App Pro Organisation.

Adds a new Site to your organisation.

Authorizations:
(firebaseTokenfirebaseUserId)
header Parameters
x-organisation-id
required
string

Specifies the target Organisation ID for the request context.

Request Body schema: application/json
required

Site to be added to your Organisation

name
required
string
isActive
boolean
category
string
address
string
latitude
number <float>
longitude
number <float>
email
string
phoneNumber
string
contactName
string
projectManager
string
safetyManager
string
notes
string
externalId
string
scheduledStartDate
integer <int64>
scheduledEndDate
integer <int64>
status
string

Responses

Request samples

Content type
application/json
{
  • "name": "SiteName",
  • "isActive": true,
  • "category": "siteCategory",
  • "address": "Auckland",
  • "latitude": 0.1,
  • "longitude": 0.1,
  • "email": "site@example.com",
  • "phoneNumber": "021123456",
  • "contactName": "Site Contact",
  • "projectManager": "Site Project Manager",
  • "safetyManager": "Site Safety Manager",
  • "notes": "Notes",
  • "externalId": "Site External Id",
  • "scheduledStartDate": 0,
  • "scheduledEndDate": 0,
  • "status": "Status"
}

Response samples

Content type
application/json
{
  • "name": "SiteName",
  • "organisationId": 1234,
  • "isActive": true,
  • "category": "siteCategory",
  • "address": "Auckland",
  • "latitude": 0.1,
  • "longitude": 0.1,
  • "email": "site@example.com",
  • "phoneNumber": "021123456",
  • "contactName": "Site Contact",
  • "projectManager": "Site Project Manager",
  • "safetyManager": "Site Safety Manager",
  • "notes": "Notes",
  • "externalId": "Site External Id",
  • "scheduledStartDate": 0,
  • "scheduledEndDate": 0,
  • "status": "Status",
  • "formCompletionEmailList": "Notes",
  • "whenCreated": 0,
  • "createdByUserId": 0,
  • "whenLastModified": 0,
  • "lastModifiedByUserId": 0,
  • "whenArchived": 0,
  • "archivedByUserId": 0,
  • "whenDeleted": 0,
  • "deletedByUserId": 0,
  • "parentId": 0,
  • "pin": "1234",
  • "reportFooter": "Footer",
  • "pcbuOption": "",
  • "counterContact": "",
  • "counterBusinessName": "",
  • "counterPhoneNumber": "",
  • "firstAidContact": "",
  • "notifiableWorks": "",
  • "taskAnalysis": "",
  • "accidentReporting": "",
  • "hazardousSubstances": "",
  • "trainingCompetency": "",
  • "subcontractors": "",
  • "environmentNeighbourhood": "",
  • "communications": "",
  • "pinnedInitialFormIds": "",
  • "agreementSummaryLastModified": 0,
  • "notifiableWorksLastModified": 0,
  • "taskAnalysisLastModified": 0,
  • "accidentReportingLastModified": 0,
  • "hazardousSubstancesLastModified": 0,
  • "trainingCompetencyLastModified": 0,
  • "environmentNeighbourhoodLastModified": 0,
  • "communicationsLastModified": 0,
  • "siteCode": "",
  • "siteClosedTime": "",
  • "latestCheckOutNotificationTime": 0,
  • "entryNotes": "",
  • "outlineOfWork": "",
  • "otherTaskAnalysis": ""
}

Archives Sites in your Site App Pro Organisation.

Archives Sites in your Site App Pro Organisation.

Authorizations:
(firebaseTokenfirebaseUserId)
header Parameters
x-organisation-id
required
string

Specifies the target Organisation ID for the request context.

Request Body schema: application/json
required

Site to be archived in your Organisation

One of
siteId
required
integer

The internal Site App Pro ID.

Responses

Request samples

Content type
application/json
{
  • "externalId": "foo-bar-123456"
}

Response samples

Content type
application/json
1

subscriptions

Create a Webhook subscription.

Registers a new webhook subscription. The user and organisation IDs are dynamically derived from your authentication token.

Activating your subscription

Immediately after this call succeeds, we send a one-time handshake request to your targetUrl to confirm it is ready to receive events. This handshake is not retried, so your endpoint must already be live and reachable before you call this operation, or the subscription will never activate.

  1. We send a POST to your targetUrl with an X-Hook-Secret: <uuid> header and Content-Type: application/json, but no body. Your endpoint must not reject the missing body.
  2. Your endpoint must respond with an X-Hook-Secret header. We only check that the header is present, but you should echo back the exact value we sent.
  3. Any HTTP status code activates the subscription; 200 is the recommended response.
  4. Store the secret so you can validate that later webhook deliveries genuinely come from us. It is also returned as the xHookSecret field (and the X-Hook-Secret response header) on the create call itself.

If the handshake can't reach your endpoint, the subscription stays inactive and no webhook events will be delivered. Create a new subscription once your endpoint is ready.

Authorizations:
(firebaseTokenfirebaseUserId)
Request Body schema: application/json
required

Webhook REST subscription.

event
required
string
targetUrl
required
string
userEmail
required
string

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Create or update a Webhook subscription by ID.

Updates an existing webhook subscription. The user and organisation IDs are dynamically derived from your authentication token.

Authorizations:
(firebaseTokenfirebaseUserId)
path Parameters
id
required
integer <int32>

ID of the webhook subscription.

Request Body schema: application/json
required

Webhook REST subscription.

event
required
string
targetUrl
required
string
userEmail
required
string

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}