Timeline APIs

These APIs support the creation and maintenance of timeline services for an organization. With respect to this service, an event can be defined as an arbitrary action that occurred at a specific time, anchored to an arbitrary object and contains data attributes specific to this particular type of action.

As you consult the conceptual discussions and the tables that detail JSON requests and responses, bear in mind that timelines utilize a collection of objects and attributes that contain the word "stream." For example, consider these object names: stream, stream_view and stream_type. When this site describes a timeline attribute or object, it uses these names. However, when discussions are more conceptual and descriptive in nature, this site uses the word "timeline." Of course this site always utilizes the literal names for all objects and attributes in timeline-related sample code or their associated references; in these cases, the term "stream" is never replaced with "timeline."

In more concrete terms, an implementation of the timeline service could be a member statement that represents customer activity. For example, an event could have the following characteristics:

• Action: purchase
• Anchored object: customer
• Timestamp: datetime of purchase
• Data: {item: “T-shirt”, price: 19.99, color: “red”, size: “Medium”}

Part of the functionality offered by this collection of APIs is the ability to create event types and categories, or groupings, of event types. The Timeline Event Types API allows you to build out and maintain event types as well as associate rendering templates to them.

Timeline services can reflect a variety of timelines, including those for customer activity, campaign activity, enduser communication and Point of Sale (POS) activity.

You can use the Timeline Service API to build and maintain the service. When designing your timeline service, do so in a generic manner. This approach makes it easy to define additional event timelines with different event definitions and levels of granularity that require a minimal development effort. One of the functions this API offers is the ability to consume raw data from external devices that are generating events. Related methods can interpret raw event data and render it in specific customer contexts. With this API, you can publish an event and retrieve a page of events for a particular event timeline view.

Each service can record types of temporal events with varying sets of data attributes per event type. Doing so generates a timeline of events in reverse chronological order that can be accessed in a paged manner.

An event timeline can be of infinite size. However, the Timeline Configuration API includes methods that can constrain a very large timeline with views that read from the timeline service and inject context into the raw event data being presented. This API includes methods for creating event templates and rendering contexts for these views.

Views allow for paging through a timeline, either rendered literally as pages of events or shown with an “infinite scroll” mechanism. They can reflect different levels of granularity, and individual events within them can appear in multiple views. For example, the same event can be included in the view for a particular customer’s events, and also show up in a view tied to a particular campaign.

This section contains the following discussions:

• Timeline APIs Architecture
• Timeline Event Types API
• Timeline Service API
• Timeline Configuration API

If you want information on working with events, see the Events API.

Timeline APIs Architecture

The Timeline APIs architecture features object entities that reflect the three APIs that enable the programmatic capture of event histories, or timelines. These entities can be best understood in the following two sections, with each discussion rooted in a diagram:

• Event Definition
• Event Display

Event Definition

Before you can present timelines of customer events, you must define the events being represented in the timeline. Events are the digital representation of a customer's activity that gets passed to SessionM as data. Generally they can be defined as one of the three types: engagement (or activity), location and purchase.

SessionM offers the Event Types API so you can build out a hierarchy of event metatdata. In short, event categories contain event types which define events. The following diagram depicts these entities:

The Event Categories box shown at the top of the diagram represents a category that aggregates a set of event types into a single, common grouping. In this case, the event category is "Purchases." It contains three event types, which are shown in the Event Types box located in the middle of the diagram. Each event type defines the kind of event that is being expressed; in this example, the purchase event types include "Returned Item," "Voided Transaction" and, of course, "Purchased Item."" Each of these types represents a result that can follow from a purchase:

• Item being purchased.
• Purchased item being returned.
• Purchase transaction for item being voided.
  

All fit logically within the event category, "Purchases."

The bottom box of the diagram depicts the Event object type. Unlike the other boxes in the diagram, the Event box shows the attributes defined by both the higher level types and the attributes that are critical to defining what an event is. Inherited attributes include the event category and the event type, which are shown toward the top of the event box. Other attributes include identifiers, a timestamp and the heart of the event, a payload. It is the payload that expresses perhaps the most familiar characteristics of a purchase event: What the item is, its size, its price and its associated tax.

Event Display

With event categories, event types and events defined, determine how timelines of events can be displayed. Timelines can reflect event histories of a variety of actors, however, the current SessionM implementation features those reflecting customer events.

