Introduction #

Application programming interfaces (a.k.a. APIs) are the means by which IT systems can talk to each other. They convey information and events from one system to another, or make it possible for one system to query another for information,  allowing the other system to react and respond or further process the information and events detected, and data collected or produced by another system.

The primary purpose of APIs is to break down silos and enable the seamless integration of otherwise isolated systems. By fostering such integrations, organizations can substantially reduce manual effort, streamline and automate key processes, minimize human error, and enhance overall responsiveness.

Secapp APIs in a Nutshell #

The APIs are based on REST principles. To call an API you make (or receive, more about this later) an http request to a URL. In return, you get (or send) an http response with the necessary information traveling in the payload JSON.

For security reasons, https is required so that the data traveling over the connection is encrypted while in transit.

For those not familiar with JSON, JSON (JavaScript Object Notation) is a lightweight text-based format used to store and exchange data between systems in a way that is both  human and machine-readable. 

For authentication, the APIs use API keys carried in the request headers.

Currently available APIs are shortly introduced here. If, however, none of these APIs match your needs, it is also possible to develop additional APIs. 

Messaging #

The messaging features of the API allows external applications to send and receive messages, and follow up responses to them. So, when you send or receive a message/messages, you will receive an ID for each message. Using those IDs you can then request the system to return up-to-date response counts or complete response information (user name of the respondent, OK/NOK, timestamp for the response etc.). 

The messages sent using the API are first delivered to the so called routing engine in Secapp. This engine checks if the sender (when applicable) is allowed, then optionally checks the existence of specific keywords in the message and if matches are found, triggers a message based on a message template configured for the keywords. The message generated can include the original message content delivered over the API, and additional content (text, attached files) can be added in the template. The template also defines the message distribution: To whom it is sent and which channels are used. Defining these things in templates is handy especially if you have limited access or capabilities to modify the sending systems behavior: Any distribution changes, escalation rule changes etc. can be done in Secapp UI without any need to modify the code or configuration of the sending system.

For receiving messages in an external system, Secapp provides an outbound webhook that can be configured to make an http request to a URL in an external system for every message sent based on a specific message template (not limited to a single template. If necessary any or all templates can include webhooks.). A template can include several webhooks and they all will be triggered when the message is sent. The JSON payload of the http request includes the message content (in all languages if provided) and other details – such as channels used and timestamps for sending – that the external system can then process further.

Use case examples

• IT system or Security system alerts: When monitoring system detects faults or anomalies in network or IT system operation, it alerts response team using Secapp. Should the problem be serious, the information is also delivered by Secapp to the top management at the same time. Secapp alerts are particularly useful when serious incidents occur outside regular office hours and off-duty personnel needs to be brought in.
• Alerts from building automation or process control are delivered to field workers 
• Alerts or incident advisories are posted by Secapp to information display systems as well.
• External situation awareness system receives alerts and retrieves responses from Secapp to complement the situational picture.

User management #

User management API gives you full control over users of the system. With it, you can retrieve a list of users in the system, add new users, update user data/settings of already existing users and remove users from the system. It is also possible to define which groups the user belongs to as well as remove the user from one or multiple groups.

Use case examples:

• Create Secapp accounts to users based on their data in your central HR or IT system, also synchronizing changes to keep information up-to-date, and removing users that left the company.
• The visitor information system of an industrial area registers visitors to Secapp and specific groups so that they will receive local alerts. Registrations are removed when visitors are leaving the area.

In addition to the proprietary Secapp API for user management, Secapp also supports SCIM 2.0 interface for user management. While primarily intended to be used with Microsoft Entra ID to synchronize user data between Entra ID and Secapp, it can also be enabled to be used by other systems for user data management. After all, SCIM is also based on REST principles, just like the proprietary API as well.

However, the Secapp API gives finer and wider access to user settings and their control, while SCIM supports a more limited subset of settings for a user.

Group management #

The API gives you access to groups in the system. Over the API, it is possible to discover what groups you have in the system, who (users or groups) belong to a group, add and remove users and groups from groups, and also delete an entire group. Note that the API operates on groups only, so if you delete a group, just the group will disappear from the system. The users that were members of the group will remain in the system. 

Use case examples

• Use HR/Shift management software to update a group at a shift change.  Example, your ER team always receives alerts in EMG – Trauma group, but the people that form the Trauma Team change every time a shift changes 
• Automatically add/remove personnel from groups when they join/leave the company.

