Migrating from Stems One API v1.3

The intent of this Migration Guide document is to help existing businesses seamlessly port their integrations with Stems One API v1.3 to Stems One API v1.4.

Stems One API v1.4 introduces breaking changes on Event sections.
There is a big change in how the Event data is entered to the system. This new version adds the ability to allow more customisation on existing Event Forms (injury, damage, environment, nearmiss, and custom). To cater for this, a new endpoint is created to retrieve fields available for every Event Forms. The previous customisation data returned under Lookup endpoint is now obsolete. There are also a couple of field renaming on this version, which is required to match the update performed in Stems One application.

1. Breaking Changes

Please check changes described below and update your integration accordingly.

Endpoint Breaking Change Version Introduced
POST /events/requireapproval The following Fields under eventDetails object are renamed on both request and response data.

  • eventGroupId is renamed to eventFormId
  • title is renamed to subheading
  • description is renamed to additionalInformation
  • checklists is renamed to selectedChecklists
  • questionnaires is renamed to questionnaireAnswers and the field is now expecting different data


The following Fields are added under eventDetails object on both request and response data.

  • freeText1
  • freeText2
  • freeText3
  • freeText4
  • freeText5
  • freeText6
 v1.4.0
PUT /events/{id}/requireapproval Please refer to POST /events/requireapproval endpoint changes above v1.4.0
GET /events/{id}/groups This endpoint is now renamed to GET /events/{id}/forms

The following fields are renamed on response data

  • title is renamed to subheading.
  • description is renamed to additionalInformation.
 v1.4.0
GET /events/lookup The following fields are renamed on response data

  • eventRecordGroups is renamed to eventRecordForms.
  • Under eventRecordForms object, groups is renamed to forms.
  • eventGroupTypesCategories is renamed to eventFormTypesCategories.
  • Under eventFormTypesCategories, eventGroupId is renamed to eventFormId and eventGroupName is renamed to eventFormName.


The following Fields are added on response data.

  • questionnaireItemTypes. This data is required for new customisation introduced in this version.


The following Fields used in previous customization are now obsolete and removed on response data. Please use GET /events/formDesignData for form customization.

  • customizedEventFormSettings
  • customizedEventChecklists
  • customizedEventQuestionnaires
 v1.4.0
GET /events/approvalData This endpoint is removed. Please use GET /events/includerequireapproval instead. v1.4.1
POST /events This endpoint is repurposed to insert event data without approval process. Please use POST /events/requireapproval if migrating from version 1.3. v1.4.1
PUT /events This endpoint is removed. Please use PUT /events/{id}/requireapproval if migrating from version 1.3. To updating event data without approval process, please use the new PUT /events/{id} endpoint. v1.4.1

2. Extended Endpoints

Below are endpoints which had new fields/parameters in their request/response data in this version.

Endpoint Description Version Introduced
GET /hazards/includerequireapproval Input parameter 'q' is extended to search text occurences in hazard id v1.4.1
GET /events/includerequireapproval Input parameter 'q' is extended to search text occurences in event id v1.4.1

3. New Endpoints

Below are new endpoints created.

Endpoint Description Version Introduced
GET /events/formDesignData Retrieve field customization for Event Forms (previously called Event Groups). This endpoint is replacing field customization data returned from GET /events/lookup endpoint in previous versions. v1.4.0
PUT /events/{id} Update event data without approval process. v1.4.1
GET /hoursworked Retrieves hours worked data v1.4.1
GET /hoursworked/total Retrieves total hours worked monthly v1.4.1
POST /hoursworked/personnel Insert personnel hours worked data v1.4.1
POST /hoursworked/bulk Insert bulk hours worked data per organisation structures v1.4.1