CxSense developers docs (1.0.0)

Download OpenAPI specification:Download

Introduction

Levels up your CX, faster.

Profile

Profile creates granular customer segmentation with the aim of delivering more relevant experiences by seperating users into distinct groups based on their shared characterisitics.

Create a new profile

Use this API endpoint to create a profile.

Considerations

  • For unsegmented users create a profile without a segmentId.
  • For anonymous users user_id can be empty.
Authorizations:
oAuth2
Request Body schema: application/json

An object containing a user id and optional dictionary of key-value pairs that represent data tied to the user.

user_id
string

User UUID (or any unique user id) specified by consumers.

user_properties
object

Optional dictionary of key-value pairs that represent data tied to the user. You have access to this object in your Destinations.

segmentId
string

Segment identifier

Responses

Request samples

Content type
application/json
{
  • "user_id": "foobar",
  • "user_properties": {
    }
}

Response samples

Content type
application/json
{
  • "error": {
    }
}

Get a user profiles

Authorizations:
oAuth2
query Parameters
user_id
required
any

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a profile

Authorizations:
oAuth2
path Parameters
profileId
required
string

profile identifier

Responses

Response samples

Content type
application/json
{
  • "firstName": "Foo",
  • "lastName": "Bar",
  • "email": "foo@bar.com"
}

Fetch or create a profile

Authorizations:
oAuth2
Request Body schema: application/json
user_id
string

User UUID (or any unique user id) specified by consumers.

user_properties
object

Optional dictionary of key-value pairs that represent data tied to the user.

segmentId
string

Segment identifier

Responses

Request samples

Content type
application/json
{
  • "user_id": "foobar",
  • "user_properties": {
    }
}

Response samples

Content type
application/json
{
  • "error": {
    }
}

Interaction

Interactions are customer behaviours you wish to track and response in your application.

Create a new interaction for a user

An interaction with an Item overrides variation_settings.

Authorizations:
oAuth2
path Parameters
profileId
required
string

profile identifier

Request Body schema: application/json
source
string

Identifier of an event source

event
required
string

unique event identifier.

variation_settings
object

Optional dictionary of key-value pairs that represent variation settings for an event

occurred_at
integer

Timestamp of the event in milliseconds since epoch

object

An item in a catalogue

Responses

Request samples

Content type
application/json
{
  • "event": "login",
  • "variation_settings": {
    },
  • "occurred_at": 1666807081
}

Response samples

Content type
application/json
{
  • "_id": "ofK1OSX8cK3MJI1oPEqQgqgasVtkXJEO",
  • "event": "login",
  • "user_id": "500c145f-4f41-4c00-8e6b-e35306f0fa71",
  • "event_at": 1666807081
}

Journey

Journey is a chain of events you wish to track and response in a segment. Journey can be either simple, containing only one event, or composite, a set of events with different orders and priorities. For example, in an ecommerce website, adding a first product to a wish-list is a simple journey while adding products to a shopping cart followed by a purchase is a composite journey. Additionaly, you can track and response to customer drop-offs. For instance, sending email to customers who has not logged in for three consecutive days.

Funnels

Funnels can be created by chaining journeys. Every subsequent journeys target only the users who has completed the previous journey in a funnel. For example, only offer discount vocuher if a user has already signed up for the free trial of your SaaS product

{
  title: '20-discount-voucher',
  journeySteps: [
    {
      event: 'CTA clicked'
    }
  ],
  previousJourneyId: 'ID of free trial sign up journey'
}

Journey Steps

Index

Index is a number in an ascending order which determines the sequence of events. For example, an event with index 1 has to occure before the event with index 2. Steps with the equal index do not take precedence over each other but all needs to occure for a journey to progress.

[
  {
    event: 'login',
    options: {
      index: 1,
    },
  },
  {
    event: 'win',
    options: {
      index: 2,
    }
  }
]

Short circuit

Steps with equal index can progress as soon as one of the short circuit event happens and do not need to wait for other events with equal index to occur. For example, the win and lose have equal index which means both needs to occur for the journey to progress. However, because win is short curcuited, then even by occuring win the journey progresses.

