NAV Navbar
Logo
cURL ruby python javascript php

Introduction

Setting up your Salesmachine takes only a few minutes. Use our libraries to collect customer data from your website, mobile applications, servers and send it to your Salesmachine.

Contact: A contact is a customer that is logged in on your product.

Account: An account is a group of contacts generally represented by a same company/project.

Event: An event is an action a contact performed in your application. Examples: created a new project, invited friends, upgraded to pro, etc.. You can define any event that is specific to your application.

Pageview: A pageview is when a contact loaded a page on your application.

Alias: Link and merge two contacts.

Install

Add salesmachine-ruby to you gem file:

gem 'salesmachine-ruby', '~> 1.0.0'

Initialize client:

require 'salesmachine'
require 'cgi'

$smclient = Salesmachine::Api.new :api_key => YOUR_API_TOKEN

Using pip:

pip install salesmachine-python

Initialize client:

from salesmachine.client import Client

smclient = Client(YOUR_API_TOKEN, YOUR_API_SECRET)
curl -X POST -H "Content-Type: application/json" -u 'YOUR_API_TOKEN:' \
'https://api.salesmachine.io/v1/ping'
<?
Salesmachine::init(YOUR_API_TOKEN, YOUR_API_SECRET);
?>

To install Salesmachine, just paste this snippet into the header of your site:

Full version

var salesmachine = salesmachine || [];
salesmachine.Settings = function(apiToken, options) {
  var script = document.createElement('script');
  script.type = 'text/javascript';
  script.async = true;
  script.src = ("https:" === document.location.protocol ? "https:" : "http:") + "//my.salesmachine.io/javascripts/salesmachine.min.js";
  var firstScript = document.getElementsByTagName('script')[0];
  firstScript.parentNode.insertBefore(script, firstScript);

  var methodFactory = function (type) {
    return function () {
        salesmachine.push([type].concat(Array.prototype.slice.call(arguments, 0)));
    };
  };

  var methods = ['init', 'salesmachine', 'pageview', 'account', 'contact', 'track'];

  for (var i = 0; i < methods.length; i++) {
    salesmachine[methods[i]] = methodFactory(methods[i]);
  }

  salesmachine.init(apiToken, options);
};
salesmachine.Settings("YOUR_API_TOKEN", {});

Minified version

var salesmachine=salesmachine||[];salesmachine.Settings=function(e,a){var n=document.createElement("script");n.type="text/javascript",n.async=!0,n.src="//my.salesmachine.io/javascripts/salesmachine.min.js";var t=document.getElementsByTagName("script")[0];t.parentNode.insertBefore(n,t);for(var s=function(e){return function(){salesmachine.push([e].concat(Array.prototype.slice.call(arguments,0)))}},c=["init","salesmachine","pageview","account","contact","track"],i=0;i<c.length;i++)salesmachine[c[i]]=s(c[i]);salesmachine.init(e,a)};
salesmachine.Settings("YOUR_API_TOKEN", {});

Make sure to replace YOUR_API_TOKEN and YOUR_API_SECRET with your API key.

Authentication is done over HTTPS using Basic Auth with your API credentials. Your Application code will be your application token and your API token will be the password.

Authentication

The API uses HTTP Basic Authentication to authenticate users. A valid API key is required for all requests.

Obtaining an API Key

An API key can be obtained by signing in to salesmachine.io, and then going to App Settings > API Keys. Each app has its own set of API keys. We recommend creating a separate API key for each application that will be making calls on your behalf.

Usage

curl -u '<YOUR_API_TOKEN>:' \
'https://api.salesmachine.io/v1/ping'

The API key must be passed in through the username with the password left blank. The right sidebar has an example request with authorization

Contact

Contact object is the main entity to collect users data.

Contacts can be created or updated via a POST method which accepts a JSON object describing the contact.

Contacts not found via contact_uid will be created, and those that are found will be updated.

$smclient.contact :contact_uid => "123456", :params => {
  email => "elon@teslamotors.com",
  name => "Elon Musk",
  gender => "male",
  mrr => 99,
  account_uid => "78910"
}
smclient.set_contact("123456", {
  "email": "elon@teslamotors.com",
  "name": "Elon Musk",
  "gender": "male",
  "mrr": 99,
  "account_uid": "78910"
})
curl -X POST -H "Content-Type: application/json" -u 'YOUR_API_TOKEN:' \
-d '{"contact_uid":"123456", "params" : { "email":"elon@teslamotors.com", "name":"Elon Musk", "gender":"male", "mrr": 99, "account_uid":"78910" }}' \
'https://api.salesmachine.io/v1/contact'
salesmachine.contact("123456", {
  email: "elon@teslamotors.com",
  name: "Elon Musk",
  gender: "male",
  mrr: 99,
  account_uid: "78910"
});
<?php
Salesmachine::set_contact("123456", array(
  'email' => 'elon@teslamotors.com',
  'name' => 'Elon Musk',
  'gender' => 'male',
  'mrr' => 99,
  'account_uid' => '78910'
));
?>

