Social Proof API | Fomo

The fomo-api Developer Hub

Welcome to the fomo-api developer hub. You'll find comprehensive guides and documentation to help you start working with fomo-api as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    
Suggest Edits

Welcome to Fomo

The world's first Social Proof Automation API

 

Fomo began as an ecommerce plugin, syncing with store orders to showcase sales activity to online visitors in real-time.

Today, Fomo is integrated with 5,500+ websites and powers 500,000,000 notifications per month.

Pending use case, implementing Fomo takes as little as 15 minutes. If you need help integrating with your platform, schedule 30 minutes with our developers.

Suggest Edits

How it Works

 

The primary API interaction is with our Events endpoint.

All events are created via POST requests from your app's front-end / backend, a 3rd party integration, or Zapier. Assuming a 200 Response, Event parameters are added to a live data feed and viewable within the Fomo dashboard. You can also Retrieve all events with the API.

This feed of Events is displayed to end-users on your website as animated notifications, based on the Application Settings you provide for a given Fomo Application.

Below are a couple Fomo notifications from Matchaeologist and Growth Marketing Conference:

Matchaeologist sends purchase orders -- Growth Marketing Conference sends ticket sales.

As you can see, the ability to sync Fomo with your branding spans as deeply as your CSS chops. :)

Understanding Events vs Event Types

Fomo is built for scale, with modularity and separation of concerns top-of-mind.

For this reason, Fomo delineates Event parameters (ie: first_name, city, product_name) from a notification's message structure, ie:
"{{ first_name}} from {{ city }} just bought {{ product_name }}!"

Thus, whenever you POST an Event object hash to the Events endpoint, you'll need to include an Event Type ID.

This tells Fomo how to arrange the parameters you've sent, for display to end-users browsing your website.

Creating Event Types

While you could create EventTypes with the Fomo API, we recommend using our application UI instead -- just log in and click the Templates tab.

Pro Tip - Developer Happiness

Many of our users maintain separate Fomo app instances for their dev, staging, and production environments.

If you do this, feel free to reference the event_type_tag in your Event POST requests (vs event_type_id) to reduce the number of dynamic environment variables needed in your application. This merely requires giving Templates the same name during setup.

Suggest Edits

Available SDKs

 

We're proud to offer official libraries for the following programming languages.

PHP

Node.js

Python

Ruby

Don't see what you need? Let us know.

Suggest Edits

Token-based Auth

 

Before making requests, you need an Auth Token.

To get your Token, log into Fomo and hover Apps (top left) > Your App Name. The auth token will be near the bottom.

Note: API access is only available by default to users on a Paid plan -- you will not see an auth token otherwise. If you need to make test calls before upgrading, send us an email and we'll set it up.

$client = new FomoClient($authToken);
var client = new FomoClient('<token>');
client = Fomo.FomoClient('<token>') 
client = Fomo.new('<token>')
Suggest Edits

Create an event

Send notification parameters to your live Event feed.

 
posthttps://www.usefomo.com/api/v1/applications/me/events
curl "https://www.usefomo.com/api/v1/applications/me/events"
        -H "Content-Type: application/json"
        -H "Authorization: Token {your_auth_token}"
        -d '{"event": {"event_type_id":"123", "external_id": "adf23r",
               "first_name": "John", "city": "New York", "country":"US",
               "title":"San Francisco Dealership", 
               "image_url":"http://some-image-url.png",
               "url":"http://usefomo.com/some-awesome-link",
               "custom_event_fields_attributes": [
                 {"key":"model", "value":"Corvette"}
             ]}}'
        -X POST
$event = new FomoEventBasic();

$event->event_type_id = "4"; // Find ID in Fomo > Templates > Template ID
$event->title = "Test event";
$event->first_name = "Dean";
$event->city = "San Francisco";
$event->url = "https://www.yourawesomesite.com";
// for additional parameters check code documentation

// Add custom attributes to an event
$event->addCustomEventField('variable_name', 'value');

$client->createEvent($event);
var basicEvent = client.FomoEventBasic();

basicEvent.event_type_id = '4'; // Find ID in Fomo > Templates > Template ID
basicEvent.title = 'Test event';
basicEvent.first_name = 'Ryan';
basicEvent.city = 'San Francisco';
basicEvent.url = 'https://www.usefomo.com';
// for additional parameters check code documentation

// Add custom attributes to an event
basicEvent.addCustomEventField('variable_name', 'value');

client.createEvent(basicEvent, function (savedEvent) {
    console.log(savedEvent);
});
event = Fomo.FomoEventBasic()