This customer event timeline is populated from events generated by customers using external devices. Supported by methods available in the Timeline Service API, the raw data from these events can be published as timeline objects in the SessionM Platform. Once data is in residence as a user_event_stream, it can be configured for display via timeline views and rendering contexts. The diagram show below depicts these entities and their relationships:

Note that the publishing of raw external event data as a timeline is not presented in the diagram above; it happens outside of the platform.

Event data consumed from external sources resides in the bottom box of the diagram, which is labeled "Timelines." In this case, the timeline shown is a customer timeline. Since the number of events in any timeline can be quite large, timeline views determine what subset of events will be presented, a specification that is shown in the middle box of the diagram, "Timeline Views." Two views are shown; one as a customer member statement and one as a customer service agent member statement. Each view expresses its own collection of events, all of which are defined by particular event types and represented as multiple Event boxes located between the Timelines and Timeline Views layers.

While timelines do provide a mechanism for narrowing which events will be shown in a timeline, event templates and rendering contexts define how those events will appear. The top box of the diagram labeled "Timeline Rendering Contexts" contains two rendering contexts, each of which specifies context for a view being presented in an associated template. In this case, the rendering contexts include one for customers engaged in a iOS-based mobile experience and the other for customer service agents accessing the platform's customers module in the UI. For both contexts, event templates have been defined, along with their association to an event type and a rendering context, as shown in multiple Event Template boxes located between the Timeline Views and the Timeline Rendering Contexts layers.

Timeline Event Types API

The Timeline Event Types API offers a collection of endpoints that build and manage event types for events shown in an event timeline. Event types are kinds of actions; they name and define the actions that are common to your organization and, often, customers.

Maintained in the SessionM Platform, each event type defines the metadata for each event that can occur; for example, "Purchased Item XYZ" or "Opened an Email." A grouping of event types, however, are event categories; for example, "Customer Actions." Event categories are an optional way of defining a set of related event types. Finally, an event itself is an instance of an event type; for example, "Customer ABC Purchased Item XYZ."

In addition to managing the types and categories for events, this API includes endpoints for creating and managing rendering templates for the event types. Templates can serve a variety of contexts, including:

• SessionM customer module
• Customer's mobile experience
• Customer's desktop experience

This API provides the following methods:

• Create an event category
• Create an event type
• Create a rendering template
• Retrieve event categories
• Retrieve rendering templates
• Retrieve an event type
• Update an event category
• Update a rendering template
• Update an event type

Create an Event Category

Create an event category for grouping a set of event types together.

Endpoints

This method offers the following endpoints:

POST /priv/:api_version/apps/:api_key/timelines/categories            

For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Request Object

When this method runs, it passes in a request object that contains an category object, as shown below:

{
  "category": {
    "name": "Points Economy",
    "description": "Points Economy"
  }
}

This object is detailed in the following table:

Request Attributes for Category

Response Object

In addition to a status key-value pair, the response object returned by the method contains an event_category object, as shown below:

{
  "status": "ok",
  "event_category": {
    "id": 9,
    "name": "Points Economy",
    "slug": "POINTS_ECONOMY",
    "description": "Points Economy",
    "created_at": "2017-08-24T17:15:00Z",
    "updated_at": "2017-08-24T17:15:00Z"
  }
}

This object is detailed in the following table:

Response Attributes for Category

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. No error messages are defined for this method except for the generic statuses and errors returned for any object. For more information, see the associated section in Generic Statuses and Errors.

Create an Event Type

Create an event type for the kind of action that occurred, such as “Purchased” or “Opened Email."

Endpoints

This method offers the following endpoints:

POST /priv/:api_version/apps/:api_key/timelines/:timeline_id/event-types

For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Request Object

When this method runs, it passes in a request object that contains a event_type object, as shown below:

{
    "event_type": {
        "name": "New Name",
        "description": "new description",
        "event_stream_event_category_id": 1
    }
}

This object is detailed in the following table:

Request Attributes for Event Type

{
    "status": "ok",
    "event_type": {
      "id": 1,
      "name": "Name",
      "slug": "NAME",
      "description": "Description",
      "event_stream_event_category_id": 1,
      "event_stream_stream_id": 1
  }
}

Response Object