HTTP Request

POST /v1/contact

Parameters

Required parameters

Value Type Description
contact_uid string Unique identifier referring to a contact, it must match a unique ID in your application like database ID or email address.
Value Type Description
email string Contact email.
name string Contact full name.
account_uid string Account id is a link to an account.

Optional parameters

You can send any parameter, this table is just an example.

Value Type Description
title string Mr, Ms, …
registered_at timestamp Time at which the user registered.
position string CEO, VP Sales, …

Revenue field

Send recurring revenue data to Salesmachine to monitor your revenue health. Monthly Recurring Revenue (MRR) is the standard value you must send to Salesmachine. It should be sent as a parameter called mrr. More details

Value Type Description
mrr number Monthly Recurring Revenue

Account

Account object is the main entity to collect account data. An account is a collection of contacts and a contact can belong to several accounts.

$smclient.account :account_uid => "78910", :params => {
  name: "Tesla Motors",
  employee_count: 10,
  website_url: "http://www.teslamotors.com",
  mrr: 999,
}
salesmachine.set_account("78910", {
  "name": "Tesla Motors",
  "employee_count": 10,
  "website_url": "http://www.teslamotors.com",
  "mrr": 999,
})
curl -X POST -H "Content-Type: application/json" -u 'YOUR_API_TOKEN:' \
-d '{"account_uid":"78910", "params" : {"name":"Tesla Motors", "employee_count":12000,"mrr":999}}' \
'https://api.salesmachine.io/v1/account'
salesmachine.account("78910", {
  name: "Tesla Motors",
  employee_count: 12000,
  website_url: "http://www.teslamotors.com",
  mrr: 999,
});
<?php
Salesmachine::set_account("78910", array(
  'name' => 'Tesla Motors',
  'employee_count' => 12000,
  'website_url': 'http://www.teslamotors.com',
  'mrr'=> 12000
));
?>

HTTP Request

POST /v1/account

Required parameters

Value Type Description
account_uid string Unique identifier referring to an account, it must match a unique ID in your application like database ID.

Recommanded fields

Value Type Description
name string Account name.

Optional parameters

You can send any parameter, this table is just an example.

Value Type Description
employee_count number Number of employees
website_url String Url of the account, if any. We will use it to display account logo in Salesmachine.

Revenue field

Send recurring revenue data to Salesmachine to monitor your revenue health. Monthly Recurring Revenue (MRR) is the standard value you must send to Salesmachine. It should be sent as a parameter called mrr. More details

Value Type Description
mrr number Monthly Recurring Revenue

Event

Events are called when recording a specific action in the application. Events are specific to contacts defined by their unique_id.

$smclient.track(
  :contact_uid => "123456", :event => "user_registration",
  :params => {
    account_uid: "78910",
    display_name: "Registration"
  }
)
smclient.track_event("123456", "user_registration", {
  "account_uid" : "78910",
  "display_name" : "Registration"
})
curl -X POST -H "Content-Type: application/json" -u 'YOUR_API_TOKEN:' \
-d '{"contact_uid":"123456", "event_uid" : "user_registration", "params" : {"account_uid" : "78910", "display_name" : "Registration"}}' \
'https://api.salesmachine.io/v1/track/event'
salesmachine.track("123456", "user_registration", {
  account_uid : "78910",
  display_name : "Registration"
});
<?php
Salesmachine::track_event(
  "123456",
  "user_registration",
  array(
    'account_uid' => '78910',
    'display_name' => 'Registration'
  )
);
?>

HTTP Request

POST /v1/track/event

Required parameters

Value Type Description
contact_uid string Unique identifier referring to a contact, it must match a unique ID in your application like database ID or email address.
event_uid string Event name.

Recommanded fields

Value Type Description
account_uid string Account id is a link to an account already created.
display_name string Human readable event name.

Optional parameters

You can send any parameter.

Pageview

Pageviews are called when recording a specific page in the application. Pageviews are specific to User defined by their unique_id.

