NAV
shell ruby javascript

Introduction

Welcome to the dotIn API!

We are a team of passionate technologists from Silicon Valley who are dedicated to understanding the art of decisions made by the subconscious mind to yield powerful business outcomes. We do this using the science of psychological, structured/unstructured social or enterprise data and machine learning to tap into the subconscious mind of humans. This enables us to capture the true digital personality fingerprint of every user.

Here you can find examples of our API usage and links to full API description

Authentication

Browser authentication

Browser authentication from a page with Javascript:

# not applicable. Browser side only
# not applicable. Browser side only
DOTIN = {}

DOTIN_SERVICE = "http://api.dotin.us";

DOTIN.SERVICE = DOTIN_SERVICE

DOTIN.setUserPass = function(id, key) {
  this.user = id
  this.password = key
  this.auth = btoa(id + ":" + key)
  this.authorized = false
}

//method - HTTP request type (GET, POST)
//path - API path
//func - callback function
//do_login - flag which indicates if authorization header should be added
//data - POST body
DOTIN.makeRequest = function(method, path, func, do_login, data) {
  var strUrl = this.SERVICE + path;
    $.support.cors = true;
    ajax_params = {
      type: method,
      dataType: 'json',
      contentType: 'application/json',
      data: data,
      url: strUrl,
      crossDomain: true,
      success: function(data) {
        console.log("success");
        this.authorized = true
          if (func != null)
            func(data)
      },
      error: function(jqXHR, textStatus, errorThrown) {
        console.log("error");
        if (jqXHR.status == 401) {
          this.getData(path, func)
        } else if (jqXHR.status == 0 && func != null) {
          func(data);
        } else if (jqXHR.status == 200 && func != null) {
          func(data);
        }
      }, xhrFields: {
        withCredentials: true
      }
    }
  if (do_login != null || this.authorized == false){
    ajax_params.headers = { "Authorization": "Basic " + (do_login || this.auth)}
  }
  jQuery.ajax(ajax_params);
}

DOTIN.setUserPass("userId", "skey");

//EXAMPLE:
data = JSON.stringify({
  "some": "data"
});

// sending authrized post request
DOTIN.makeRequest("POST", "/some/post/api", function(data){}, null, data);

// sending authorized get request
DOTIN.makeRequest("POST", "/some/post/api", function(data){});


Browser authentication is the most general use case for the dotin API. We are using external authentication servers like Google or Facebook. All these authentication servers provide OAuth2 protocol.

Below endpoints can be used to activate browser side authentication:

Provider Endpoint URL
Facebook http://api.dotin.us/connect/facebook/v1.0
LinkedIn http://api.dotin.us/connect/linkedin/v1.0
Google http://api.dotin.us/connect/google/v1.0
Twitter http://api.dotin.us/connect/twitter/v1.0

After authentication user is forwarded back to the reference page with set cookie ibq_uid and remember-me for top-level domain .dotin.us. Alternate ways to authorise is to use Basic authentication. In this case user need to get plain userId and skey values. These values can be obtained as the response of the social network authorization APIs shown above.

If you authorize for the first time new user profile will be created. If user calls another social network authorization API, new data will be obtained from the network and merged with the existing profile.

Server side authentication

To authorize, use this code:

# With shell, you can just pass the correct header with each request
# http://api.dotin.us/users/public/getUser/v2.0?id=someid is the example of the api request.
# userId and skey are credenitals (for more info see description)

curl --request GET \
  --url 'http://api.dotin.us/users/public/getUser/v2.0?id=57e375f2e4b0daaeec626f88' \
  --header 'authorization: Basic $(echo -n 'userId:skey' | base64)" 
require 'uri'
require 'openssl'
require 'net/http'
require 'json'

HOST = "http://api.dotin.us"