In addition to a status key-value pair, the response object returned by the method contains a event_type object, as shown below:

{
    "status": "ok",
    "event_type": {
      "id": 1,
      "name": "Name",
      "slug": "NAME",
      "description": "Description",
      "event_stream_event_category_id": 1,
      "event_stream_stream_id": 1
  }
}

This object is detailed in the table below:

Response Attributes for Event Type

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. No error messages are defined for this method except for the generic statuses and errors returned for any object. For more information, see the associated section in Generic Statuses and Errors.

Create a Rendering Template

Create a rendering template, mapping an event template to a specific rendering context. The context specifies the environment in which events should be rendered and targets a particular template to that environment.

Endpoints

This method offers the following endpoints:

POST /priv/:api_version/apps/:api_key/timelines/:timeline_id/event-types/:event_type_id/templates

For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Request Object

When this method runs, it passes in a request object that contains a rendering_template object, as shown below:

{
  "rendering_template": {
    "event_stream_event_template_id": 2,
    "event_stream_stream_view_id": 7,
    "event_stream_rendering_context_id": 4,
    "version": 1
  }
}

This object is detailed in the following table:

Request Attributes for Rendering Template

Response Object

In addition to a status key-value pair, the response object returned by the method contains a rendering_template object, as shown below:

{
  "status": "ok",
  "rendering_template": {
    "id": 4,
    "event_stream_event_template_id": 2,
    "event_stream_stream_view_id": 7,
    "event_stream_rendering_context_id": 4,
    "version": 1
  }
}

This object is detailed in the table below:

Response Attributes for Rendering Template

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. No error messages are defined for this method except for the generic statuses and errors returned for any object. For more information, see the associated section in Generic Statuses and Errors.

Retrieve Event Categories

Retrieve all event categories for an organization.

Endpoints

This method offers the following endpoints:

GET /priv/:api_version/apps/:api_key/timelines/categories            

For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Request Object

Not applicable.

Response Object

In addition to a status key-value pair, the response object returned by the method contains a result array, which is a hash array of one or many event_category objects. Consider the following sample:

{
    "status": "ok",
    "result": [
    {
        "event_category": {
           "created_at": "2017-08-25T10:23:24-04:00",
           "description": "Points Economy",
           "id": 30,
           "name": "Points Economy 1",
           "organization_id": 112,
           "slug": "POINTS_ECONOMY_1",
           "updated_at": "2017-08-25T10:23:24-04:00"
        }
    },
    {
        "event_category": {
           "created_at": "2017-08-25T10:23:24-04:00",
           "description": "Points Economy",
           "id": 31,
           "name": "Points Economy 2",
           "organization_id": 112,
           "slug": "POINTS_ECONOMY_2",
           "updated_at": "2017-08-25T10:23:24-04:00"
        }
    },
    {
        "event_category": {
           "created_at": "2017-08-25T10:23:24-04:00",
           "description": "Points Economy",
           "id": 32,
           "name": "Points Economy 3",
           "organization_id": 112,
           "slug": "POINTS_ECONOMY_3",
           "updated_at": "2017-08-25T10:23:24-04:00"
        }
    }
  ]
}

The array is empty if no categories exist. When present, the event_category object can contain several attributes. For more information, see the event_category object.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. No error messages are defined for this method except for the generic statuses and errors returned for any object. For more information, see the associated section in Generic Statuses and Errors.

Retrieve Rendering Templates

Retrieve all existing rendering templates for a specified event type.

Endpoints

This method offers the following endpoints:

GET /priv/:api_version/apps/:api_key/timelines/:timeline_id/event-types/:event_type_id/templates

For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Request Object

Not applicable.

Response Object

In addition to a status key-value pair, the response object returned by the method contains a templates array, which is a hash array of one or many rendering_template objects. Consider the following sample:

{
  "status": "ok",
  "templates": [{
      "rendering_template": {
        "id": 1,
        "event_stream_stream_view_id": 6,
        "event_stream_event_template_id": 1,
        "event_stream_rendering_context_id": 1,
        "version": 1
      }
    },
    {
      "rendering_template": {
        "id": 2,
        "event_stream_stream_view_id": 6,
        "event_stream_event_template_id": 1,
        "event_stream_rendering_context_id": 2,
        "version": 1
      }
    },
    {
      "rendering_template": {
        "id": 3,
        "event_stream_stream_view_id": 6,
        "event_stream_event_template_id": 1,
        "event_stream_rendering_context_id": 3,
        "version": 1
      }
    }
  ]
}