$smclient.pageview(
  :contact_uid => "123456",
  :params => {
    account_uid: "78910",
    visit_url: "http://myproduct.com/onboarding",
    visit_ip: "XX.XX.XX.XX",
    visit_agent: "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/43.0.2357.130 Safari/537.36"
  }
)
sm.track_pageview("123456", {
  "account_uid" : "78910",
  "visit_ip": "0.0.0.0",
  "visit_url": "/home",
  "visit_agent": "Mozilla/5.0 (Windows NT 6.2; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/32.0.1667.0 Safari/537.36"
})
curl -X POST -H "Content-Type: application/json" -u 'YOUR_API_TOKEN:' \
-d '{"contact_uid":"123456", "event_uid" : "pageview", "params" : {"account_uid" : "78910", "visit_url" : "http://myproduct.com/onboarding", "visit_ip" : "XX.XX.XX.XX", "visit_agent" : "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/43.0.2357.130 Safari/537.36"}' \
'https://api.salesmachine.io/v1/track/event'
salesmachine.pageview("123456", {
  account_uid : "78910",
});
<?php
Salesmachine::track_pageview(
  "123456",
  array(
    'visit_url' => 'http://myproduct.com/onboarding',
    'visit_ip' => 'XX.XX.XX.XX',
    'visit_agent' => 'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/43.0.2357.130 Safari/537.36'
));
?>

HTTP Request

POST /v1/track/event

Required parameters

Value Type Description
contact_uid string Unique identifier referring to a contact, it must match a unique ID in your application like database ID or email address.

Recommanded fields

Value Type Description
account_uid string Account id is a link to an account already created.
visit_ip string We use it to geolocalize your clients.

Optional parameters

You can send any parameter.

Alias

Only avaiable using http calls.

curl -X POST -H "Content-Type: application/json" -u 'YOUR_API_TOKEN:' \
-d '{"contact_uid":"123456", "alias" : "789"}' \
'https://api.salesmachine.io/v1/alias'

Alias enable mapping between two contacts with two different contact_uid but which are the same contact. When calling alias, the two concerned contacts fields and activities are merged and all calls using on of the two contact_uid will be mapped to the same contact.

HTTP Request

POST /v1/alias

Required parameters

Value Type Description
contact_uid string Unique identifier referring to a contact, it must match a unique ID in your application like database ID or email address.
alias string Unique identifier referring to a contact, it must match a unique ID in your application like database ID or email address.

Optional parameters

There is no optional parameters for alias calls.

Revenue

Revenue screen shot

Send recurring revenue data to Salesmachine to monitor your revenue health. Monthly Recurring Revenue (MRR) is the standard value you must send to Salesmachine. It should be sent as a parameter called mrr in contacts or accounts.

Value Type Description
mrr number Monthly Recurring Revenue

Batch

Already used by the library.

curl -X POST -H "Content-Type: application/json" -u 'YOUR_API_TOKEN:' /
-d '[{"account_uid":"78910", "params" : {"display_name":"Acme", "employee_count":12}, "method":"account"}, {"contact_uid":"123456", "event_uid" : "user_registration", "params" : {"account_uid" : "78910", "display_name" : "Registration"}, "method":"event"}, {"contact_uid":"123456", "event_uid" : "payment", "params" : {"account_uid" : "78910", "display_name" : "Payment"}, "method":"event"}]' /
'https://api.salesmachine.io/v1/batch'

Batch is used to send up to 100 events, accounts or contacts on one call.

HTTP Request

POST /v1/batch

Required parameters

Required paramters depends on batch calls, but the batch method is mandatory for each subcall.

Value Type Description
method string Can be one of contact, account, or event

Errors

Each API call returns an HTTP status code that reflects the nature of the response. We have done our best to follow the HTTP status code conventions.

Any request that did not succeed will return a 4xx or 5xx error. The 4xx range means there was a problem with the request, like a missing parameter. The 5xx range means that something went wrong on our end.

Salesmachine API returns the following codes:

Error Code Meaning
200 OK –- Request succeeded
201 Created –- A resource was created
400 Bad Request – Incorrect or missing API key
401 Unauthorized – Your API key is wrong
404 Not Found – The specified url could not be found
405 Method Not Allowed – You tried to access our api with an invalid method
406 Not Acceptable – You requested a format that isn’t json
429 Too Many Requests – You’re sending too many requests! Slow down, or if you have a high traffic webapp, contact us :-)
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarily offline for maintenance. Please try again later.