Introduction

Welcome on the Omnisense API documentation v1.0. You can use these to retrieve and add informations on your Omnisense instance.

Omnisense is an omnicanal CRM.

With Omnisense, you can manage the entire lifecycle of your users : Acquisition, Segmentation, Reengagement.

Acquisition : Omnisense is connected to the main advertising companies of the market and will allow you to manage your acquisition easily.

Segmentation : Retrieve all your user data within a clear and intuitive interface and segment them in a few clicks.

Reengagement : Push, mails, sms ... You can reengage your users with all possible and unimaginable means...

Getting started

We consider the base url you will use :

https://YOUR_INSTANCE.app.omnisense.io/api/v1

where YOUR_INSTANCE has to be replaced with your instance subdomain. This is the same as the "universe" you choose when connecting to your instance.

Basic API

These API are used by our SDKs. You have to use them in order to track data from your users.

User data

The purpose of this API is to send all available data about your user. The list of available fields are displayed on the right part. Note that you can send any data not available on the user Hash into the metadata Hash, which accepts any pair of key/values (only Strings).

JSON Parameters example

{
  "api_key" : "1234567890abcdef09876543210",
  "udid": "12345-abcdef-67890-fedcba",
  "trid": "9876543210abcdef1234567890",
  "user": {
    "email": "foo@bar.com",
    "first_name": "Foo",
    "last_name": "Bar",
    "lang": "fr"
  },
  "location": {
    "latitude":"42.6932879",
    "longitude":"2.8951097"
  },
  "metadata": {
    "purchase_count": "5"
  }
}

Allowed user hash example

{
  "email" : "String",
  "fb_id" : "String",
  "first_name" : "String",
  "last_name" : "String",
  "birthday" : "Date",
  "phone" : "String",
  "address" : "String",
  "city" : "String",
  "postal_code" : "String",
  "country" : "String", #must be the iso code for country (ISO 3166)
  "lang" : "String", #must be the iso code for lang (ISO 639)
  "sex" : "String", #One of "male", "female"
  "optin" : Boolean, #Set to true if the user is optin to receive email
  "optin_sms" : Boolean, #Set to true if the user is optin to receive SMS
  "registered" : Boolean, #Set to true if the user has signed up to your website
  "custom_event_date" : "Date",
  "company" : "String"
}

HTTP Request

POST /subscriber

Mandatory Parameters

One of theses three parameters need to be set in your JSON.

Parameter	Value	Description
udid	String	Must be IDFA (iOS) or Google Play ID (Android)
trid	String	Returned by the API after each call. Unique identifier for your user.
user	Hash	Allowed parameters are defined below.

Optional Parameters

Parameter	Value	Description
platform	String	When provided, must be one of "android", "iphone"
token	String	Push token (from GCM or APNS).
location	Hash	Must contain latitude/longitude in degrees
metadata	Hash	Set of key/values (String / String)

Metadatas

A metadata can be anything you want as a hash of key/values.

Actions / Events

The purpose of this API is to track actions realized by your user. Typically, you will use it to track product view / cart / purchase.

HTTP Request

POST /user_event

JSON example

{
  "api_key" : "1234567890abcdef09876543210",
  "trid": "9876543210abcdef1234567890",
  "email": "foo@bar.com",
  "user_event" : {
    "identifier": "product.view",
    "segments" : {
      "id": "1234",
      "name": "foo",
      "media": "iphone_app"
    }
  }
}

Mandatory parameters

Parameter	Value	Description
user_event	Hash	The user event to create
trid	String	Unique identifier for your user
email	String	Email of your user

trid is mandatory if email is not set

Allowed parameters for users_events

Parameter	Value	Description
identifier	String	name of the event (ex: product.view).
segments	Hash	Set of key/values.

Administrative API

These API are authenticated, you need a master_key and credentials (email/token) in order to use any of these API.

All the API below require the master_key/credentials to be added in the body of your request, as listed below :

Parameter	Value	Description
master_key	String	The master key, unique to your website/app
admin	Hash	Containing "email" and "token" fields

Email API

You can send email through Omnisense's API. The main purpose is to send transactional email such as welcome email, or a confirmation of order, but you can also send marketing email if necessary.

Then, you have to create a template based on one of the availables templates, which will be used as a base for your email. You can set variables to customize the content of your email. The format of the variables inside the template is : [name_of_your_var]

HTTP Request

POST /newsletter

JSON example

