Work with the Sitefinity Insight API

Get started

To start using Sitefinity Insight data collection and personalization API, you first need to have:

  1. A Microsoft account, which is provisioned in Insight.

    NOTE: If you do not have a Sitefinity Insight account, contact sitefinitysales@progress.com.

  2. Accepted Insight terms and conditions.
    You can do this in one of the following ways:
    • Log into Sitefinity Insight with your Microsoft account.
    • Use the Insight API.
      For details, see the Accept terms and conditions section in this article.
  3. Access to at least one Insight data center.
    To do this, you need to obtain the data center API key. For more information, see the Obtain the API key of a data center section in this article.

    NOTE: If you do not have an Insight account, contact sitefinitysales@progress.com for information about getting a trial version of Insight, as well as purchasing Insight licenses.

Next, you can proceed with getting your authorization token and obtaining the data center API key. You will need both to use the most of Insight endpoints.

Accept terms and conditions

By calling the following endpoint, you agree to the latest Insight terms and conditions.

NOTE: To get the full text of the terms and conditions, see Progress Sitefinity Insight agreement.

Resource information

URL https://api.dec.sitefinity.com/admin/v1/users/accept-terms-and-conditions
HTTP method POST
Description Accepts the latest Insight terms and conditions on behalf of the authorized user.
Authentication Required

Parameters

Name Location  Required Data type

Description

Authorization Header Yes String The access token of the user

Request body

Body is not required.

Responses

Name Returned data Description
200 OK User
For more information, see User API data types.
Terms and conditions are accepted successfully.
401 Unauthorized 'Unauthorized' Returned when an invalid or expired token is provided in the Authorization header.

Sample request

HTTP:

POST https://api.dec.sitefinity.com/admin/v1/users/accept-terms-and-conditions

Sample response

Authorization

Authorization token with access key

To use the secured Insight endpoints, you need to obtain an authorization token. The recommended way of obtaining an authorization token is by using an access key. The token is obtained by calling the endpoint resource described in details in this section. The authorization token with access key is valid for 60 minutes. For more information, see Access keys.

Resource information

URL https://api.dec.sitefinity.com/admin/v1/access-keys/issue-access-token
HTTP method POST
Description Returns a short-living authorization token for the provided access key to be used when calling secured DEC endpoints.
Authentication None

Parameters

No parameters are required for this endpoint.

Request body

Name Required Data type Description
AccessKey Yes String The access key token

Responses

Name Returned data Description
200 OK AccessKeyAuthenticationServiceResponse
For more information, see AccessKeyAuthenticationServiceResponse.
The access key was accepted by the authentication service. The details, including the authorization token and its type, along with the access key details are provided.
401 Unauthorized GeneralErrorResponse
For more information, see General error response.
Returned when the provided access key is invalid or deactivated.
400 Bad Request GeneralErrorResponse
For more information, see General error response.
Usually returned when the JSON in the request body has invalid or missing properties.
412 Precondition Failed GeneralErrorResponse
For more information, see General error response.
Usually returned when an empty body is JSON is passed.

Sample request

HTTP: 

POST https://api.dec.sitefinity.com/admin/v1/access-keys/issue-access-token

Body JSON:

{

    "AccessKey": "    eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJhcGlzZXJ2ZXIiLCJzdWIiOiIyYzM0MJMwOS0yZDA1LTYxMTMtNTM5MS1mODFlMzBlMDFlNmQiLCJ0eXBlIjoxLCJpYXQiOjE1NjMxODA3MjcsImF1ZCI6InNmLWNvbm5lY3RvciJ9.orCufOBCjgFvC8vYzut6Cjvm9R1aGwk_ZUrB0YZYDxBmfaT6Oc5QQHN18Msyfv9NBAMgu-Z8Xx-axY7bC5FL82X6udLngPiq6juPEgaq6bwt0NB3VkngGFzAy4vNJL20g-Fs28SaUuKM8ng7O1Omf6mubYDaTt_1jLZk8IJqwID7jcK_l9PI0Z5P6ENLVqoypIf3munL8Npw4dZ8HrrRgbrGtndRja9ZkUR-n4lNjbEjcXxGGD2T2t9h-4_KuRDCt81jYJ9yl5nlmBq8jkqV7dMi4gpgUwt2VPhivejj6gcUBCyakzeTJuk93bivGXSqXS8SegYdmVlonKkEIXPeUD"

}

