Skip to content

Migrating to BI endpoints version 2

We created a new version for BI endpoints to provide a more consistent and faster endpoint. Minor breaking changes are present and this guide provides you help to upgrade your existing integration.

Changes

The key changes are:

  • The endpoint is now /v2/bi/ instead of /bi/
  • All properties are now camelCase, always starting with a lowercase letter.
  • "modifiedAfter" correctly returns the last modified date of the object. It was previously returning the creation date.
  • Different order for the data. The ordering for the data can be different since we are applying more efficient ordering to it.
  • Different logic for pagination.

Since all properties are now camelCase, tools like PowerBI will have issues with the migration. You need to change the properties in PowerBI where stated in uppercase to lowercase. Those are:

  • FirstSurveyExposure
  • Custom
  • AdditionStatus

ModifiedAfter filter parameter

The "modifiedAfter" parameter now correctly returns objects based in their last change. It was previously returning based on the creation date, which was inconsintent with the parameter name. There is a limitation with this filter - The modification date is beign tracked only from 01/09/2022. If you need to retrieve data from before this date, you need to use the alternative date parameter to the method.

ApiKey

No changes are required for the ApiKey. The same key can be used for the new version.

Endpoint

The endpoint is now /v2/bi/ instead of /bi/. The old endpoint will be deprecated in the future.

All methods are still the same, with the same parameters. The only difference is the endpoint prefix.

So, the previous endpoints:

  • /bi/campaignmembers
  • /bi/responses
  • /bi/responsecategories
  • /bi/sms
  • /bi/emails
  • /bi/companies
  • /bi/employees

Are now:

  • /v2/bi/campaignmembers
  • /v2/bi/responses
  • /v2/bi/responsecategories
  • /v2/bi/sms
  • /v2/bi/emails
  • /v2/bi/companies
  • /v2/bi/employees

Pagination

There is a limit for 300,000 records per request. If you need to retrieve more records, you need to use the pagination.

IF THE TAKE PARAMETER IS BIGGER THAN THE MAXIMUM OF 300000 AN ERROR WILL BE THROWN.

As before, the pagination is done using the skip and take parameters. Skip is not required but it is required to provide the take parameter.

"adminComment" and "adminCommentBy" in Responses model

Update (22-08-2023): adminComment and adminCommentBy were restored with previous behaviour. When more than one comment exists, they will be joined by '; '.

As we made changes in the way we store comments, the "adminComment" and "adminCommentBy" in "Responses" model only returns old comments from old responses. This is due to the fact that we are not storing the comments in the same way as before, where only one comment was possible to be added and now, we can add multiple comments to a campaign member.