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 pack, COMPANY and YOUR_INSTANCE should be the same thing.

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]
}

 

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.

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request