NAV Navbar
json
  • Introduction
  • Getting started
  • Basic API
  • Administrative API
  • 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.

    Email sending

    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
    admin  Hash Containing email and token
    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.

    Allowed parameters for Newsletter hash

    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.