The array is empty if no templates exist. When present, the rendering_template object can contain several attributes. For more information, see the rendering_template object.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Retrieve an Event Type

Retrieve a specified event type with all of its related attributes.

Endpoints

This method offers the following endpoints:

GET /priv/:api_version/apps/:api_key/timelines/:timeline_id/event-types/:event_type_id

For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Request Object

Not applicable.

Response Object

In addition to a status key-value pair, the response object returned by the method contains an event_type object, as shown below:

{
  "status": "ok",
  "event_type": {
    "id": 2,
    "name": "Earned Achievement \"Free Hamburger\"",
    "slug": "EARNED_ACHIEVEMENT_FREE_HAMBURGER",
    "description": "Earned Achievement \"Free Hamburger\"",
    "event_stream_event_category_id": 10,
    "event_stream_stream_id": 17
  }
}

This object is detailed in the table below:

Response Attributes for Event Type

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Update an Event Category

Update an event category that groups a set of event types together.

Endpoints

This method offers the following endpoints:

PUT  /priv/:api_version/apps/:api_key/timelines/categories/:category_id

For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Request Object

When this method runs, it passes in a request object that contains a category request object as shown below:

{
  "category": {
    "name": "Points Economy",
    "description": "Points Economy"
  }
}

Response Object

In addition to a status key-value pair, the response object returned by the method contains an event_category object, as shown below:

{
  "status": "ok",
  "event_category": {
    "id": 9,
    "name": "Points Economy",
    "slug": "POINTS_ECONOMY",
    "description": "Points Economy",
    "created_at": "January 30, 2017 10:22",
    "updated_at": "January 30, 2017 10:22"
  }
}

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Update a Rendering Template

Update a specified rendering template for an event type.

Endpoints

This method offers the following endpoints:

PUT  /priv/:api_version/apps/:api_key/timelines/:timeline_id/event-types/:event_type_id/templates/:template_id

For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Request Object

When this method runs, it passes in a request object that contains a rendering_template object, as shown below:

{
  "rendering_template": {
    "event_stream_event_template_id": 2,
    "event_stream_stream_view_id": 7,
    "event_stream_rendering_context_id": 4,
    "version": 1
  }
}

Response Object

In addition to a status key-value pair, the response object returned by the method contains a rendering_template object, as shown below:

{
                "status": "ok",
                "rendering_template": {
                "id": 4,
                "event_stream_event_template_id": 2,
                "event_stream_stream_view_id": 7,
                "event_stream_rendering_context_id": 4,
                "version": 1
                }
                }
            

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Update an Event Type

Update an event type, modifying attributes such as its name and description.

Endpoints

This method offers the following endpoints:

PUT /priv/:api_version/apps/:api_key/timelines/:timeline_id/event-types/:event_type_id        

For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Request Object

When this method runs, it passes in a request object that contains an event_type object, as shown below:

{
  "event_type": {
    "name": "Earned Achievement \"Free Hamburger\"",
    "description": "Earned Achievement \"Free Hamburger\""
  }
}

This object is detailed in the table below:

Request Attributes for Event Type

{
  "status": "ok",
  "event_type": {
    "id": 2,
    "name": "Earned Achievement \"Free Hamburger\"",
    "slug": "EARNED_ACHIEVEMENT_FREE_HAMBURGER",
    "description": "Earned Achievement \"Free Hamburger\"",
    "event_stream_event_category_id": 10,
    "event_stream_stream_id": 17
  }
}

Response Object

In addition to a status key-value pair, the response object returned by the method contains an event_type object, as shown below:

{
  "status": "ok",
  "event_type": {
    "id": 2,
    "name": "Earned Achievement \"Free Hamburger\"",
    "slug": "EARNED_ACHIEVEMENT_FREE_HAMBURGER",
    "description": "Earned Achievement \"Free Hamburger\"",
    "event_stream_event_category_id": 10,
    "event_stream_stream_id": 17
  }
}

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Timeline Service API

