Omnisense API Documentation

Base URL : https://app_identifier.app.omnisense.io

Replace "app_identifier" with your unique application identifier.

User data tracking

User profile

This API is used to track all informations about the user himfself.

API : /api/v1/subscriber
Method : POST
Content-Type: application/json
Params :
api_key : String (Mandatory), provided by Omnisense
user : Hash (Optional if udid param is provided), allowed parameters are defined below.
udid : String (Optional if user hash is provided), must be IDFA (iOS) or Google Play ID (Android)
lang : String
platform : String (Optional), when provided, must be one of « android », « iphone »
token : String (Optional), push token (from GCM or APNS).
location : Hash (Optional, must contain latitude/longitude in degrees)
metadata : Hash (Optional), Set of key/values

Allowed parameters for user :

Example :

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

User events recording

This API is used to track user's action such as product view or purchase.

API : /api/v1/user_event
Method : POST
Content-Type: application/json
Params :
api_key : String (Mandatory), provided by Omnisense
email: String, mandatory if udid is not provided
udid: String, mandatory if email is not provided, must be IDFA (iOS) or Google Play ID (Android)
platform: String, mandatory if udid is provided, must be one of "android", "iphone"
user_event: Hash, defined below

Allowed parameters for user_event

identifier: String, name of the event (ex: product.view)
segments: Set of key/values.

Example :

{ "api_key" : "1234567890abcdef09876543210",
  "email": "foo@bar.com",
  "udid": "12345-abcdef-67890-fedcba",
  "user_event": {
    "identifier": "product.view",
    "segments" : {
      "id": "1234",
        "name": "foo",
        "media": "iphone_app"
    }
  }
}

User Event batch create

This API is used to massively import data.

API : /api/v1/user_event/import
Method : POST
Content-Type: application/json
Params :
master_key : String (Mandatory), provided by Omnisense
user_events: Array of user events to create, see below for allowed parameters

Allowed parameters for user_events array

identifier:  String, name of the event (ex: product.view).
segments: Hash, Set of key/values.
email: String, mandatory if udid is not provided
udid: String, mandatory if email is not provided, must be IDFA (iOS) or Google Play ID (Android)
platform: String, mandatory if udid is provided, must be one of "android", "iphone"

Example :

{
  "master_key" : "1234567890abcdef09876543210",
  "user_events" : [
    "email": "foo@bar.com",
      "identifier": "product.view",
      "segments" : {
        "id": "1234",
          "name": "foo",
          "media": "iphone_app"
      }
  ]
}

User Event batch update

This API is used to massively update data based on an identifier. Typically, this identifier is the ID of the object you want to update.

API : /api/v1/user_event
Method : PUT
Content-Type: application/json
Params :
master_key : String (Mandatory), provided by Omnisense
user_events: Array of user events to update, see below for allowed parameters

Allowed parameters for user_events array

update_key : String, The key which will be used to identify the rows to update
object_identifier: String, The object to update
identifier: (optional) String, name of the event (ex: product.view). If none is provided, all events are taken into account.
segments: Hash, Set of key/values to add or update.

Note 1 : All keys not included inside the "segments" hash but already present in the dabatase won't be deleted, whereas new keys will be added.

Note 2 : Update are done in background and may take several minutes.

Example :

{
  "master_key" : "1234567890abcdef09876543210",
  "user_events" : [
     {
        "update_key": "id",
        "object_identifier": "1234",
        "segments" : {
           "name": "bar"
        }
     },
     {
        "update_key": "region",
        "object_identifier": "Languedoc-Roussillon",
        "segments" : {
           "region": "Occitanie",
           "foo" : "bar"
        }
     }
  ]
}

Newsletter

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.

In order to send email, you must configure a sender profile (Settings -> Communication). Follows the steps indicated by Omnisense to configure your profile (Email validation, Domain validation, DKIM & SPF).

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]

API : /api/v1/newsletter
Method : POST
Content-Type: application/json
Params :
master_key : String (Mandatory), provided by Omnisense
admin : Hash, containing email and token
newsletter: Hash, see below for allowed parameters
emails : Array of emails. If an email provided is not found on Omnisense, it is ignored.

Parameters for newsletter hash :

newsletter_template_id : The ID of the template, you can find it in the template listing
sender_profile_id : The ID of the sender profile, you can find it in communication settings page
title : The objet of the email
delivery_time : ISO 8601 Date
is_transactional : true/false , if set to true, bypasses the optin flag of the user.
variables : Set of key/value which will be replaced inside the email.

Example :

{
    "master_key": "YOUR_MASTER_KEY",
    "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.