Topics

Personalization API endpoints

With the Sitefinity Insight REST API, you can personalize content in an easy and straightforward way.

Endpoint: POST /analytics/v1/personalization/visitor-context

You use this API to retrieve available personas, lead scorings, touchpoints, conversions, or contact properties for a given visitor or contact. You can select which information to obtain, making this call very efficient.

Resource information

URL https://api.insight.sitefinity.com/analytics/v1/personalization/visitor-context
HTTP method POST
Description Use this endpoint for personalization. All requested information is returned, and the consumer can decide how to change the served content.
Authentication Required

Parameters

Name Location Required Data type Description
Authorization Header Yes String The access token of the user.
x-dataintelligence-datacenterkey Header Yes Guid The API key of the data center.
x-dataintelligence-datasource Header Yes String The name of the data source where the subject is reported.
x-dataintelligence-subject Header Yes String The subject ID of the visitor you want to check.

You declare in the body of the request what information you need. The body is a JSON-encoded object, containing the fields described below. All fields are optional, but the request must have at least one field.

Name Data type Description
Touchpoints PersonalizationEntitiesWithPeriod The identifiers of touchpoints which you are looking for whether the visitor has any actions associated with.
Conversions PersonalizationEntitiesWithPeriod The identifiers of conversions which you are looking for whether the visitor participated in.
PersonasIds Integer[] The identifiers of personas which you are looking for whether the visitor belongs to.
LeadsIds Integer[] The identifiers of lead scorings which you are looking for whether the visitor belongs to.
ContactProperties Boolean Set this property to true to request contact properties for the given contact.

The PersonalizationEntitiesWithPeriod object contains the following fields, all of which are optional:

Name Data type Description
Ids Integer[] All identifiers of personalization entities required for the personalization context.
PeriodInDays Integer The period, represented in number of days, for which the personalization entities are requested. Use ‘-1’ to request entities for any time. The allowed values are -1, 7, 30, 90, 180, and 365.

Responses

Name Returned data Description
200 OK
{
   Properties?: Object
   PassedLeads?: PersContextLead[],
   InPersonas?: PersContextPersona[],
   InTouchpoints?: PersContextEntityWithEventDate[],
   InConversions?: PersContextEntityWithEventDate[]
} 		Returns a JSON object, whose members depend on what data was requested:
  • Properties: Contains the values of all ContactProperties. Each object property contains the ID of the respective ContactProperty.
    NOTE: This object contains data only when you authenticate with an account that has the permission to work with personally identifiable information. For more information, see Manage Personally identifiable information.
  • InPersonas: Optional. All Persona IDs where a given visitor belongs to.
  • PassedLeads: Optional. IDs of all lead scorings and their stages, where a given visitor interactions count.
  • InTouchpoints: Optional. IDs of touchpoints visited by a given visitor with the date of the last occurred event.
  • InConversions: Optional. IDs of all conversions to which a given visitor belongs with the date of the last occurred conversion.
400 GeneralErrorResponse This error status may be returned when some property is not in the expected format (for example, providing a string value where a number is expected), or there was an expected property in the request body, or the parameters are exceeded. Change the property specified in the error message and retry the call.
403 Forbidden GeneralErrorResponse Returned when an invalid API key is provided in the x-dataintelligence-datacenterkey parameter. Another reason is when a valid key is provided but the authenticated user does not have access to the data center.
412 Precondition Failed GeneralErrorResponse The subject, datasource, or apiKey headers are not provided or invalid, or the JSON-encoded body payload is empty.. Generally, the message states which parameter needs to be fixed.

Personalization Context - Persona (PersContextPersona)

Name Data Type Required Description
PersonaId Int No Contains the ID of the persona, which a given visitor belongs to.

Personalization Context - Leads (PersContextLead)

Name Data Type Required Description
LeadId Int No Contains the ID of the lead scoring for particular visitor.
LevelId Int No Contains the completed level of given lead scoring for a given visitor.

Personalization context – Touchpoints and Conversions (PersContextEntityWithEventDate)

Name Data Type Required Description
Id Int No The ID of the personalization entity for a particular visitor.
LatestEventDate DateTime No The latest date on which the personalization entity occurred.

Sample request and response

Headers:

  • Authorization: bearer token
  • x-dataintelligence-datacenterkey: c27aeeb7-d222-d848-d8bf-9792485dafa9
  • x-dataintelligence-datasource: Demo data
  • x-dataintelligence-subject: 1353