A timeline service can record various types of temporal events, each with its own different set of data attributes. It allows developers to access them as a timeline of infinite size. You can use the service to define different kinds of timelines; while a user event timeline is quite typical, you can also create a campaign timeline. Having multiple timelines allows you to keep events logically separated along service boundaries and not easily intermingled. The Timeline Service API offers a collection of endpoints that build and manage an event timeline service.

Before timelines can exist on the SessionM Platform, the events being generated from external sources or devices must be captured. This API supports this task by providing methods that manage the consumption of events published by external devices and interpret raw event data so it can be rendered in a specific customer context.

This API provides the following methods:

• Publish an external event into a timeline
• Retrieve events for a single view
• Create a timeline type
• Create a timeline service
• Retrieve all timeline services
• Retrieve a specified timeline service
• Update a timeline service

Publish an External Event into a Timeline

Publish events generated from external devices outside of the SessionM Platform into timelines in either a synchronous or asynchronous mode. The raw data generated by events is represented by user_event_stream objects specified on the platform.

Endpoints

This method offers the following endpoints:

POST /v1/apps/:api_key/users/:user_id/timelines/:stream_id
POST /v1/apps/:api_key/external/users/:external_id/timelines/:stream_id
POST /v1/apps/:api_key/users/:user_id/timelines/stream_type_slug
POST /v1/apps/:api_key/external/users/:external_id/timelines/stream_type_slug

For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Request Object

When this method runs, it passes in a request object that contains a stream object, as shown below:

{
  "transactional": false,
  "stream_type": "USER",
  "event_type": "PURCHASE_TRANSACTION",
  "timestamp": "2017-06-05 12:30:00",
  "payload": {
    "value": "17.00",
    "num_points": "17"
  }
}

This object is detailed in the following table:

Request Attributes

Response Object

In addition to a status key-value pair, the response object returned by the method contains a result object, which can contain the saved attribute. If this boolean is set to true, the event has been published.

Consider the following sample:

{
  "status": "ok",
  "result": {
    "saved": true
  }
}

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. No error messages are defined for this method except for the generic statuses and errors returned for any object. For more information, see the associated section in Generic Statuses and Errors.

Retrieve Events for a Single View

Retrieves an array of events in a timeline view that reflects a specific user or type of user. The event data returned represents a wide range of event activity, which can vary depending upon what type of user is performing the events. For example, the events in a view associated with an enduser, or customer, making a purchase differs a great deal from an administrator creating new event types.

Endpoints

This method offers the following endpoints:

GET /v1/apps/:api_key/external/users/:external_id/timelines/NEW_VIEW
GET /v1/apps/:api_key/users/:user_id/timelines/NEW_VIEW

For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

If you want to filter the view, you can pass in filters via the endpoint. Specify the endpoint by drawing from a set of possible filter types, all listed below with corresponding sample data:

• Context slug - context_slug=ABC
• Since - since=1484585770
• Count - count=2
• Event category ID - filter[event_category_id]=123
• Event type ID(s) - event_types=12,13,14
• Target ID - This is an internal ID generated on the SessionM Platform.

Combining several of these parameters together might produce the following endpoint:

GET /v1/apps/:api_key/external/users/:external_id/timelines/NEW_VIEW?count=1&since=1530045547&event_types=12,13,14&filter[event_category_id]=123

Note that an important part of this endpoint's syntax is the interplay between the since and count attributes to produce pagination. For example, you might return 300 pages of a view with the following calls:

• Call 1: count = 100 and since is omitted.
• Call 2: count = 100 and since = (timestamp of last value from Call 1)
• Call 3: count = 100 and since = (timestamp of last value from Call 2)

Views rendered in the SessionM UI derive from the activity log for the platform. The value for this view is end_user_member_statement with a context of mmc_customer_campaigns.

Request Object

Not applicable.

Response Object

In addition to a status key-value pair, the response object returned by the method contains the result array, as shown below:

{
  "status": "ok",
  "result": [
    {
      "event_stream_stream_id": "735c10bc-7ddc-11e7-b3e5-0242ac11000b",
      "event_stream_event_category_id": 186,
      "event_stream_event_type_id": 449,
      "target_id": 600,
      "timestamp": 1467830700000,
      "created_at": 1502377143000,
      "event_stream_payload": {
        "tier_level": "Silver",
        "rewards_system_id": "6",
        "event_category_slug": "TIERS",
        "event_type_slug": "TIER_ADVANCED",
        "event_category_name": "TIERS",
        "organization": {
          "organization_name": "SM Tour - TCOLV",
          "uuid": "687b4ce2-61c0-11e7-8406-be8512245348"
        },
        "created_at": "1502377143",
        "request_id": "730646b6-7ddc-11e7-96f4-ff5e1b0abf72",
        "event_type_name": "Tier Advanced",
        "external_ids": []
      },
      "contexts": [
        {
          "id": 21,
          "name": "mmc:customer:campaigns",
          "value": " Tier advanced to Silver"
        }
      ]
    },
    {
      "event_stream_stream_id": "738c2170-7ddc-11e7-b3e5-0242ac11000b",
      "event_stream_event_category_id": 181,
      "event_stream_event_type_id": 441,
      "target_id": 600,
      "timestamp": 1467801120000,
      "created_at": 1502377144000,
      "event_stream_payload": {
        "reason_code": "Reason Code 103: Good Will  +100 points",
        "num_points": 100,
        "rewards_system_id": "6",
        "event_category_slug": "POINTS",
        "event_type_slug": "POINTS_COMPED",
        "event_category_name": "POINTS",
        "organization": {
          "organization_name": "SM Tour - TCOLV",
          "uuid": "687b4ce2-61c0-11e7-8406-be8512245348"
        },
        "created_at": "1502377143",
        "request_id": "72fbed9c-7ddc-11e7-8aec-3984f8bf80a4",
        "event_type_name": "Points Comped",
        "external_ids": []
      },
      "contexts": [
        {
          "id": 21,
          "name": "mmc:customer:campaigns",
          "value": " Reason Code 103: Good Will  +100 points +100.0 points"
        }
      ]
    },
    {
      "event_stream_stream_id": "7303b788-7ddc-11e7-b3e5-0242ac11000b",
      "event_stream_event_category_id": 181,
      "event_stream_event_type_id": 442,
      "target_id": 600,
      "timestamp": 1467744300000,
      "created_at": 1502377143000,
      "event_stream_payload": {
        "num_points": 100,
        "rewards_system_id": "6",
        "event_category_slug": "POINTS",
        "event_type_slug": "POINTS_EARNED",
        "event_category_name": "POINTS",
        "organization": {
          "organization_name": "SM Tour - TCOLV",
          "uuid": "687b4ce2-61c0-11e7-8406-be8512245348"
        },
        "created_at": "1502377143",
        "request_id": "72e9007e-7ddc-11e7-8486-43b6f8bf80a4",
        "event_type_name": "Points Earned",
        "external_ids": []
      },
      "contexts": [
        {
          "id": 21,
          "name": "mmc:customer:campaigns",
          "value": " +100.0 points"
        }
      ]
    }
  ]
}

This object is detailed in the following table:

Response Attributes for Result

Response Attributes for Contexts

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. No error messages are defined for this method except for the generic statuses and errors returned for any object. For more information, see the associated section in Generic Statuses and Errors.

Create a Timeline Type

Create a timeline type.

Endpoints

This method offers the following endpoints:

POST /priv/:api_version/apps/:api_key/timelines/stream_types            

For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Request Object

When this method runs, it passes in a request object that contains a stream_type object, as shown below:

{
    "stream_type": {
        "name": "Name",
        "description": "Description"
    }
}

This object is detailed in the following table:

Request Attributes for Stream Type

Response Object

In addition to a status key-value pair, the response object returned by the method contains a stream_type object, as shown below:

{
  "status": "ok",
  "stream_type": {
      "id": 41,
      "name": "Name",
      "slug": "NAME",
      "description": "Description"
  }
}  

This object is detailed in the following table:

Response Attributes for Stream Type

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. No error messages are defined for this method except for the generic statuses and errors returned for any object. For more information, see the associated section in Generic Statuses and Errors.

Create a Timeline Service

Create an timeline service for the current organization. Doing so creates a kind of super view of all events occurring in the timeline for the organization.

Endpoints

This method offers the following endpoints:

POST /priv/:api_version/apps/:api_key/timelines/streams            

For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

{
  "stream": {
    "event_stream_stream_type_id": 1
  }  
}

Request Object

When this method runs, it passes in a request object that contains a stream object, as shown below:

