Bring subscription information from a website using the API

Required access: Analytics and API token
Difficulty: Developer only!

This article is meant to guide a developer that wants to bring information from another system into Borealis. It gives examples on how to

Get the possible values for a drop-down menu
Create an individual stakeholder
Create a communication linked to the stakeholder just created

A good example of this is if you have a website where stakeholders can enter their information to subscribe to your newsletter, or a feedback section where stakeholders can ask questions or give comments. You want to push the information from this form to Borealis.

Before we start

Make sure you have a valid API token. This should be provided by your superuser.
You can find the API documentation here (https://COMPANY.boreal-is.com/api-docs/YOUR_INSTANCE/).
- Note: If you are not using a Corporate view add-on, COMPANY and YOUR_INSTANCE should be the same thing.

It is also important to understand that an API is a powerful tool that allows you to transfer information between systems. As such, security is important in keeping your data safe and additional steps should be taken to prevent potential data leaks. One such step is the addition of a reCAPTCHA to your page, which enables web hosts to distinguish between human and automated access to websites and prevent bots from spamming data at your API setup.

Get the possible values for a drop-down menu

Lots of fields in Borealis are drop-down menus. For example, a record needs to be linked to a Project (sometimes called Access rights). To access the list of possible values, you can make a call like this one:

Call

curl -X GET "https://COMPANY.boreal-is.com/api/v2/YOUR_INSTANCE/stakeholders_engagement~register~individuals/values/stkProjectMulti?limit=10&offset=0" -H "accept: application/json" -H "api_key: YOUR_API_TOKEN"

Response

{
  "total": 3,
  "data": [
    {
      "displayValue": "Mine site",
      "value": 1
    },
    {
      "displayValue": "Transmission line",
      "value": 2
    },
    {
      "displayValue": "General",
      "value": 3
    }
  ]
}

You can choose which value you want to add. The value will not change over time so you can set this up initially and not worry about it later.

Create an individual stakeholder

Here is an example for creating a stakeholder "Ms. Jane Doe".

You can find the API documentation for managing Individuals here: https://COMPANY.boreal-is.com/api-docs/YOUR_INSTANCE/stakeholders_engagement~register~individuals/

Creating a new record is a POST call with the following body:

{
  "baseCatIndividualTtlId": 7,
  "firstName": "Jane",
  "lastName": "Doe",
  "stkProjectMulti": [3],
  "onAddEmail": jane.doe@invalidemail.test,
  "onAddPhonenumber": "01 22 22 22 22",
  "onAddAddress": "1 Salmon Street",
  "onAddCity": "Magog",
  "onAddStateProvince": "Quebec",
  "onAddCountry": "Canada",
  "onAddPostcode": "J1X 1G8”
}

We used baseCatIndividualTtlId = 7 because in our case this is for "Ms.".

You can find many other fields that can be filled by using the API documentation.

Response

{
 "sysId": 33842
}

You can use it for the communication creation call.

Create a communication

Here is an example for creating the feedback for Ms. Jane Doe where she asked a question.

You can find the API documentation for managing communications here: https://COMPANY.boreal-is.com/api-docs/YOUR_INSTANCE/stakeholders_engagement~consultations~communications/

Creating a new record is a POST call with the following body:

{
 "stkMtSummaryNoHl": "I wanted to know if the street will still be closed next week-end. Please send me an email to confirm.",
 "importCommunicationDate": "2021-11-18",
 "baseStakeholderId": [33842],
 "stkMtTitle": "Question from the website",
 "baseProjectId": [3],
 "stkCatMeetingTypeId": 63
}

We used stkCatMeetingTypeId = 63 because in our case this is for Website questions.

You can find many other fields that can be filled by using the API documentation. The response will give you the system ID of the communication created.

Add your stakeholder to a distribution list

If you want to add your stakeholder to a distribution list, you need to create the distribution list before and find its identifier.

The system identifier can be deduced from the Ref. no. For example a Ref. no DL-00019 means the system identifier is 19.

Creating a new record is a POST call with the following URL (in this example the system identifier of the distribution list is 19):

https://COMPANY.boreal-is.com/api/v2/YOUR_INSTANCE/stakeholders_engagement~stk_administration_tools~distribution_lists/19/stakeholders

and the following body:

{
 "baseStakeholderIdAdd": [33842]
}

Create a Community contribution (Social investment)

Here is an example for creating the sponsorship of investment request that was sent through a website form.

You can find the API documentation for managing community contributions here: https://COMPANY.boreal-is.com/api-docs/YOUR_INSTANCE/social_investment~investment_portfolio~community_contribution/

Creating a new record is a POST call with the following body:

{
"title": "Sponsorship request",
"receptionDate": "2023-01-16",
"contributionContext": "Part of the program to improve the activity options at the school",
"followUpContact": 33842,
"contributionType": 3,
"requestedItemDescription": "Monetary contribution",
"siCatContribItemTypeId": 1,
"requestedItemValue": 5000,
"responsiblePerson": 11
}

We used

contributionType= 3 because in our case this is for "Sponsorship"
siCatContribItemTypeId = 1 because this is for monetary value
responsiblePerson = 11 because this is "Adam Paige", the person responsible for reviewing the sponsorship requests.

You can find many other fields that can be filled by using the API documentation. The response will give you the system ID of the community contribution created.

This covers the basis on how to call the Borealis API to bring data from a website. You can find more general information on the API in this article, and we also have an example on how to grab data from Borealis to bring to another system.

Related articles