JSON response:

Endpoint: GET /analytics/v1/personalization/visitor-context

NOTE: Starting with Sitefinity Insight deployment on Jan 20, 2022, this API endpoint is obsoleted. We recommend you to use the POST /analytics/v1/personalization/visitor-context endpoint described above.

Resource information

URL https://api.insight.sitefinity.com/analytics/v1/personalization/visitor-context
HTTP method GET
Description Use this endpoint for personalization. All available information is returned, and the consumer can decide how to change the served content.
Authentication Required

Parameters

You send the following parameters in the header of the API request. All parameters are required.

Name Data type Description
Authorization String The access token of the user.
x-dataintelligence-datacenterkey Guid The API key of the data center.
x-dataintelligence-datasource String The name of the data source where the subject is reported.
x-dataintelligence-subject String The subject ID of the visitor you want to check.

Responses

Name Returned data Description
200 OK
{
   Properties: ContactProperty[]
   InPersonas?: PersContextPersona[],
   PassedLeads?: PersContextLead[]
} 		Returns an object containing:
  • Properties: Contains the values of all ContactProperties. Each object property contains the ID of the respective ContactProperty.
    NOTE: This array contains data only when you authenticate with an account that has the permission to work with personally identifiable information. For more information, see Manage Personally identifiable information.
  • InPersonas: Optional. All Persona IDs where a given visitor belongs to.
  • PassedLeads: Optional. IDs of all lead scorings, where a given visitor interactions count with their levels.
400 GeneralErrorResponse This error status may be returned when some property is not in the expected format (for example, providing a string value where a number is expected), or there was an expected property in the request body, or the parameters are exceeded. Change the property specified in the error message and retry the call.
403 Forbidden GeneralErrorResponse Returned when an invalid API key is provided in the x-dataintelligence-datacenterkey parameter. Another reason is when a valid key is provided but the authenticated user does not have access to the data center.
412 Precondition Failed GeneralErrorResponse The subject, datasource, or apiKey headers are not provided or invalid, or the JSON-encoded body payload is empty.. Generally, the message states which parameter needs to be fixed.

Personalization Context - Persona

Name Data Type Required Description
PersonaId Int No Contains the ID of the persona, which a given visitor belongs to.

Personalization Context - Leads

Name Data Type Required Description
LeadId Int No Contains the ID of the lead scoring for particular visitor.
LevelId Int No Contains the completed level of given lead scoring for a given visitor.

Sample request and response

Headers:

  • Authorization: bearer token
  • x-dataintelligence-datacenterkey: c27aeeb7-d222-d848-d8bf-9792485dafa9
  • x-dataintelligence-datasource: Demo data
  • x-dataintelligence-subject: 1353

JSON response:

Endpoint: GET /analytics/v2/scorings/leads/in

NOTE: Starting with Sitefinity Insight deployment on Jan 20, 2022, this API endpoint is obsoleted. We recommend you to use the POST /analytics/v1/personalization/visitor-context endpoint described above.

Resource information

URL https://api.insight.sitefinity.com/analytics/v2/scorings/leads/in
HTTP method GET
Description Gets information about the lead scoring types the visitors are associated to.
Authentication Required

Parameters

You send the following parameters in the header of the API request.

Name Required Data type Description
Authorization Yes String The access token of the user.
x-dataintelligence-datacenterkey Yes Guid The API key of the data center.
x-dataintelligence-datasource Yes String The name of the data source where the subject is reported.
x-dataintelligence-subject Yes String The subject ID of the visitor you want to check.
x-dataintelligence-ids No String

The IDs of the lead scoring types in the data center you want check. You can check several lead scoring types at once by separating the IDs with a comma. For example: “10, 25, 36”.

If you do not provide a parameter, all lead scoring types to which the provided visitors are associated to are returned.

Responses

Name Returned data Description
200 OK
{
    “items”: LeadScoringResultV2
}

For details, see Lead scoring result API data type v2.

Returns:

  • Data source
  • Visitor ID
  • Current points and dates on which each level was passed for each of the provided lead scoring types Ids the visitor is associated to.
403 Forbidden GeneralErrorResponse Returned when an invalid API key is provided in the x-dataintelligence-datacenterkey parameter. Another reason is when a valid key is provided but the authenticated user does not have access to the data center.
412 Precondition Failed GeneralErrorResponse Some of the provided parameters are not valid. Generally, the message states which parameter needs to be fixed.

