REST API #

The REST API provides an integration mechanism for those cases where there is no native SDK that can be integrated with the Marketing Automation Platform.

In all cases, APIs support the EDN format, which has advantages when compared to JSON since different data types are allowed to avoid having to always send information encoded as a string.

In case you still want to use JSON as a serialization format, you must specify the Content-Type and Accept HTTP headers as application/json.

Traces #

The trace API provides a generic traceability mechanism regardless of the type of action or platform where it occurs. As such, it assumes no channel capacity to persist session identifiers -cookies, for example- and each API user must resolve the persistence and association of such information independently.

For cases where, if there is such availability, for example, Internet Browsers, it is recommended to use the existing native SDK.

Trace #

Customers interact with the platform in different sessions or interactions that we call visits (trails). Traces are used to group these visits. In the most usual case, a pre-conversion client interacts several times with different sections of the website, mobile app, or another channel.

Before creating a new trail, it must belong to a trace, so if there is no trace we have to create it. The trace must be generated either the first time a user visits or enters the application, or when they want to close a previous trace, perhaps because the user has already converted to another promotion.

The format of the posted information is an EDN or JSON object with two fields, both optional.

data = {
    :app-token "D17C100F-0668-400A-AF91-967FE1A09A9E"
    :customer-id "5114932"
}

data = {
    "app-token": "D17C100F-0668-400A-AF91-967FE1A09A9E",
    "customer-id": "5114932"
}

The customer-id parameter can be empty if the person interacting is not identified, in which case the system will create an anonymous client for this interaction identifier.

The response is an EDN or JSON object with a trace identifier generated, this trace identifier must be used after each new visit to keep it linked. In case the trace is generated with an identifier of an anonymous client, it will be returned as part of the result.

response = {
    :trace-id "D17C100F-0668-400A-AF91-967FE1A09A9E"
    :customer-id "5114932"
}

response = {
    "trace-id": "D17C100F-0668-400A-AF91-967FE1A09A9E",
    "customer-id": "5114932"
}

The result of the operation is given by one of the following HTTP status codes.

Visits #

A new visit must be generated whenever a user visits the website or opens the mobile application (or uses any other alternative channel).

The format of the posted information is an EDN or JSON object with three fields, where two of them (platform and language) are optional.

data = {
    :language "en-US"
    :platform "Chrome Browser"
    :channel: :atm
}

data = {
    "language": "en-US",
    "platform": "Chrome Browser",
    "channel": "atm"
}

The response is an EDN or JSON object with the visit identifier generated, which will have to be used in the subsequent actions generated within this visit.

response = {
    :trail-id "D17C100F-0668-400A-AF91-967FE1A09A9E"
}

response = {
    "trail-id": "D17C100F-0668-400A-AF91-967FE1A09A9E"
}

The result of the operation is given by one of the following HTTP status codes:

Activity #

As mentioned in the First Steps document, there are different types of activities that can be done within a visit:

The execution is made through the action API, and the format of the posted information is an EDN or JSON object:

data = {
    :name "conversion"
    :type :trail-action/conversion
    :data [
        {
            :name "field1"
            :value "value1"
        }
        {
            :name "field2"
            :value "value2"
        }
    ]
}

data = {
    "name": "conversion",
    "type": "conversion",
    "data": [
        {
            "name": "field1",
            "value": "value1"
        },
        {
            "name": "field2"
            "value": "value2"
        }
    ]
}

The result of the operation is given as one of the following HTTP status codes:

Conversion and No interest #

By using the action API it is possible to indicate when a client converts or if there is a lack of interest in a campaign. Each action has a corresponding type, and the only required parameter to send is tracking-token obtained previously in the channel.

The following information is sent along with the action. For JSON, the action type must be sent without a preffix.

data = {
    :name "conversion"
    :type :trail-action/conversion
    :data [{:name "tracking-token" :value "value"}]
}

data = {
    :name "dismiss"
    :type :trail-action/dismiss
    :data [{:name "tracking-token" :value "valor"}]
}

data = {
    "name": "conversion",
    "type": "conversion",
    "data": [{"name": "tracking-token", "value": "value"}]
}