[
  {
    event: 'win',
    options: {
      index: 1,
      short_circuit: true
    },
  },
  {
    event: 'lose',
    options: {
      index: 1,
    }
  }
]

Frequency

For situations when you need one event to occur multiple times with the same priority, frequency option can be used. For example, consider a scenario that you want a user login and follows by three consequitive wins.

[
    {
      event: 'login',
      options: {
        index: 1,
      },
    },
    {
      event: 'win',
      options: {
        index: 2,
        frequency: 3
      }
    }
]

Variation

Events can have variations. For example, winning a game is an event but winning game X is one variation of that event. In CxSense, you can define as many variation as you need for an event.

[
  event: 'win',
  options: {
    variation_settings: {
      game: 'COD'
    }
  }
]

Additionally, you can define a variation that applies on ANY items in catalogues. For example, imagine your App has multiple games and the journey progresses by winning any games.

[
  event: 'win',
  options: {
    variation_settings: {
      catalogue: 'Game'
    }
  }
]

Drop-offs

Drop-offs sets predefined response to any inaction by users. For example, sending an email to inactive customers who has not logged in for three consecutive days.

[
  event: 'login',
  options: {
    dropoff: {
      after: "3d"
    }
  }
]

Expiry

The expiry parameter defines a time-bound condition for trigger validity within a user journey. It ensures that a specific trigger will only be considered valid if it occurs within a defined time window, starting from a specified reference point.

This reference point can be:

  • A fixed calendar date - ISO8601 format (e.g., "2011-10-05T14:48:00.000Z"), or
  • A dynamic event-based timestamp, such as the time when a previous user action occurred (e.g., a completed signup or email open).

If the defined trigger (e.g., user_login) occurs within the specified expiryIn duration (e.g., 2 days) from the reference point, the journey will proceed to the next step. If the trigger does not occur within that time frame, the pathway is considered incomplete, and the journey will not advance.

[
  event: 'user_login',
  options: {
    expiry: {
      in: "2d",
      from: "2011-10-05T14:48:00.000Z"
    }
  }
]

Create a journey

Authorizations:
oAuth2
Request Body schema: application/json

An object containing a journey details and journey steps

title
required
string
description
string
required
Array of objects (journey_steps)
segmentId
string

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "description": "string",
  • "journey_steps": [
    ],
  • "segmentId": "string"
}

Response samples

Content type
application/json
{
  • "_id": "500c145f-4f41-4c00-8e6b-e35306f0fa71"
}

Destination

Destinations are the real-time callbacks of user progression in journeys. You can attach multiple destinations to a journey.

CxSense transforms your web/mobile application to a trigger machine. Triggers can be utilised in various automation and integration services like Zapier. Destinations are REST hooks. Learn in general how https://resthook.org work.

Authentication

When you add a destination in CxSense, you can CxSense how to authenticate with that destination’s app or endpoints.

String template

You can access your segment data object and users properties you provided in the payload of the requests to the destinations. If you do not provide data, then we send user and segment metadata object to the webhook.

  let data = {
    message: "{user.firstName} won {segment.gameTitle} game!"
  }

Subscribe a destination

Authorizations:
oAuth2
Request Body schema: application/json

An object containing a destination endpoint details

title
required
string
journeyId
required
string
url
required
string
object
method
string
Default: "get"
Enum: "post" "get"
data
object

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "journeyId": "string",
  • "url": "string",
  • "auth": {
    },
  • "method": "post",
  • "data": { }
}

Response samples

Content type
application/json
{
  • "_id": "string"
}

Unsubscribe a destination

Authorizations:
oAuth2
path Parameters
destinationId
required
string

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Run destinations

Run subscribed destinations for a journey for a user.

Authorizations:
oAuth2
path Parameters
destinationId
required
string
Request Body schema: application/json
profileId
required
string

A profile for a destination run

Responses

Request samples

Content type
application/json
{
  • "profileId": "string"
}

Response samples

Content type
application/json
{
  • "error": {
    }
}

Achievement

Achievements are completion of a path within a journey for a user.

Get achievements

Authorizations:
oAuth2
path Parameters
journey_title
required
string
query Parameters
page
integer
Default: 0

The number of pages to skip before starting to collect the result set

limit
integer <= 200
Default: 100

