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 track events.

In this topic

Authentication

 Use the Authorization header for authentication with a value in the following format: epi-single key; it contains the subscription key that is passed to the API with each request.

Profiles

The profile object contains a fixed set of fields. For example:

{
  "ProfileId": "df9fbdb3-4141-4d85-b37b-f5664b11a9dc",
  "DeviceIds": [
     "1f68f8a6-894b-42ce-aa2a-d5110eba1fba"
  ],
  "Name": "John Doe",
  "ProfileManager": "Alec Baldwin", 
  "FirstSeen": "2018-01-01T12:34:56",
  "LastSeen": "2018-05-18T11:33:12",
  "Visits": 1401,
  "Scope": "CommerceSite"
  "Info": {
      "Website": "https://example.com"
      "Picture": "http://example.com/profile/JohnDoe_avatar.png",
      "StreetAddress": "Hagagatan 1, vi",
      "Phone": "0294-8742517",
      "Mobile": "0294-8742517",
      "City": "Stockholm",
      "State": "N/A",
      "ZipCode": "815 24",
      "JobTitle: "Developer",
      "Company": "Almacs",
      "Country: "SW",
      "Email": "John.Doe@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.
  • Scope [string]. The scope for the profile.
  • ProfileManager [string]. Name of the person responsible for managing the profile.
  • FirstSeen [DateTime]. When the first track event was sent for the visitor.
  • LastSeen [DateTime]. When the last track event was sent for the visitor.
  • Visits [int]. Number of sessions that this profile was active (>15 minutes between two track events creates 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 that contains a list with values describing how the owner of the profile can be contacted, and contains 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. For example:

{
   "DeviceId":"91687965-bc76-49a2-862c-e014441b8f6b",
   "EventType":"home",
   "Value":"Visited the start page.",
   "PageUri":"https://example.com/en/",
   "RemoteAddress":"::1",
   "Payload":{  
      "name":"Home page",
      "contentGuid":"440be34f-d08a-4a7e-b019-55448d065d28",
      "contentLink":"163204",
      "contentTypeID":170,
      "parentLink":"163198"
   },
   "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/{scope}/{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:

{
  "ProfileId": "6243d1c0-70dd-453e-9cc4-63c577cb25ad",
  "DeviceIds": [
     "9f4447e4-9f00-4fa8-ad30-a1a971d4fbf6"
  ],
  "Name": "Nikki A Blomqvist",
  "ProfileManager": null, 
  "FirstSeen": "2017-12-01T12:34:56",
  "LastSeen": "2018-05-19T11:33:12",
  "Visits": 1150,
  "Scope": "DefaultScope"
  "Info": {
      "Website": "https://example.com"
      "Picture": "http://example.com/Nikki A Blomqvist_avatar.png",
      "Country: "SW",
      "Email": "Nikki.Blomqvist@example.com"
  },
  "ContactInformation": [
    "Mailable",
    "Anonymous"
  ],
  "Payload": {
    "customField": 14,
    "otherCustomField": "apple"
  }
}

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 because it is generated by the API.)

{
  "DeviceIds": [
     "1f68f8a6-894b-42ce-aa2a-d5110eba1fba"
  ],
  "Name": "Luke Skywalker",
  "ProfileManager": null,
  "LastSeen": "2018-06-15T00:00:00",
  "Scope": "CommerceSite",
  "Visits": 1205,
  "Info": {
    "Website": "https://example.com"
    "Picture": "http://example.com/profile/luke_avatar.png",
    "InferredCountry": "Sweden",
    "Email": "Luke.Skywalker@example.com"
  },
  "Payload": {
    "customField": 10,
    "otherCustomField": "banana"
  }
}
  • In case Scope is null or no Scope is sent, the default value for Scope will be DefaultScope
  • 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