event.event_type_id = '183' # Find ID in Fomo > Templates > Template ID
event.title = 'Test event'
event.city = 'San Francisco'
event.url = 'https://www.usefomo.com'
# for additional parameters check code documentation

# Add custom attributes to an event
event.add_custom_event_field('variable_name', 'value')

created_event = client.create_event(event)
print(created_event)
# You can create an event by instantiating an object, or passing a hash to the client's create_event method

# for additional parameters check code documentation

# method A
client.create_event(event_type_id: '183', # Event type ID is found on Fomo dashboard (Templates -> Template ID)
                    city: 'San Francisco',
                    first_name: 'Dean',
                    url: 'https://www.usefomo.com',
                    title: 'Test event',
                    custom_event_fields_attributes: [{'key' => 'variable_name', 'value' => 'value'}])

# method B
event = FomoEventBasic.new

event.event_type_id = '183' # Find ID in Fomo > Templates > Template ID
event.city = 'San Francisco'
event.first_name = 'Dean'
event.url = 'https://www.usefomo.com'
event.title = 'Test event'

created_event = client.create_event(event)
A binary file was returned
{
    "id": 1,
    "external_id": "adf23r",
    "event_type_id": "123",
    "url": "http://usefomo.com",
    "first_name": "John",
    "city": "New York",
    "country": "US",
    "title": "San Francisco Dealership",
    "image_url": "http://newevent.com",
    "created_at_to_seconds_from_epoch": 1123123123,
    "message": "John from New York just got a new Corvette at our San Francisco Dealership",
    "link": "http://usefomo.com/some-awesome-link?utm_source=fomo&utm_medium=notification",
    "custom_event_fields_attributes": [
        {
            "key": "model",
            "value": "Corvette"
        }
    ]
}
HTTP/1.1 404 BadRequest
{
  "error": {"message":"Url is not valid"}
}

Query Params

event_type_id
int32
required

Event type unique ID

url
string

Url to redirect on the event click. Size range: 0..255

first_name
string

Firstname of the person on the event. Size range: 0..255

city
string

City where the event happend. Size range: 0..255

province
string

Province where the event happend. Size range: 0..255

country
string

Country where the event happend ISO-2 standard. Size range: 0..255

title
string

Title of the event. Size range: 0..255

image_url
string

Url of the image to be displayed. Size range: 0..255

custom_event_fields_attributes
array

Array to create custom event fields

external_id
string

Optional identifier, useful for preventing duplicates

 

Using the time_ago (timestamps) feature

If you're leveraging the "time_ago" attribute to show timestamps in your events, there's no need to POST any 'created_at' values. Fomo simply uses the derived values from the event record itself.

Suggest Edits

Retrieve an event

Fetch an event object by ID.

 
gethttps://www.usefomo.com/api/v1/applications/me/events/ID
curl "https://www.usefomo.com/api/v1/applications/me/event/1"
  -H "Content-Type: application/json"
	-H "Authorization: Token {your_auth_token}"
  -X GET
$fomoEvent = $client->getEvent("<event ID>"); // ie: 123
client.getEvent('<id>', function (event) {
    console.log(event);
});
event = client.get_event('<event ID>')
print(event)
event = client.get_event('<event-id>')
A binary file was returned
{
    "id": 1,
    "event_type_id": "123",
    "url": "http://usefomo.com",
    "first_name": "john",
    "city": "New York",
    "country": "US",
    "title": "New event",
    "image_url": "http://newevent.com",
    "created_at_to_seconds_from_epoch": 1123123123,
    "message": "John from New York just got a New event",
    "link": "http://usefomo.com?utm_source=fomo&utm_medium=notification",
    "custom_event_fields_attributes": [
        {
            "key": "Model",
            "value": "Clio"
        }
    ]
}

Query Params

id
int32

Event unique id.

 
Suggest Edits

Retrieve all events

Returns an index of all events.

A future version will include pagination and additional meta attributes.

 
gethttps://www.usefomo.com/api/v1/applications/me/events
curl "https://www.usefomo.com/api/v1/applications/me/events"
        -H "Content-Type: application/json"
        -H "Authorization: Token {your_auth_token}"
        -X GET
$fomoEvents = $client->getEvents();
client.getEvents(function(events) {
    console.log(events);
});
events = client.get_events()

print(events)
events = client.get_events
A binary file was returned
[
 { "id":1,
   "event_type_id":"123",
   "url":"http://usefomo.com",
   "first_name": "john",
   "city": "New York",
   "country":"US",
   "title":"New event",
   "image_url":"http://newevent.com",
   "created_at_to_seconds_from_epoch":1123123123,
   "message":"John from New York just got a New event",
   "link":"http://usefomo.com?utm_source=fomo&utm_medium=notification",
   "custom_event_fields_attributes": [
     {"key":"Model", "value":"Clio"}
   ] }, ...
]
 
