Area: Episerver Profile Store
Applies to versions: 1.3.0 and higher


This topic shows how to manage scopes using the API in Episerver Profile Store. Scope is a way of grouping objects, separating tracking requests to the site ID of the site where data was tracked. 

In this topic

How it works

Data separation by scope can be used for example to separate different business areas, such as brands or markets, to separate the tracked user's behavior. Each user can have a separate profile and history for interactions per scope, so that personalization and marketing activities are relevant to the behavior within the context of that scope. A regional manager can access only his/her market or brand according to their responsibilities, while a global manager can access several scopes.

Tracking events sent from a multi-site solution are isolated in its different sites. The default implementation for a scope when installing EPiServer.Tracking.Cms is the SiteId for the site from which the tracking event was sent. Track events sent without a scope are added to the default scope.

See Install and configure tracking for Profile Store how to configure scopes for multi-site solutions.

Note: The scope needs to be created before manipulating (create, update, and delete) or fetching (get, sort, search) profiles in the scope with Profile Store API.

Scope properties

The scope object contains the following property fields.

  • ScopeId [string]. The unique identifier of the scope. You can specify up to 64 characters. Start the string with a letter or number and it must contain a letter, number, and underline (_) only. Do not use capital letters.
  • Description [string]. Optional. You can specify a meaningful description of the scope of up to 256 characters.


  "ScopeId"     : "europe",  
  "Description" : "The european market."

Default scope

There is a default scope named default in each environment. Default scope cannot be updated or removed.


Profile Store API only supports 20 custom scopes in each environment.

Scope methods

GET api/v1.0/scopes/

Returns HTTP 200 OK with all the scopes available in the environment. Also, default scope is added at the end of the list.

Example of response body:

  "total" : 2,
  "count" : 2,
  "items" : [
                "ScopeId"     : "europe",
                "Description" : "The european market"
                "ScopeId"     : "default",
                "Description" : ""

GET api/v1.0/scopes/{scopeid}

  • Returns HTTP 200 OK with the scope in the response body, for the ScopeId provided.
  • Returns 404 NOT FOUND if no scope with the ScopeId was found.

Example of response body:

  "ScopeId"     : "Europe",  
  "Description" : "The european market."

PUT api/v1.0/scopes/{scopeid}

  • Replaces an existing scope, or creates a new one if no scope with the specified ScopeId was found.
  • Returns:
    • HTTP 201 CREATED if scope with ScopeId was not found, so it was created.
    • HTTP 200 OK when a scope was found and replaced (same response as GET method).
    • HTTP 400 BAD REQUEST if there are more than 20 custom scopes are created in the environment, or if you include the ScopeId in the body.
    • HTTP 400 BAD REQUEST if attempt to replace default scope.

Example of request body:

  "Description" : "The european market."
Do you find this information helpful? Please log in to provide feedback.

Last updated: Jun 15, 2018