module AuthAPI
  def set_user(userId, skey)
    @username = userId
    @password  = skey
  end

  def request(req, uri, user, pass)
    req.basic_auth user, pass if user
    res = Net::HTTP.start(uri.hostname, uri.port) { |http| http.request(req) }
    if res.code.to_i >= 400
      # error
    end
    return JSON.parse(res.body)
  rescue Exception => e
    puts e.message
      # Rescue
    return nil
  end


  def post_req(api, data, user = @username, pass = @password)
    uri = URI("#{HOST}#{api}")
    req = Net::HTTP::Post.new(uri, initheader = {'Content-Type' =>'application/json'})
    req.body = data
    request(uri, req)
  end

  def get_req(api, user = @username, pass = @password)
    uri = URI("#{HOST}#{api}")
    req = Net::HTTP::Get.new(uri)
    request(uri, req, user, pass)
  end

  def upload_file(url, file)
    url = URI(url)
    http = Net::HTTP.new(url.host, url.port)
    http.use_ssl = true
    http.verify_mode = OpenSSL::SSL::VERIFY_NONE
    request = Net::HTTP::Put.new(url)
    request["cache-control"] = 'no-cache'
    request.body = File.read(file)
    response = http.request(request)
    return JSON.parse(response.read_body)
  end
end

# Example of sending request with authentication

class ExampleReader
  include AuthAPI

  def example_post
    data = { "some" => "data" }.to_json
    api = "/some/post/api"
    post_req api, data
  end

  def example_get
    api = "/some/get/api"
    get_req api
  end
end

reader = ExampleReader.new
reader.set_user("userId", "skey")

# sending authrized post request
reader.example_post

# sending authorized get request
reader.example_get

Not applicable. See Ruby code.

To perform server side authentication, user need to get userId and skey of your user profile. These values can be obtained as the response of the social network authorization APIs described upwards.

If you want to use our API on server side to do data gathering you have to provide an access tokens. This will allow us to gather information and authenticate a user.

API for images uploading

In this section user will find description of APIs for uploading images into our engine. These images are used for a personality analysis.

Direct upload

Direct images uploading

curl --request POST \
  --url http://api.dotin.us/image/v1.0/upload \
  --header "authorization: Basic $(echo -n 'userId:skey' | base64)" \
  --header 'cache-control: no-cache' \
  --header 'content-type: multipart/form-data; boundary=---011000010111000001101001' \
  --form file=@path/to/your/image.png
require 'net/http/post/multipart'

url = URI.parse('http://api.dotin.us/image/v1.0/upload')
File.open("./path/to/your/image.jpg") do |jpg|
  req = Net::HTTP::Post::Multipart.new url.path,
    "file" => UploadIO.new(jpg, "image/jpeg", "path/to/your/image.jpg")

  req.basic_auth "userId", "skey"
  res = Net::HTTP.start(url.host, url.port) do |http|
    http.request(req)
  end

  res.body
end
// not applicable. See ruby

This API helps in uploading raw images of current user for further analysis

See swagger

The above command returns JSON structured like this:

{
  "id":"...some_internal_id....",
  "imageId":"...some_imageId..."
}

imageId field can be used to retrieve images: http://api.dotin.us/image/get/v1.0/...some_imageId...

Uploading from a link

curl -X POST -H "Content-Type: application/json" -H "Cache-Control: no-cache" -d '{
    "link": [
      "example.com/path/to/your/image1.jpg",
      "example.com/path/to/your/image2.jpg"
    ]
  }' "http://api.dotin.us/image/upload/v1.0/link"
class ImageUploader
  include AuthAPI

  def loadImagesByLinks(links)
    api = "/image/upload/v1.0/link"
    data = {
      "link": links
    }.to_json
    post_req api, data
  end
end

uploader = ImageUploader.new

uploader.set_user("userId", "skey")

uploader.loadImagesByLinks([
      "example.com/path/to/your/image1.jpg",
      "example.com/path/to/your/image2.jpg"
    ]);

// require class from authentication

data = JSON.stringify({
    "link": [
      "example.com/path/to/your/image1.jpg",
      "example.com/path/to/your/image2.jpg"
    ]
  });

DOTIN.makeRequest("POST", "/image/v1.0/links/{{userId}}", function(data){}, null, data);

This API uses external link to upload user’s current images for further analysis.

See swagger

The above command returns JSON structured like this:

[
  {
    "id":"...some_internal_id....",
    "imageId":"...id_of_image_1..."
  },
  {
    "id": "...some_internal_id....",
    "imageId": "...id_of_image_2..."
  }
]

imageId can be used to retrieve images: http://api.dotin.us/image/get/v1.0/...id_of_image_1...

API Get user information

Get user profile shell curl -X GET -H "Authorization: Basic $(echo -n 'userId:skey' | base64)"\ -H "Cache-Control: no-cache" "http://api.dotin.us/users/getUser/v2.0?id={{userId}}"

# require mixin from authentication

class UserInformationLoader
  include AuthAPI

  def getUserInformation(user_id)
    api = "/users/getUser/v2.0?id=#{user_id}"
    get_req api
  end
end

loader = UserInformationLoader.new

loader.set_user("userId", "skey")

loader.getUserInformation("some_user_id")

// require class from authentication
DOTIN.makeRequest("GET", "/users/getUser/v2.0?id={{userId}}", function(data){});

This API fetches full information about selected user, including result of intellectual analysis and user profile information from social network. The response includes three kinds of profile: Personal, Professional and Personality.

Each profile contains a number of attributes which consist of parameters like value, type, descriptions, provider and weight. All parameters are optional except for value.

See swagger

The above command returns JSON structured like this:

{
  "profiles": [
    {
      "name": "personality",
      "attributes": [
        {
          "name": "dominant_attr",
          "groups": [
            [
              {
                "name": "dominant_attr",
                "value": [
                  "Natural"
                ]
              },
              {
                "name": "provider",
                "value": [
                  "color"
                ]
              },
              {
                "name": "weight",
                "value": [
                  "1.0"
                ]
              },
              {
                "name": "description",
                "value": [
                  "Some description of attribute value here"
                ],
                "type": "DESCRIPTION"
              }
            ]
          ],
          "access": "private",
          "label": "Positive Personality Attributes"
        }
      ]
    }
  ]
}

User can also use additional get parameter pack which allows you to get subset of parameters.

pack parameter can take following values:

value attributes subset
personality_insights
Positive Personality Attributes
Negative Personality Attributes
Compatibility Personality match
Hollands Occupational Assessment
Gardner’s Multiple Intelligence and Learning Style
—– ——————
buying_behavior
Positive Personality Attributes
Negative Personality Attributes
Compatibility Personality match
Hollands Occupational Assessment
Gardner’s Multiple Intelligence and Learning Style
Colors Affinity
Buying Preferences
Products Buying affinity
Products Buying non-affinity
—– ——————
employee_engagement
Positive Personality Attributes
Negative Personality Attributes
Compatibility Personality match
Hollands Occupational Assessment
Gardner’s Multiple Intelligence and Learning Style
Colors Affinity
Employment affinity
Employment non-affinity
—— ——–
compatibility_match
Compatibility Personality match

AutoSync of Latest Images Of Logged in User

Operate images of logged in user

curl -X GET --header 'Accept: text/html' 'http://api.dotin.us/image/getRecentImages/v1.0?limit=10'
# 'http://api.dotin.us/image/getRecentImages/v1.0?limit=10'
// require class from authentication
DOTIN.makeRequest("GET", "/image/getRecentImages/v1.0?limit={{limit}}", function(data){});

This API automatically picks up latest images of logged in user and replace them with old images with a default “limit” of 10. Each getRecentImages does the operation of replacement of old images. Since the image analysis is an asynchronous process the images will not be processed instantly.

Errors

Example of JSON data in HTTP response

{
  "url": "http://api.dotin.us/users/public/getUser/v2.0",
  "message": "User does not exist"
}

If your HTTP request cause any error, you receive an HTTP response with an appropriate error code.

Supported HTTP error codes:

Code Cause
400 Bad request (not correct/inappropriate data in request)
403 Access denied (wrong credentials, no credentials)
404 Resource not found
503 Service unavailable

The HTTP response contains additional JSON data with textual description of the error in the message field. URL which caused the error is stored in the url field. See an example in the code section.

Examples of the textual error’s description obtained from the message field:

Description
User does not exist
No token found
Exception while handling Oauth2 callback