{
  "stream": {
    "event_stream_stream_type_id": 1
  }  
}

This object is detailed in the following table:

Request Attributes for Stream

Response Object

In addition to a status key-value pair, the response object returned by the method contains a result array, which is a hash array of one or many stream objects. Consider the sample below:

{
  "status": "ok",
  "stream": {
    "id": 7,
    "organization_id": 4,
    "event_stream_stream_type_id": 7,
    "created_at": "2017-01-09T10:27:25-05:00",
    "updated_at": "2017-01-09T10:27:25-05:00"
  }
}

The array is empty if no timelines exist. When present, the stream object can contain the following details:

Response Attributes for Stream

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. No error messages are defined for this method except for the generic statuses and errors returned for any object. For more information, see the associated section in Generic Statuses and Errors.

Retrieve All Timeline Services

Retrieves all existing timeline services for the current organization.

Endpoints

This method offers the following endpoints:

GET /priv/:api_version/apps/:api_key/timelines/streams            

For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Request Object

Not applicable.

Response Object

In addition to a status key-value pair, the response object returned by the method contains a result array, which is a hash array of one or many stream objects. Consider the sample below:

{
  "status": "ok",
  "streams": [
  {
        "stream": {
            "created_at": "2017-08-25T10:47:17-04:00",
            "disabled": false,
            "event_stream_stream_type_id": 51,
            "id": 49,
            "organization_id": 249,
            "updated_at": "2017-08-25T10:47:17-04:00"
        }
  },
  {
        "stream": {
            "created_at": "2017-08-25T10:47:17-04:00",
            "disabled": false,
            "event_stream_stream_type_id": 52,
            "id": 50,
            "organization_id": 249,
            "updated_at": "2017-08-25T10:47:17-04:00"
        }
  },
  {
        "stream": {
            "created_at": "2017-08-25T10:47:17-04:00",
            "disabled": false,
            "event_stream_stream_type_id": 53,
            "id": 51,
            "organization_id": 249,
            "updated_at": "2017-08-25T10:47:17-04:00"
        }
  }
  ]
}

The array is empty if no timelines exist. When present, the stream object can contain several attributes.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. No error messages are defined for this method except for the generic statuses and errors returned for any object. For more information, see the associated section in Generic Statuses and Errors.

Retrieve a Specified Timeline Service

Retrieves a specified timeline service.

Endpoints

This method offers the following endpoints:

GET /priv/:api_version/apps/:api_key/timelines/streams/:timeline_id            

For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Request Object

Not applicable.

Response Object

In addition to a status key-value pair, the response object returned by the method contains a stream object, as shown below:

{
  "status": "ok",
  "stream": {
    "id": 12,
    "organization_id": 17,
    "event_stream_stream_type_id": 12,
    "created_at": "2017-01-30T07:58:18-05:00",
    "updated_at": "2017-01-30T07:58:18-05:00"
  }
}

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Update a Timeline Service

Update an existing timeline service.

Endpoints

This method offers the following endpoints:

PUT /priv/:api_version/apps/:api_key/timelines/streams/:timeline_id            

For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Request Object

When this method runs, it passes in a request object that contains a stream object, as shown below:

{
  "stream": {
    "event_stream_stream_type_id":  1
  }
}

Response Object

In addition to a status key-value pair, the response object returned by the method contains a stream object, as shown below:

{
  "status": "ok",
  "stream": {
    "id": 12,
    "organization_id": 17,
    "event_stream_stream_type_id": 12,
    "created_at": "2017-01-30T07:58:18-05:00",
    "updated_at": "2017-01-30T07:58:18-05:00"
  }
}

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Timeline Configuration API

The Timeline Configuration API supports the creation and retrieval of timeline views, which refine the contents presented by a timeline service by providing specific views, or subsets, of the entire timeline.

Each timeline can have multiple stored “view" definitions. For example, a customer's member statement is a particular view of an all-encompassing customer timeline.

This API also offers objects that create event templates and their corresponding rendering contexts. The event template model defines how an event should be rendered in a given context. The rendering context model is a global list of contexts in which to render events. It targets a template to a type of environment in which to render. For example, mobile:ios.

This API provides the following methods:

• Create a timeline view
• Retrieve details on a timeline view
• Create an event template
• Create a rendering context

