Hide menu Last updated: Dec 27 2017
Area: Episerver Profile Store Applies to versions: 1.3.0 and higher

Profile Store API

This topic describes how to use the API in Episerver Profile Store to search, add and modify profiles, and tracked events.

Authentication

The Ocp-Apim-Subscription-Key header field is used for authentication and contains the subscription key that is passed with each request to the API.

Profiles

The profile object contains a fixed set of fields. Example:

{
  "Id": "df9fbdb3-4141-4d85-b37b-f5664b11a9dc",
"DeviceIds": [
"1f68f8a6-894b-42ce-aa2a-d5110eba1fba"
], "Name": "John Doe", "Manager": "Alec Baldwin", "LastSeen": "2001-01-01T12:34:56", "Visits": 1, "Info": { "Picture": "http://mypicture.com/", "InferredCountry": "Sweden", "Email": "user1@example.com" }, "ContactInformation": [ "Mailable", "Anonymous" ], "Payload": { "customField": 10, "otherCustomField": "banana" } }

Property descriptions

  • Id [GUID]. The unique identifier of the profile. Generated by the API.
  • DeviceIds [Array[string]]. A list of attached devices.
  • Name [string]. A descriptive name for the profile.
  • Manager [string]. Name of the person responsible for managing the profile.
  • LastSeen [DateTime]. When the last track event was sent for the visitor.
  • Visits [int]. Number of sessions that this profile has been active (>15 minutes between two track events will create a new session).
  • Info [Array with key [string] / value [string] ]. Key is one of the following:
    • Picture
    • Website
    • StreetAddress
    • Phone
    • Mobile
    • City
    • State
    • ZipCode
    • JobTitle
    • Company
    • Country
    • InferredCountry
    • Email
  • ContactInformation [Array[string]]. A read-only property which contains a list with values describing how the owner of the profile can be contacted, and will contain one or more of the following values:
    • Anonymous. If Name property is not set on the profile.
    • Known. If Name property is set on the profile.
    • Mailable. If Email exists in Info property.
    • Callable. If Phone or Mobile exists in Info property.
  • Payload [object]. A property where any other custom values can be stored in the form of a JSON object.

Track events

The track event object contains a fixed set of fields. Example:

{
   "DeviceId":"91687965-bc76-49a2-862c-e014441b8f6b",
   "EventType":"home",
   "Value":"Visited the start page.",
   "PageUri":"http://localhost:50244/en/",
   "RemoteAddress":"::1",
   "Payload":{},
   "EventTime":"2017-09-15T07:16:34.7957819Z",
   "CountryCode":"Localhost"
}

Property descriptions

  • DeviceId [string]. The device the event was send from.
  • EventType [string]. The type of event.
  • Value [string]. A human-readable string for the event.
  • PageUri [string]. The URL where the event was made (if it was from a site).
  • RemoteAddress [string]. The IP-address for the event visitor.
  • EventTime (datetime). The UTC time when the event occured.
  • CountryCode (string). The country from which the event was made.
  • Payload [object]. A property where any other custom values can be stored in the form of a JSON object.

API methods

GET api/v1.0/profiles/{profileid}

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

Example of response body:

{
  "Id": "df9fbdb3-4141-4d85-b37b-f5664b11a9dc",
"DeviceIds": [
"1f68f8a6-894b-42ce-aa2a-d5110eba1fba"
] "Name": "John Doe", "Manager": "Alec Baldwin", "LastSeen": "2001-01-01T12:34:56", "Visits": 1, "Info": { "Picture": "http://mypicture.com/", "InferredCountry": "Sweden", "Email": "user1@example.com" }, "ContactInformation": [ "Mailable", "Anonymous" ], "Payload": { "customField": 10, "otherCustomField": "banana" } }

POST api/v1.0/profiles/

  • Maximum request body size: 256KB
  • Creates a new profile object.

Example of request body (note that no ID should be sent, it will be generated by the API):

{
"DeviceIds": [
"1f68f8a6-894b-42ce-aa2a-d5110eba1fba"
], "Name": null, "Manager": null, "LastSeen": "0001-01-01T00:00:00", "Visits": 0, "Info": { "Picture": "http://mypicture.com/", "InferredCountry": "Sweden", "Email": "user1@example.com" }, "Payload": { "customField": 10, "otherCustomField": "banana" } }
  • Returns HTTP 201 CREATED with the created profile in the response body, and with the same structure as when retrieving a profile with the GET method as described above.

    The HTTP response header Location contains the URL to the profile:

    HTTP/1.1 201 Created Location: http://www.example.org/api/v1.0/profiles/df9fbdb3-4141-4d85-b37b-f5664b11a9dc
  • Returns HTTP 413 REQUEST ENTITY TOO LARGE if request body is > 256KB.

PUT api/v1.0/profiles/{id}

  • Maximum request body size: 256KB
  • Replaces an existing profile, or creates a new one if no profile with the specified ID was found.
  • Returns:
    • HTTP 201 CREATED (same response as POST method) if profile with ID was not found, so it was created.
    • HTTP 200 OK when a profile was found and replaced (same response as GET method).
    • HTTP 413 REQUEST ENTITY TOO LARGE if request body is > 256KB.

Comments