data = {
    "name": "dismiss",
    "type": "dismiss",
    "data": [{"name": "tracking-token", "value": "value"}]
}

IMPORTANT: Once conversion or dismiss are invoked on a trace, it cannot be used again and a new trace must be created to mark subsequent actions, visits, and synchronizations. In case the same trace is used an invalid request error 400 will be returned.

Campaigns #

Campaign functionalities.

Active Campaigns #

This API allows us to obtain all the campaigns that are active for any given client.

The execution is made through the API:

The format of the posted information is an EDN object:

data = {
    :app-token "D17C100F-0668-400A-AF91-967FE1A09A9E"
    :customer-id "5114932"
    :category "Sales"
    :group "Cars"
    :trail-id  "882252f3-fe70-4402-9195-639d8037f339"
}

Banners and Popups #

Banners and popups as obtained as a result of the app screen synchronization. Whenever the user goes to a new page or screen, several banners can be recovered together, or a single popup for that screen. These actions are made by invoking a single API (sync-page) that obtains all the elements corresponding to that screen for the client.

The format of the posted information is an EDN or JSON object:

data = {
    :app-token "D17C100F-0668-400A-AF91-967FE1A09A9E"
    :customer-id "5114932"
    :trail-id "882252f3-fe70-4402-9195-639d8037f339"
    :sync-popups true
    :page-location "http://my.domain/page"
    :placeholders [{:placeholder "id-placeholder1"} {:placeholder "id-placeholder2"}]
}

data = {
    "app-token": "D17C100F-0668-400A-AF91-967FE1A09A9E",
    "customer-id": "5114932",
    "trail-id": "882252f3-fe70-4402-9195-639d8037f339",
    "sync-popups": "true",
    "page-location": "http://my.domain/page",
    "placeholders": [{"placeholder": "id-placeholder1"}, {"placeholder": "id-placeholder2"}]
}

The response is an EDN or JSON object containing two types of information:

1. Banners to display in each placeholder
2. Information of the Popup to unfold in case it corresponds.

response = {
    :popup = {}
    :placeholders = [{} {}]
}

response = {
    "popup": {},
    "placeholders": [{}, {}]
}

Popup #

The pop-up information structure contains the following data:

popup = {
    :tracking-token
    :campaign
    :show-close
    :funnel
}

In order to display the funnel corresponding to this popup, the conformed URL must be used in the following way: /api/campaigns/:campaign/funnel?d=:tracking-token&a=:app-token&t=:trail-id&popup=true

Placeholders #

The placeholders attribute in the sync-page API response includes the result of banners to display in each of the requested placeholders that contain information. In case a given placeholder does not have associated banners to display for the identified client, no results will be returned.

The response structure of each placeholder is the following:

placeholder = {
    :customer-id "5114932"
    :banners-list [{b1} {b2}]
    :is-popup false
    :popup-timeout 1000
    :transition-time 5000
    :width 800
    :height 600
}

Result description:

Banner detail:

Each object in banners-list contains the detail of one of the banners to display for that placeholder. In case there is more than one, it will be possible to display them in different formats: carousel mode, grid, etc.

The detail of each banner object returned is as follows:

banner-detail = {
    :banner {banner object}
    :funnel {funnel object}
}

Description of the banner object:

Funnel object description:

Within the funnel object, there are properties related to the identified user’s conversion process, along with the data corresponding to the first step of the funnel:

Funnel steps #

In order to obtain the defined steps of the funnel, use the advance-funnel. This API obtains the steps, one by one, as the previous steps are completed.

If there are forks in the funnel, based on the data or other user parameters, the next step in the funnel will only be determined after the current step is completed. This is why we must use the API to obtain the first funnel step when the user is interested in the campaign, as well as the following steps as each step is completed.

The format of the posted information is an EDN or JSON object.

data = {
    :trail-id  "882252f3-fe70-4402-9195-639d8037f339"
    :campaign-id 123123101
    :tracking-token "12312-21919-j1b3-121m-1212"
    :step-data {}
}

data = {
    "trail-id": "882252f3-fe70-4402-9195-639d8037f339",
    "campaign-id": "123123101",
    "tracking-token": "12312-21919-j1b3-121m-1212",
    "step-data": {}
}