Suggest Edits

Update an event

Change key value pairs of an existing Fomo event.

 
patchhttps://www.usefomo.com/api/v1/applications/me/events/ID
curl "https://www.usefomo.com/api/v1/applications/me/events/1"
        -H "Content-Type: application/json"
        -H "Authorization: Token {your_auth_token}"
        -d ' { "event_type_id":"123", "external_id":"fdsa23423",
               "first_name": "john", "city": "New York", "country":"US",
               "title":"New event", "image_url":"http://newevent.com",
               "message":"John from New York just got a New event",
               "url":"http://usefomo.com",
               "custom_event_fields_attributes": [
                 {"id":1, "key":"Model", "value":"Clio"}
               ] }'
        -X POST
$fomoEvent = $client->getEvent("<event ID>");
$fomoEvent->first_name = "John";

$client->updateEvent($fomoEvent);
client.getEvent('<id>', function (event) {
    console.log(event);
    event.first_name = 'John';
    client.updateEvent(event, function(updatedEvent) {
        console.log(updatedEvent);
    });
});
event = client.get_event('<event ID>')

event.first_name = 'John'
updated_event = client.update_event(event)

print(updated_event)
event = client.get_event('<event-id>')
event.first_name = 'John'
updated_event = client.update_event(event)
A binary file was returned
{
    "id": 1,
    "event_type_id": "123",
  	"external_id": "fdsa23423",
    "url": "http://usefomo.com",
    "first_name": "john",
    "city": "New York",
    "country": "US",
    "title": "New event",
    "image_url": "http://newevent.com",
    "created_at_to_seconds_from_epoch": 1123123123,
    "message": "John from New York just got a New event",
    "link": "http://usefomo.com?utm_source=fomo&utm_medium=notification",
    "custom_event_fields_attributes": [
        {
            "key": "Model",
            "value": "Clio"
        }
    ]
}

Query Params

event_type_id
int32
required

Event type unique id.

url
string
required

Url to redirect on the event click. Size range: 0..255

first_name
string

Firstname of the person on the event. Size range: 0..255

city
string

City where the event happend. Size range: 0..255

province
string

Province where the event happend. Size range: 0..255

country
string

Province where the event happend ISO-2 standard. Size range: 0..255

title
string

Title of the event. Size range: 0..255

image_url
string

Url of the image to be displayed. Size range: 0..255

custom_event_fields_attributes
array of strings
required

Array to create custom event fields

key
string
required

Key of the custom field

id
int32

Id of the event type (needed only for the update)

value
string
required

Value of the custom field

external_id
string

Optional identifier, useful for preventing duplicates

 
Suggest Edits

Delete an event

Delete a Fomo event by ID.

 
deletehttps://www.usefomo.com/api/v1/applications/me/events/ID
curl "https://www.usefomo.com/api/v1/applications/me/events/1"
        -H "Content-Type: application/json"
        -H "Authorization: Token {your_auth_token}"
        -X DELETE
$client->deleteEvent("<event ID>");
client.deleteEvent("<id>", function(response) {
    console.log(response);
});
client.delete_event('<event ID>')
client.delete_event('<event-id>')
A binary file was returned
{
    "message": "Event successfully deleted"
}
Token is required.
Wrong format (only json allowed).
If application_id is else than me (trying to access other application).
HTTP/1.1 404 BadRequest
{
  "error": {"message":"Url is not valid"}
}

Query Params

id
int32

Event unique id.

 
 

Fomo integrates seamlessly on any website through an asynchronous, Javascript widget that points to an auto purge-caching CDN.

This enables both our users as well as our developers to make ongoing improvements without customers ever needing to update the snippet on their site.

Drop the Fomo snippet on your website once, and you're done.

To learn more about how the Fomo snippet works, see our Basic and Advanced documentation.

Suggest Edits

Basic Usage

 

Every Fomo widget script tag looks something like this:

<script src="https://www.usefomo.com/api/v1/36K9pUyuj8sukckFW66iCg/load.js" async></script>

The identifier following /api/v1 is your application's client_id, which is safe to share publicly.

If you visit the script tag's source URL, you'll notice a basic object with a few properties and convenience methods.

The following object has been truncated to save space, but can you visit this URL to see the latest object notation.