{
  "master_key" : "1234567890abcdef09876543210",
  "admin": {
        "email": "YOUR_LOGIN_EMAIL",
        "token" : "YOUR_TOKEN"
    },
    "newsletter": {
        "newsletter_template_id" : 45,
        "sender_profile_id": 11,
        "title": "Lorem ipsum title",
        "delivery_time": "2017-06-30 11:45:00",
        "is_transactional": true,
        "variables": {
            "promo_code": "123456",
            "promo_link": "https://omnisense.io?promo=123456"
        }
    },
    "emails": ["yourcustomer@test.com"]
}

NB : You can use user's attributes in your template in addition to the variables provided in the API.

Mandatory parameters

Parameter	Value	Description
newsletter	Hash	See below for allowed parameters
emails	Array	Array of emails strings. Note: If an email provided is not found on Omnisense, it will be ignored.

Parameter	Value	Description
newsletter_template_id	Integer	The template ID, find it in the template listing
sender_profile_id	Integer	The sender profile ID, find it in the communication settings page
title	String	Email object
delivery_time	Date	ISO 8601 Date
is_transactional	Boolean	if set to true, this parameters will allow the query to bypass the optin flag of the user.
variables	Hash	Set of key/value which will be replaced inside the email.

Import users

POST /subscriber/import


  master_key = "1234567890abcdef09876543210"
  admin[email] = "YOUR_LOGIN_EMAIL"
  admin[token] = "YOUR_TOKEN"
  csv = Your file.csv

The csv field must contain a CSV file encoded in UTF8 without Byte Order Mark (BOM). Please follow the format accepted by Omnisense which is available here.

You can import/update multiple users at once via this API. This API must be call via a POST http request, in multipart/form-data format.

Import actions

POST /user_event/import

JSON Example


{
"master_key" : "1234567890abcdef09876543210",
"admin": {
  "email": "YOUR_LOGIN_EMAIL",
  "token" : "YOUR_TOKEN"
},
"user_events": [
  {
    "email": "yourcustomer@test.com",
    "date": "2018-11-13 10:00:00Z",
    "identifier": "product.order",
    "segments" : {
      "order_id": 1234,
      "order_amount": 150,
      "order_currency": "EUR",
      "payment": "cb",
      "product_id": "the_product_ref",
      "product_price": 75,
      "product_quantity": 2,
    }
  },
  {
    "email": "anothercustomer@test.com",
    "identifier": "product.order",
    "date": "2016-09-13 11:00:00Z",
    "segments" : {
      "order_id": 2345,
      "order_amount": 250,
      "order_currency": "EUR",
      "payment": "check",
      "product_id": "the_product_ref",
      "product_price": 150,
      "product_quantity": 2,
    }
  },
  ...
]
}

You can import multiple actions at once via this API. This API must be call via a POST http request.

Parameter	Value	Description
user_segments	Array	The list of action to import

Then the fields for each action :

Parameter	Value	Description
email	String	Email of the user who made the action
date	Date	When the action occured
identifier	String	Identifier of the action (product.view, product.cart...)
segments	Hash	Contains a set of key/value describing the action

Opt-in / Opt-out callback notification

Example of opt-out notification

Callback URL : https://www.yourwebsite.com/api/omnisense_callbacks?secret_key=mysecretkey

{
    "email": "yourcustomer@test.com",
    "notification_type": "optout",
    "optout_type": "unsubscription",
    "optout_at": "2018-10-05 08:30:00 +0200"
}

Example of opt-in notification

Callback URL : https://www.yourwebsite.com/api/omnisense_callbacks?secret_key=mysecretkey

{
    "email": "yourcustomer@test.com",
    "notification_type": "optin",
    "optin_at": "2018-10-05 08:30:00 +0200"
}

You can receive opt-in/opt-out notification from Omnisense when :

A user opt-in from its personal information panel
A user opt-out from your newsletters (or when an email sent is bounced permanently).

In order to set a callback, you have to go to Settings > Communications and click on "DNS & Callback settings" and fill the "Callback URL" field.

Callbacks are sent for each opt-out, with a POST http request containing a json body. On the right are examples of the body's request.

"optout_type" can be one of unsubscription, bounce, complaint "notification_type" can be one of optout, optin Note : You should add a "secret key" parameter to secure your callback API.

Introduction

Getting started

Basic API

User data

HTTP Request

Mandatory Parameters

Optional Parameters

Metadatas

Actions / Events

HTTP Request

Mandatory parameters

Allowed parameters for users_events

Administrative API

Email API

HTTP Request

Mandatory parameters

Allowed parameters for Newsletter hash

Import users

Import actions

Opt-in / Opt-out callback notification