Statistics #

The system also records periods when the lone worker feature has been active, i.e. the periods when the counter has been set running/stopped. 

These statistics are available over the API as well, and they are often used to demonstrate regulatory compliance in occupational safety measures.

This data is only kept by Secapp for 60 days (default) after which it is removed. Should you need data to be kept for shorter or longer periods, please contact Secapp support.

Reporting and documentation #

Secapp reporting and documentation features let you 

• manage and track work/tasks, and orders/invoices related to them
• provide checklists for specific tasks or procedures
• Collect information using reports and questionnaires for any purpose
• Manage sites and assets in them
• And a lot more…

In case you wish to find out more, please take a look at https://www.secapp.fi/product/checklists-and-operating-critical-infra/

Through APIs, external systems can query and fetch job packages/work orders with status and their tasks, billable items (work or material) in them and site/asset information. External systems can then further process this to be used as input for example for accounting or maintenance management systems.

Files #

In Secapp mobile application there is also a Files section that can be used to distribute files to users so that they are also available even if the device is offline. Typically files shared this way are something that must remain available at all times, even (sometimes particularly) during major incident and crises: Evacuation instructions, emergency procedures, evacuation route maps and muster points etc.

If you have a so-called single source of truth, a place where  a set of latest versions of “always available” documents are stored, Secapp can now automatically synchronize the files from that source. 

To synchronize, you need to arrange SFTP access to your files. Secapp can then be configured to retrieve the files from your SFTP server. 

Once the interface is enabled, you can configure the server address in Secapp and the keys needed for the transfer. The transfer runs automatically once a day and synchronizes the files and folder structure with the Secapp Files section.

Getting Started #

To begin working with our APIs, we recommend contacting our sales team to discuss your specific integration needs.

Secapp will provide the necessary access credentials, with the exact delivery method agreed on a case-by-case basis depending on the preferred communication channels. As the credentials are security-sensitive, they should always be handled with appropriate care and confidentiality.

Typically, development begins in a dedicated test environment, allowing you to explore and validate functionality safely before moving to the production system. As part of the setup process, please collect and share key technical details such as the IP address of the systems or applications that will be calling the API. It is also important to estimate your expected level of usage — including the approximate number and frequency (including possible peaks) of API calls — so we can ensure optimal performance, plan capacity effectively, and tune our rate limiters appropriately for your traffic. While API and test system access can usually be granted within a few days, real-world experience has shown that making the full end-to-end solution production-ready often takes longer. Although Secapp data becomes available quickly, the subsequent integration work, data processing, and implementation required to make the results available in the target system typically extend the overall project timeline.

Alternative methods for integration #

While not discussed in this document, there are alternative integration methods available as well, in case the APIs are not fit for your use case.

Messaging #

• SMS: Short messages (SMS messages) can be sent to Secapp and used to trigger an alert based on a predefined template. Also, Secapp can be configured to send an SMS to a specific number(s) whenever an alert is sent.
• Email: An email can be sent to Secapp, triggering an alert based on a predefined template. Also, Secapp can be configured to send an email to an external address whenever an alert/message is sent.

Incoming messages from both channels mentioned above are actually delivered to the same routing engine as mentioned in connection with messaging API. Thus, they include filtering based on allowed senders and keywords.

Otherwise, the capabilities in both SMS and email based integration are fairly limited compared to messaging API capabilities However, they offer a low-threshold alternative for integration, typically in cases where the sending system does not support API based approach and/or you have no access to it nor capabilities to develop API based integration.

User management #

• MS Entra ID: There is also a MS Graph API based implementation available for MS Entra ID to synchronize user data between systems. 

However, we recommend SCIM to be used instead for all new implementations as it gives customers better control on information that is accessible by the integration.

Custom Integrations #

We strongly encourage using the ready-made APIs available in Secapp for integration. That is a fast and cost effective solution compared to development of custom APIs or integrations. However, we are aware that this is not always possible for a variety of reasons. Thus, should you need something that is not addressed by the current APIs, please contact us anyway. Secapp regularly implements custom integrations, so let’s talk and see how your challenges can be solved.

Closing Note #

We hope this overview has illuminated the power and flexibility of Secapp APIs in enhancing your operational efficiency and data exchange. We encourage you to reach out to our sales team today to explore how these APIs can be used for your specific needs and help you unlock the full potential of your Secapp service and integrated systems.