Work with the Sitefinity Insight API
Get started
To start using Sitefinity Insight data collection and personalization API, you first need to have:
- A Microsoft account, which is provisioned in Insight.
NOTE: If you do not have a Sitefinity Insight account, contact sitefinitysales@progress.com.
- 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.
- 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:
- In Insight Web app, go to Administration » Data centers and click the name of the data center that you want to use.
- Click Authorized applications » Authorize an application.
- Name your application and click Generate access key.
- Copy the Access key.
- 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
- Log into Sitefinity Insight.
- Open the Administration panel.
- Select the data center whose API key you want to obtain.
- 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:
|
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