The numbers of items to return

Request Body schema: application/json

By default it returns the last 24 hours achievements of a journey.

segmentId
string

Identifier of a segment

start
integer

Unix epoch time in milliseconds

end
integer

Unix epoch time in milliseconds

Responses

Request samples

Content type
application/json
{
  • "start": 160987009765,
  • "end": 160987009765
}

Response samples

Content type
application/json
{
  • "hits": [ ],
  • "totalHits": 0
}

A user achievements

Authorizations:
oAuth2
path Parameters
user_id
required
string
query Parameters
page
integer
Default: 0

The number of pages to skip before starting to collect the result set

limit
integer <= 200
Default: 100

The numbers of items to return

Request Body schema: application/json

By default it returns the last 24 hours achievements of a user.

segmentId
string

Identifier of a segment

start
integer

Unix epoch time in milliseconds

end
integer

Unix epoch time in milliseconds

Responses

Request samples

Content type
application/json
{
  • "start": 160987009765,
  • "end": 160987009765
}

Response samples

Content type
application/json
{
  • "hits": [ ]
}

Segment

Users can be categorised into distinct segments based on their behaviours and attributes.

The multi-tenant applications can use segments to define multi tenancy.

Create a segment

Authorizations:
oAuth2
Request Body schema: application/json

A JSON object containing a segment data

title
string
description
string
settings
required
object

A set of rules to define a segment

metadata
object

optional dictionary of key-value pairs that represent data tied to the segment

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "description": "string",
  • "settings": {
    },
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "_id": "string"
}

Schema

CxSense supports unstrcutured data for metadata and properties. However, some automation and integration services might need structured data like Zapier. Schema endpoint allows you to manage your schemas.

Create a schema

Authorizations:
oAuth2
Request Body schema: application/json

A JSON object containing a schema data

required
Array of objects

Responses

Request samples

Content type
application/json
{
  • "rule": [
    ]
}

Response samples

Content type
application/json
{
  • "_id": "string"
}

Get a schema

Authorizations:
oAuth2
path Parameters
schemaId
required
string

Responses

Response samples

Content type
application/json
{
  • "rule": [
    ]
}

Catalogue

Catalogue is a collection of items or resources in your system. For example, in a weblog application, articles are defined in a catalogue. In CxSense, catalogue items are structured and require a schema.

CxSense can recommend the most relevant items in a catalogue to users to encourage engagement. Our proprietary AI recommender engine trains by user interactions and items in your catalogues.

Create a catalogue

Create a catalogue

Authorizations:
oAuth2
Request Body schema: application/json
schemaId
required
string

Id of the schema for items in a catalogue

title
required
string

A unique identifier of a catalogue

recommender
boolean
Default: false

Sets AI recommendation for items in this catalogue

Responses

Request samples

Content type
application/json
{
  • "schemaId": "string",
  • "title": "string",
  • "recommender": false
}

Response samples

Content type
application/json
{
  • "error": {
    }
}

Item

Items in catalogues are your resources. You can define them once and on every achievement have access to your resource fields.

Nominated fields in items can be used for traning CxSense recommender system.

Create an item

Create an item

Authorizations:
oAuth2
Request Body schema: application/json
catalogue
required
string

Catalogue unique identifier

id
required
string

A unique identifier of an item in your system

properties
object
Default: "[object Object]"

Request samples

Content type
application/json
{
  • "catalogue": "string",
  • "id": "string",
  • "properties": { }
}

Recommend items

Authorizations:
oAuth2
path Parameters
id
required
string

Item identifier

Request Body schema: application/json
mode
string
Default: "Quick"
type
string
Default: "Item_to_Item"

Responses

Request samples

Content type
application/json
{
  • "mode": "Quick",
  • "type": "Item_to_Item"
}

Response samples

Content type
application/json
{
  • "error": {
    }
}

Authentication

Get Access Token

Exchange your client_id and client_secret with an access token

Authorizations:
oAuth2
Request Body schema: application/json
client_id
required
string
client_secret
required
string
audience
required
string
Value: "https://cxsense.io/api/v1"
grant_type
required
string
Value: "client_credentials"

Request samples

Content type
application/json
{}