var fomo = {
  version: 1.0,
  initiate: function () {
    this.applyDefaultStyling();

    //Pull in recent events, cache for 40 seconds
    var cached = Math.ceil((new Date().getTime() / 1000) / this.cache) * this.cache;
    var recentOrders = document.createElement('script');
    recentOrders.src = this.settings.fomoUrl + '/js-obj/' + this.clientHash + '/' + this.settings.limit + '/' + cached + '.js';

    if (this.isFomoEnabled()) {
      document.getElementsByTagName('head')[0].appendChild(recentOrders);
    }
    else{
       console.log("Fomo is currently turned off on this domain. To re-enable, log into Fomo and click Apps > Enable (toggle) next to this website.");
    }
  },
  applyDefaultStyling: function () {
    var cssElement = document.createElement('style');
    cssElement.innerHTML = this.settings.themeCss;
    document.getElementsByTagName('head')[0].appendChild(cssElement);
  },
  closed: false,
  cache: 40,
  isFomoEnabled: function () {
    var enabled = true;

    // Should it hide for mobile?
    if (this.settings.hideMobile && this.isMobileDevice()) {
      enabled = false;
    }

    // drop <IE9 support
    if (this.isIE() && (this.isIE() === 7 || this.isIE() === 8)){
      enabled = false;
    }

    return enabled;
  },
  
  // etc, etc.
}

By default, the Fomo widget fires async to your DOM ready functions, and is loaded with relevant Events that match your Application settings.

You may want to debug Fomo in order to tweak CSS styles, check for Events being pre-loaded, etc.

This can be done with the following methods in your browser's developer console:

// get an array of Event objects that match your application settings
fomo.recentEvents

// check if Fomo is enabled on this page
fomo.isFomoEnabled() // returns true/false

// stop the animation sequence, to 'freeze' a given notification's display CSS
fomo.pause()

// manually trigger fomo's setup procedure
fomo.initiate()

// manually trigger fomo's notification animation sequence (ie, if you have a long initial-delay setting and want to test
fomo.runNotifications()

// display a single notification
var events = fomo.recentEvents;
var event = events[0];

fomo.displayNotification(event);

To enable additional features and debugging tools, see Advanced Functionality below.

Suggest Edits

Advanced Functionality

 

For granular control over your Fomo notification logic, enable the manual override setting from the Design > Advanced tab, while logged into the dashboard.

Heads Up

Enabling programatic notification triggers will turn off the default page load strategy. Thus, automatic notifications will stop showing on your website, in exchange for full control.

Example use cases:

  • Show a Fomo notifications after a user adds something to their shopping cart
  • Stop showing notifications when the user signs up
  • Show notifications in rapid succession when a user is looking at a certain page, or area of a page
  • Etc

There are many things you can do with gesture-based notifications -- here are a few working examples:

// triggers the Fomo notifications to start showing
fomo.trigger('start')

// example implementation
$('#start-button').on('click', function(){
  fomo.trigger('start');
});

Fomo uses local storage to track which event notifications have been shown to users. Adding the optional true parameter to restart the event order. 

fomo.trigger('start', true)

// example: 
// There are 6 notifications. Your user sees notification #1, then notification #2. Calling fomo.trigger('start', true) will start back at notification #1.

// triggers the fomo notifications to stop
fomo.trigger('stop')

// Shown notifications are tracked by local storage. fomo.trigger('start') will restart notifications without repeating those previously shown.

fomo.trigger('restartOrder')

// Similar to fomo.trigger('start', true), but without triggering start. This is useful for "looping" -- showing notifications that have already been shown.

fomo.trigger('resetCount')

// Resets the "max per page" count; useful for overriding the maximum notifications per page preference, defined in your Application's Display settings.

Fomo Feed

This setting disables the popup notifications but continues to load the messages from the event, allowing for complete styling control.

How To Activate

Step 1) Within Fomo Admin, go to Design > Advanced.

Step 2) Add Fomo div to your page's HTML. (Required)
Fomo Feed needs to find an element with id='fomo_feed' in order to function.

<div id='fomo_feed'></div>

Step 3) Add some simple CSS to give some spice.

<style>
  #fomo_feed{
    max-width: 400px;
    margin: auto;
    text-align: center;
  }
</style>

Heads Up

Pending your stylesheet setup, you may experience page content being "pushed down" (or up) when your Fomo Feed functionality kicks in. To prevent this, just add a height of "30px" to div#fomo_feed.

Suggest Edits

Get Statistics

Fetch notification impressions, clicks, and conversion data.

 
gethttps://www.usefomo.com/api/v1/applications/me/get_statistics
curl "https://www.usefomo.com/api/v1/applications/me/get_statistics"
        -H "Content-Type: application/json"
        -H "Authorization: Token {your_auth_token}"
        -d '{"from": 123123123, "to": 123432123}'
        -X DELETE
