What is the Borealis API? When and how should I use it?
Date: July 21, 2021
Required Access: Superusers
The Borealis API is a powerful tool that lets you put all of your applications to work for stakeholder engagement. That might sound daunting, but it’s actually quite simple to use! Let’s take a look at how to put the API to work for you.
What is the Borealis API?
The API (which stands for “Application Programming Interface”) allows you to connect Borealis to the other tools you use to make sure you’re always working with complete data. This includes social media (Facebook, Twitter or LinkedIn), Customer Relationship Management Systems, Geographic Information Systems (GIS), Content Management Systems (WordPress, Drupal), and more.
What are the benefits of using the API?
All of your data in Borealis can be transferred to other applications. Once you connect your applications through the API, your data entries will be automatically synced across systems. Here are a few examples:
Social media platforms
Push important social media publications to Borealis as communications to link them to your important stakeholders and engagement plans. Create custom dashboards to monitor daily, monthly, and weekly posts.
CRMs
Create a new entry in your CRM and push it automatically to Borealis. Any fields that are added or updated in the CRM will be automatically updated and mapped to the relevant fields in Borealis accordingly. You can also set it up the other way and push new stakeholders from Borealis into your CRM.
GIS databases
Transfer georeferenced data from your GIS systems to Borealis to give users a visual representation of assets and stakeholders on the Borealis map. This makes it easier to plan engagement strategies, or link grievances to a particular project site or asset.
Content Management Systems
Quickly generate an interface that lets stakeholders contact the organization without going through an agent or call center. Create forms in your CMS to collect information from stakeholders and then import the records directly into Borealis.
For more information, you may find this article helpful.
Is the API Secure?
Yes, it is! The Borealis API uses the same level of security as the web interface. All data is encrypted during transit and authenticated using a “token” that works like a password. User access to the API can be controlled by assigning access rights, just like in other parts of Borealis, and an expiration date can be added to a specific token as desired. This ensures that users can only access the information they are authorized to see.
Should my organization use the Borealis API?
- Do you need to enter external data in Borealis [and/or] Do you need to send data from Borealis to another system?
- Do you add or modify data at least once a month [and/or] do you need to create or update a lot of data?
- Does manual data entry take a lot of time, and does that data potentially already exist in another platform?
If you answered YES to one or more of these questions, the API might be just the solution you need!
How Do I Connect Borealis to Another System?
If you would like to set up the Borealis API, please be aware that the integration takes two days of service. It may take longer if you have a lot of custom requirements.
Our API documentation makes it simple for your IT team to connect Borealis to other systems you’re using. The documentation is not available by default; you will need to create an access token in order to view it.
Creating the Access Token
Here's how you can generate the token you need to access the documentation (please refer to this Help Center article for more information):
- Open the record for the user you’d like to grant access.
- Click on the "Access token" tab. (API documentation is not available if no token is active)
- Use the "+" green button to add a token. Simply enter a name for the token, an expiration date (optional), and click save.
Setting Up the API
Once you have access to the API documentation, here are the steps your organization needs to take:
- Analyze and identify optimal integration processes.
- If data will be sent from Borealis to another system, we will create an Analytics widget to simplify the data transfer.
- Your IT team (or selected contractor) will need to develop the connector, and we will communicate with them to help them do so. We may make minor improvements to some API endpoints to simplify the integration.
- Once the development has been finalized, we can meet with your IT team (or chosen contractors) again to develop automated tests that will ensure a robust connection going forward.
The Importance of Proper Configuration
Automatically importing data from outside sources can save you a lot of time, but it's important to remember that it does pose some risks. If your connection is not configured properly, you could end up importing or updating the wrong data in Borealis. Before you consider implementing the API, it's important to make sure you have the necessary support and engagement from your IT team.