Sample response:

In the example above, the value that you need to provide to the Authorization header of the secured Insight API server endpoints is bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJhcGlzZXJ2ZXIiLCJzdWIiOiIyYzM0MDMwOS0yZDA1LTYxMTMtNTM5MS1mODFlMzBlMDFlNmQiLCJ0eXBlIjoyLCJpYXQiOjE1NjQwNDUwNTgsImV4cCI6MTU2NDA0ODY1OCwiYXVkIjoic2YtY29ubmVjdG9yIn0.binP7vmJUBYPZUKJ9nA48-sD1fEmBY3o9MI8lq_Ub0kXz16Hhx9OJpO4E0rm0MK1A_LkVA7TOmf0E_r0uI-xGrJe11_yvgY9B2l06KD1whQAkLCwDsvb5HJE_eVmIZp2QgtopevhAR_l92sruhLs-0WwzVGVq5ETZ8hWxK202B_MYOTPxt2-0pg9j819qWZt3xYHpwKxCD-2EXoNkQ5flaYBBU9PUcZiGVNFdcJR2iZ2o9WpvN5M5K4kXPb7kLY5DG_pQpYZ9SksPdNQnqGJ9f3PE2tXZBcZf_HT2syJQNTniAljLPuvPDuz49quVR_pCUkASXVgD_XTC15XOyIybg.

Authorized application

To create an authorized application, perform the following:

  1. In Insight Web app, go to Administration » Data centers and click the name of the data center that you want to use.
  2. Click Authorized applications » Authorize an application.
  3. Name your application and click Generate access key.
  4. Copy the Access key.
  5. Click I’m Done.

To place the generated Access key token in the Authorization header, concatenate it with appAuth. For example, if your token is “78910”, enter you need to provide appAuth 78910 to authenticate.

NOTE: Authorized applications can only access the personalization endpoints of Insight. For more information, see Personalization API endpoints.

Obtain the data center API key

To work with the most of Insight endpoints, you must provide the API key of the data center. The reason is that most of the data related to Insight is bound to a specific data center. The following sections explain the two ways of obtaining the data center API key.

Insight Web App

  1. Log into  Sitefinity Insight.
  2. Open the Administration panel.
  3. Select the data center whose API key you want to obtain.
  4. Open the API key tab.

Insight API

Use the following API resource to obtain the API keys of the data centers you need access to.

Resource information

URL https://api.dec.sitefinity.com/admin/v1/users/mydatacenters
HTTP method GET
Description Returns a collections of data centers you have access to
Authentication Required

Parameters

Name Location Required Data type Description
Authorization Header Yes String The access token of the user
x-dataintelligence-skip Header No Integer Number of items to skip. Default value is 0.
x-dataintelligence-take Header No Integer Number of items to take. Default value is 20.
x-dataintelligence-filter Header No

JSON

Data is returned in JSON format, for example:

{
  "PropertyName":     "PropertyValue"
}

You can additionally filter the data centers by the following properties:

  • Id
  • ApiKey
  • AccountId

Responses

Name Returned data Description
200 OK

{

    "items": DataCenter[]

}

For more information, see Data center API data type.

Returns a collection of the data centers the authenticated user has access to.
400 GeneralErrorResponse
For more information see, General error response.
Usually returned when you have provided an unsupported property in the filter header.
401 Unauthorized Unauthorized Returned when an invalid or expired token is provided in the Authorization header.
412 GeneralErrorResponse
For more information see, General error response.
Usually returned when the skip, take, or filter parameter are not valid data type.

Sample request

HTTP:

GET https://api.dec.sitefinity.com/admin/v1/users/mydatacenters

Headers:

  • Authorization: bearer 123456
  • x-dataintelligence-filter: {"AccountId": "40C285EA-93JF-C589-7EBD-598E71E2D3GR"}
  • x-dataintelligence-skip: 1
  • x-dataintelligence-take: 2

Sample response

Was this article helpful?