Create a Timeline View

Create a view of a specific subset of the timeline's entire history of events.

Endpoints

This method offers the following endpoints:

POST /priv/:api_version/apps/:api_key/timelines/:timeline_id/views            

For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Request Object

When this method runs, it passes in a request object that contains a stream_view object, as shown below:

{
  "stream_view": {
    "name": "Acme Inc.'s member statement",
    "description": "Acme Inc.'s member statement, defined as a view on the user event timeline.",
    "query": "select * from table",
    "event_stream_stream_id": 1
}

This object is detailed in the following table:

Request Attributes for Stream View

Response Object

In addition to a status key-value pair, the response object returned by the method contains a stream_view object, as shown below:

{
  "status": "ok",
  "stream_view": {
    "id": 3,
    "name": "Acme Inc.'s member statement 1",
    "slug": "ACME_INCS_MEMBER_STATEMENT_1",
    "description": "Acme Inc.'s member statement, defined as a view on the user event stream.",
    "event_stream_stream_id": 14,
    "query": "target_id, event_category_id, event_type_ids, since, count"
  }
}

This object is detailed in the following table:

Response Attributes for Stream View

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Retrieve Details on a Timeline View

Retrieve details of a timeline view. The details returned can be presented in a retrieved page of events from the timeline view.

This endpoint operates in the following steps:

1. Fetch page of raw event data from timeline storage service.
2. Fetch rendering templates for the view.
3. Return rendered page of events.

Endpoints

This method offers the following endpoints:

GET /priv/:api_version/apps/:api_key/timelines/:timeline_id/views/:view_id

For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Request Object

Not applicable.

Response Object

In addition to a status key-value pair, the response object returned by the method contains a stream_view object, as shown below:

{
  "status": "ok",
  "stream_view": {
    "id": 3,
    "name": "Acme Inc.'s member statement 1",
    "slug": "ACME_INCS_MEMBER_STATEMENT_1",
    "description": "Acme Inc.'s member statement, defined as a view on the user event stream.",
    "event_stream_stream_id": 14,
    "query": "target_id, event_category_id, event_type_ids, since, count"
  }
}

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Create an Event Template

Create an event template that is used for rendering events on a user's timeline.

Endpoints

This method offers the following endpoints:

POST /priv/:api_version/apps/:api_key/timelines/event_templates            

For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Request Object

When this method runs, it passes in a request object that contains a event_template object, as shown below:

{
  "event_template": {
    "html":  "<p>{{mylist}}{{ item }}{{mylistTypo}}</p>",
    "plain_text": "plain text",
    "event_stream_event_type_id": 7
  }
}

This object is detailed in the following table:

Request Attributes for Event Template

Response Object

In addition to a status key-value pair, the response object returned by the method contains a event_template object, as shown below:

{
  "status": "ok",
  "event_template": {
    "id": 1,
    "event_stream_event_type_id": 7,
    "html": "<p>{{mylist}}{{ item }}{{mylistTypo}}</p>",
    "plain_text": "plain text"
  }
}

This object is detailed in the table below:

Response Attributes for Event Template

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Create a Rendering Context

Create a rendering context, which determines how an event should be rendered in a given context. The rendering context model is a global list of contexts in which to render events. It targets a template to a type of environment in which to render.

Endpoints

This method offers the following endpoints:

POST /priv/:api_version/apps/:api_key/timelines/rendering_contexts            

For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Request Object

When this method runs, it passes in a request object that contains a rendering_context object, as shown below:

{
  "rendering_context": {
     "name": "mmc:customer:campaigns",
     "description": "rendering context description"
   }
}

This object is detailed in the following table:

Request Attributes for Rendering Context

Response Object

In addition to a status key-value pair, the response object returned by the method contains a rendering_context object, as shown below:

{
  "status": "ok",
  "rendering_context": {
    "id": 1,
    "name": "mmc:customer:campaigns",
    "slug": "MMC_CUSTOMER_CAMPAIGNS",
    "description": "description",
    "organization_id": 4982
  }
}

This object is detailed in the following table:

Response Attributes for Rendering Context

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code and a string that can be either ok or error. When the string returned is ok, the transaction processed successfully. When the string returned is error, you need to determine what error occurred. For more information, see Generic Statuses and Errors.