Sample request and response

Headers:

  • Authorization: bearer token
  • x-dataintelligence-datacenterkey: c27aeeb7-d222-d848-d8bf-9792485dafa9
  • x-dataintelligence-datasource: Demo data
  • x-dataintelligence-subject: 1353
  • x-dataintelligence-ids: 73, 74

JSON response:

Endpoint: GET /analytics/v1/scorings/personas/in

NOTE: Starting with Sitefinity Insight deployment on Jan 20, 2022, this API endpoint is obsoleted. We recommend you to use the POST /analytics/v1/personalization/visitor-context endpoint described above.

Resource information

URL https://api.insight.sitefinity.com/analytics/v1/scorings/personas/in

HTTP method

 GET
Description Checks whether the provided subjects are associated to the required personas.
Authentication Required

Parameters

You send the following parameters in the header of the API request.

Name Required Data type Description
Authorization Yes String The access token of the user.
x-dataintelligence-datacenterkey Yes Guid The API key of the data center.
x-dataintelligence-datasource Yes String The name of the data source where the subject is reported.
x-dataintelligence-subject Yes String The subject ID of the visitor you want to check.
x-dataintelligence-ids No String

The IDs of the personas in the data center you want check. You can check several personas at once by separating the IDs with a comma. For example: “1, 45, 24”.

If you do not provide a parameter, all personas to which the provided visitors are associated to are returned.

Responses

Name Returned data Description
200 OK
{
“items”: ScoringResult []
}

For details, see Scoring result API data type.

Returns:

  • Data source
  • Visitor ID
  • Current points and dates on which each level was passed for each of the provided persona IDs the visitor is associated to.
403 Forbidden GeneralErrorResponse Returned when an invalid API key is provided in the x-dataintelligence-datacenterkey parameter. Another reason is when a valid key is provided but the authenticated user does not have access to the data center.
412 Precondition Failed GeneralErrorResponse Some of the provided parameters are not valid. Generally, the message states which parameter needs to be fixed.

Sample request and response

Headers:

  • Authorization: bearer token
  • x-dataintelligence-datacenterkey: c27aeeb7-d222-d848-d8bf-9792485dafa9
  • x-dataintelligence-datasource: Demo data
  • x-dataintelligence-subject: 1353
  • x-dataintelligence-ids: 59, 60

JSON sample response:

Endpoint: GET /analytics/v1/scorings/leads/in

Resource information

URL https://api.insight.sitefinity.com/analytics/v1/scorings/leads/in
HTTP method GET
Description Get information about the lead scoring types whose threshold visitors passed.
Authentication Required

Parameters

You send the following parameters in the header of the API request.

Name Required Data type Description
Authorization Yes String The access token of the user.
x-dataintelligence-datacenterkey Yes Guid The API key of the data center.
x-dataintelligence-contacts Yes Object An object containing information about the visitors (clients) to check, grouped by data source name, for example:
{
    "Data Source 1 Name": [“Subject Id of Client 1”,  “Subject Id of Client 2”],
    "Data Source 2 Name": [“Subject Id of Client 3”,  “Subject Id of Client 4”]
}
x-dataintelligence-ids No String

The IDs of the lead scoring types in the data center you want check. You can check several lead scoring types at once by separating the IDs with a comma. For example: “10, 25, 46”.

If you do not provide a parameter, all lead scoring types, to which the provided visitors are associated to are returned.

Responses

Name Returned data Description
200 OK
{
LeadScoringResultReport[]
}

For details, see Lead scoring result report API data type.

 Returns the lead scoring type ID, current points and dates, on which each scoring type threshold was passed for each of the provided lead scoring types IDs the visitor is associated to.
403 Forbidden GeneralErrorResponse Returned when an invalid API key is provided in the x-dataintelligence-datacenterkey parameter. Another reason is when a valid key is provided but the authenticated user does not have access to the data center.
412 Precondition Failed GeneralErrorResponse Some of the provided parameters are not valid. Generally, the message states which parameter needs to be fixed.

Sample request and response

Headers:

  • Authorization: bearer token
  • x-dataintelligence-datacenterkey: c27aeeb7-d222-d848-d8bf-9792485dafa9
  • x-dataintelligence-ids: 73
  • x-dataintelligence-contacts: {"Demo data": ["1353", "1399"], "Learn": ["1254"]}

JSON sample response:

Was this article helpful?

Next article

Management of contact data endpoints