A binary file was returned
{
    "message": "Subscription successfully deleted"
}
{
    "message": "Token is required."
}
{
    "message": "Wrong format (only json allowed)."
}
{
    "message": "If application_id is else than me (trying to access other application)."
}

Query Params

id
int32

Application unique id.

from
int32

Epoch timestamp

to
int32

Epoch timestamp

 
Suggest Edits

Update Application Settings

Change the user experience of a Fomo application.

 
patchhttps://www.usefomo.com/api/v1/applications/me/ID
curl "https://www.usefomo.com/api/v1/users/me/applications/:ID"
        -H "Content-Type: application/json"
        -H "Authorization: Token {your_auth_token}"
        -d '{"application": {"name":"Fomo app", "url":"http://usefomo.com",
        "page_load":1, "maximum_per_page":30, "display_for":1,
        "display_interval":1, "randomize":1", "closable":1,
        "display_period":4, "display_threshold":5, "time_ago_period":1,
        "time_ago_threshold":1, "hide_mobile":false, "loop_notification":true,
        "position":"bottom_left", "theme":"theme1", "utm_source":"fomo",
        "utm_medium":"notification", "event_types_attributes": [ {"id":1, name": "Fomo",
        "message": "Someone in {{ city }}, {{ country }} just purchased
        a {{ linked_title }}", "_destroy":0} ]}'
        -X PATCH
A binary file was returned
{ "id":1,
  "name":"Fomo app",
  "url":"http://usefomo.com",
  "page_load":1,
  "maximum_per_page":30,
  "display_for":1,
  "display_interval":1,
  "randomize":1",
  "closable":1,
  "display_period":4,
  "display_threshold":5,
  "time_ago_period":1,
  "time_ago_threshold":1,
  "hide_mobile":false,
  "loop_notification":true,
  "position":"bottom_left",
  "theme":"theme1",
  "utm_source":"fomo",
  "utm_medium":"notification",
  "client_id":"appid",
  "client_secret": "app secret"
  "event_types_attributes": [ {
    "id": 1,
    "name": "Fomo",
    "message": "Someone in {{ city }}, {{ country }}
    just purchased a {{ linked_title }}",
    "_destroy":0} ],
  "stat_application": {"click_count": 1, "display_count": 1,
   "conversions_count": 1, "conversions_sales_sum": 200}}'
HTTP/1.1 404 BadRequest
{
  "error": {"message":"Url is not valid"}
}

Query Params

id
int32

Application unique id

name
string

Application unique name. Size range: 0..255

url
string

Application unique url. Size range: 0..255

language
string

Language of application ISO-2 standard. Default value: en Size range: 0..255

installed
boolean

If the application was installed. Deprecated, will be removed.

page_load
int32

Delay for widget to be displayed on page. Default value: 1

maximum_per_page
string

Maximum number of returned notifications in one call.

display_for
int32

Delay between display of notifications.

display_interval
int32

How much time each notification is displayed.

randomize
boolean

Display random notifications.

closable
boolean

Allow the widget to be closed.

display_period
int32

1 for seconds, 2 for minutes, 3 for hours 4 for days.

display_threshold
int32

display_threshold * display_period defines the time limit from which the notifications are displayed.

time_ago_period
int32

1 for seconds, 2 for minutes, 3 for hours 4 for days.

time_ago_threshold
int32

time_ago_threshold * time_ago_period defines the time limit from which the notifications are displayed.

hide_mobile
boolean

Hide the widget on mobile.

loop_notification
boolean

Display the notifications just once or loop them.

position
string

The position where the widget is displayed. Default value: botom_left. Allowed: 'bottom_left', 'bottom_right', 'top_left', 'top_right'

theme
string

Style theme for the widget. Default value: theme1. Allowed: 'theme1', 'theme2', 'custom'

utm_source
string

UTM Source parameter (for Google Analytics, etc). Default value: fomo.

utm_medium
string

UTM Medium parameter (for Google Analytics, etc). Default value: notification.

event_types_attributes
array of strings

Array of event_types

 
 

Fomo can send webhooks to give you a summary of your analytics. These are sent every 4 hours.

All you need to do is provide an endpoint and select your options.

Once your webhook is saved, you can test so you don't have to wait the 4 hours interval.

A sample payload (JSON).

{"stats":	     			
 {"timeframe_from":1474604187, // Unix timsestamp
  "timeframe_to":1474618587, // Unix timsestamp
  "click":300, // Integer
  "display":10 // Integer
 }
}

A great third-party resource for testing HTTP request is https://requestb.in
Note: Fomo is not affiliated with RequestBin.