The campaign-id and tracking-token parameters must correspond to the interaction the user has made. For example, if the user clicked on a banner, the campaign and tracking-token data corresponding to that banner must be sent. On the other hand, the step-data parameter must not be sent when the user initiates the funnel. In other cases, it must always be sent even if empty, in order to advance in the funnel.

The response structure is the following:

response = {
    :type data-capture | message | redirect
    :config {}
}

The configuration detail for each step type is described below.

Message Step #

step = {
    :title
    :message
    :actions
    :remaining-steps
    :max-steps
}

step = {
    "title":
    "message":
    "actions":
    "remaining-steps":
    "max-steps":
}

Data Capture Step #

step = {
    :fields
    :actions
    :remaining-steps
    :max-steps
}

step = {
    "fields":
    "actions":
    "remaining-steps":
    "max-steps":
}

The fields list indicates which fields must be requested from the client in this step, and it includes the following structure for each field:

field = {
    :label
    :name
    :control-type
    :value
}

field = {
    "label":
    "name":
    "control-type":
    "value":
}

When the next step is requested with advance-funnel, the step data must contain the values of the captured fields using name as a reference.

Redirect Step #

step = {
    :url
    :method
    :parameters
    :include-system-params
    :new-window
}

step = {
    "url":
    "method":
    "parameters":
    "include-system-params":
    "new-window":
}

Customers #

This API allows you to create or update the information of a new or existing customer through the URL shown below:

The format of the posted information is an EDN or JSON object.

data = {
    :customer {:id 12345 :field "xxyyzz"}
    :app-token "882252f3-fe70-4402-9195-639d8037f339"
}

data = {
    "customer": {"id": "12345", "field": "xxyyzz"},
    "app-token": "882252f3-fe70-4402-9195-639d8037f339"
}

| Parameter | Description | | ————- | ———————————– ————————————————– ————- | | app-token | Integrated application identifier making the request, it must be an application that has the REST platform selected | | customer | Client to update, the id data is required, and the rest of the fields that are sent must exist in the defined schema and coincide with the data type. |

The result of the operation is given by one of the following HTTP status codes:

Business Events #

Campaigns can be triggered based on certain Business Events. The nature of a Business Event is of course particular for each company. Prisma provides a way to set up Business Events and trigger campaigns when one of those events occurs.

Business Events have meaning only in the scope of an application. For that reason, the administrator must configure the application that will potentially trigger business events and then define each possible event as a part of the application. This is done in Settings/Applications.

Each business event has a name (which must be unique) and a description and can be added to a campaign in Campaign Settings/Business Events. They apply to all the customers that match the campaign segment but, if needed, a filter can be configured.

When a Business Event is triggered through a POST request, the campaign is selected based on orchestration settings (after proper filtering), this means that the same Business Event can be configured in different campaigns and the system will select the best campaign for the specified event and customer.

The request body must contain the following data:

An invalid application token or an event name that is not defined in the application will result in a 404 response. An empty customer identifier will result in a 400 response. If no customer is found a new one is created.

The field customer-id can be a string representing the customer’s unique identifier or a search specification, i.e.: an object containing key-value pairs. For example:

{
    :app-token "882252f3-fe70-4402-9195-639d8037f339"
    :event-name "newsletter-registration"
    :customer-id {:email "jane.doe@example.com"}
}

{
    "app-token": "882252f3-fe70-4402-9195-639d8037f339"
    "event-name": "newsletter-registration",
    "customer-id": {"email": "jane.doe@example.com"},
}

Providing a field that does not exist in the customer schema will result in a 400 response. If no customer is found a new one is created and the provided data is merged into the new customer.

The request body may also contain the following optional data:

The server will reply with 202 Accepted in case of success, and a 404 Not Found if no matching campaigns are found. Additionally, the response includes the following fields:

Note: The server may reply with an EDN or JSON object depending on the content of the Accept and Content-Type headers, where the former is mandatory. The response field customer-id is the same as the one provided in the request body unless the provided value was a search specification, in which case the response contains the customer identifier of the customer that was found or created.