Integrating works management systems or mapping applications to SmarterWX Sentinel can give significant benefits in terms of accuracy and productivity, removing the need for users to manually copy site locations and job details into the BYDA referral service.
SmarterWX Sentinel provides two options for reducing the work required to lodge your enquiries: –
- Direct API Integration – Automated enquiry creation through direct API communication, bypassing user interface interactions.
- UI-Assisted Integration – Semi-automated enquiry lodgement with pre-populated fields in the BYDA interface, requiring user login, review and submission.
Pre-Requisite: Approval by BYDA for API Access
Access to the APIs for automating enquiry lodgement is controlled by BYDA. This approval step ensures that there is no misuse of the APIs either accidentally or deliberately.
You must be a BYDA member to use the APIs. If you are not already a member, please check out the membership page.
As an existing member, to request approval for the BYDA API access, please submit your request using this form.
Upon request, BYDA will grant access to a collection of users either by individual email addresses or for all users from a specific email domain (e.g. all users from @bobs-builders.com.au).
Choosing your Integration Method
There are two integration options for automating enquiry lodgement. The right one for you will depend on your relationship with the end user and the availability of information necessary to lodge the enquiry.
Direct API Integration
This method involves a seamless, automated process where your application directly interacts with the SmarterWX Sentinel REST API. Here, the application sends all required data, including an authenticated session token, to create an enquiry. The process occurs entirely in the background (“headless”), without any user interface interaction. The API then responds with the details of the successfully created enquiry. This option is ideal for systems seeking a fully automated, user-interface-free integration.
- Direct API Integration will lodge enquiries using the user account of the authenticated session. Your application will need to have an API key for each user that will be lodging enquiries. Your API key cannot lodge an enquiry on behalf of a different user.
- There is no need for user interaction. The enquiries can be lodged by a scheduler or background tasks.
- Direct API Integration requires that all the fields for the enquiry can be submitted to the API.
UI-Assisted Integration
This approach is more interactive. Your application triggers the SmarterWX Sentinel user interface, pre-loading it with necessary data for the enquiry. Users are prompted to log in if not already authenticated. Once logged in, they are directed to the enquiry lodgement screen with pre-filled information. The user then manually reviews and submits the enquiry by clicking on “Lodge Enquiry”. This method integrates automation with user oversight, ensuring that users can review and modify pre-populated data before submission.
- UI-Assisted Integration can be triggered by an approved API user. The enquiry will be lodged by whichever user is logged in to the browser application. This allows you to automate the lodgement process on behalf of a different user.
- UI-Assisted Integration will prompt the user to complete any fields that have not been pre-populated. For example, your application may not know the start/end dates for the job, so the user would enter these manually as part of the assisted lodgement flow.
This method is ideal if you are providing lodgement automation on behalf of your users but you do not have any access to that user’s BYDA account. The API keys used by your application are only used to start the process. Your user signs in to their BYDA account to finalise the lodgement of the enquiry.
Authentication
When making calls to the SmarterWX Sentinel API, your application will need an authenticated session token. Details on how to authenticate can be found here.
The access_token returned by the authentication step must be included in the Authorization HTTP Header on all subsequent calls to the API.
As described earlier (Approval by BYDA), the enquiry lodgement APIs can only be called by approved users. An HTTP status code of 401 (Unauthorised) will be returned if the user is not approved, or the approval has expired.
Preparing the Enquiry Data
In this section, each of the fields required to lodge an enquiry is described.
Invalid or missing values for the Direct API Integration method will result in an HTTP status code of 400 (Bad Request). When using the UI-Assisted Integration method, invalid or missing values will be addressed by the user before submitting the enquiry.
| Field | Field Name | Rules |
| Job Site Geometry | shape | The job site is submitted as GeoJSON polygon object. It must be within Australia’s borders and have an area no more than 20km2. |
| Job Site Address | Address | Only required for Direct API Integration. Automatically derived for UI-Assisted Integration. The locality, postcode and state must match the location of the Job Site Geometry. The first line of the address can be adjusted to best describe the job site (e.g. street address, intersection, lot/parcel numbers). |
| Address Line 1 | addressLine1 | Only application for UI-Assisted Integration. Overrides the automatically derived first line of address. For Direct API Integration, submit the Address object above. |
| Workplace Locations | locationTypes | These two fields are both arrays and are inter-related. locationTypes can be one or both of “Road Reserve” and “Private”. If locationTypes only contains Private, locationsInRoad is not required. If locationTypes contains Road Reserve, locationsInRoad must contain one or more of “Road”, “Nature Strip” and “Footpath”. |
| Job Start Date | digStartAt | Must be no earlier than today in ISO8601 date format. |
| Job End Date | digEndAt | Must be no earlier than digStartAt in ISO8601 date format. |
| Enquiry Type | isPlanningJob | true indicates this is a Planning/Design enquiry. false indicates this is an Excavation job. |
| Activities | activityTypes | An array of activityTypes that match the Enquiry Type. The available values are retrieved from the API via a GET /system/domains/{domain} request.For Planning/Design jobs use the domain ENQ_ACT_DESIGN. For Excavation jobs use the domain ENQ_ACT_EXCAVATE. |
| Working On Behalf Of | otherAuthorityName | This is a text string containing the name of the company that the work is being performed on behalf of. |
| Your Reference | userReference | A free text string containing a reference used to identify your job. (OPTIONAL – Max Length 100) |
| Notes | notes | A free text string containing notes that might be useful to asset owners to understand the work that is to take place. (OPTIONAL – Max Length 500) |
| Source | source | Should be the value “API” for Direct API Integration. Not required for UI-Assisted Integration. |
| Dry Run | isDryRun | If “true”, the request will be validated and an example response is returned but no enquiry is created and no credit is consumed. |
| Phone Number | phoneNumber | Only applies for UI-Assisted Integration. If present, and BYDA user profile does not have a phone number set, can used to populate the phoneNumber. Must be supplied in E.164 format. |
| Auto Submit | isAutoSubmit | Only applies for UI-Assisted Integration. If true, and all other values are present and valid, the UI will skip the user pressing the Lodge Enquiry button. |
Submitting an Enquiry for Direct API Integration
POST https://smarterwx.1100.com.au/api/enquiries
Refer to the Create Enquiry API documentation for specifics on the payload and responses for this API.
Rate Limit
There is a rate limit on lodging enquiries through this API. Excessive enquiry volumes will result in a HTTP Status Code 429 (Too Many Requests).
The current rate limit is a maximum of 90 enquiries per user in any 15 minute period.
Submitting an Enquiry for UI-Assisted Integration
POST https://smarterwx.1100.com.au/api/system/weblaunchers
Refer to the Add Web Launch Request documentation for specifics on the payload and responses for this API. The requestType is WEB_ENQUIRY_AUTOMATION.
This request returns an object containing two URIs.
- enquiryCreateUrl – The web page to open with the pre-populated enquiry information. Can only be used once.
- enquiryDetailUrl – The web page that a user can open to view the responses for their enquiry. Only valid if the user went ahead and submitted the enquiry.