Introduction

This documentation is for v2.0 of Vero’s API. The URLs listed in this documentation are relative to https://api.getvero.com/api/v2.

Sending data with requests

Unless otherwise details, request data should be passed to the API by POSTing JSON objects to the API endpoints specified. The documentation for each API endpoint contains details of the parameters accepted by that endpoint.

Run in Postman

We’ve created a Postman collection to make testing and working with our API simpler.

Run in Postman

Official API libraries

Vero has written official API libraries for the following languages. Clicking the links below will take you to the Github repository for that library where you will find more detailed information on the setup for that library.

Community supported API libraries

Vero’s customers have written and shared a variaty of libraries for the following languages. Clicking the links below will take you to the Github repository for that library where you will find more detailed information on the setup for that library.

Questions or problems?

Have you run into difficulties or can’t get something to work just right? Get in touch via support@getvero.com and we’d be happy to help.

Authentication

To authenticate against the Vero API, you need to use your auth_token in each request. Your `auth_token` can access all of your data and, with future API releases, will be able to read from Vero too. Ensure you keep it secret!

To authenticate against the Vero API, you need to initialize the Vero gem using your api_key and api_secret. Your api_secret is used to access all of your data and, with future API releases, will be able to read from Vero too. Ensure you keep it secret!

To authenticate against the Vero API, you need to initialize the Vero Javascript library using your api_key. In future API releases, your api_secret and auth_token will be able to read from Vero too, however your api_key will only ever be able to track data into Vero.

To access your API credentials, visit the Settings page within your Vero account.

Requests are authenticated by providing a parameter called auth_token containing your `auth_token` with each request.

To authenticate using the Ruby library, setup an initializer. The Ruby library will automatically authenticate and send your tokens with each request.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. You must authenticate for all requests.

curl "https://api.getvero.com/api/v2/users/track" \
  -d "auth_token=AUTH_TOKEN"
# config/initializers/vero.rb

Vero::App.init do |config|     
  config.api_key = "API_KEY" 
  config.secret = "API_SECRET" 
end
// Include this before the </head> section of your HTML.

var _veroq = _veroq || [];
_veroq.push(['init', { api_key: 'API_KEY'} ]);

(function() {var ve = document.createElement('script'); ve.type = 'text/javascript'; ve.async = true; ve.src = '//d3qxef4rp70elm.cloudfront.net/m.js'; var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ve, s);})();
require_once('path/to/vero-php/vero.php');

$v = new Vero('AUTH_TOKEN');

Errors

Vero uses conventional HTTP response codes to indicate success or failure of an API request. Codes in the 2xx range mean success, codes in the 4xx mean there was an error in the data passed to Vero’s API (such as missing parameters) and codes in the 5xx range indicate an error with Vero’s internal servers.

HTTP status codes

Code Description
200 - OK The request was successful
400 - Bad Request Bad request
401 - Unauthorized Your credentials are invalid
404 - Not Found The resource doesn’t exist
50X - Internal Server Error An error occurred with our API

Users

The users endpoint lets you create, update and manage the subscription status of your users.

The user object

Required attributes  
id String The unique identifier of the customer
email String The email address of the customer

There are a small number of reserved properties that will be updated automatically by Vero.

Reserved attributes  
timezone integer The timezone of the user, as a GMT offset (-7, 10, etc.)
language string The IETF, ISO 3166-1 formated language last observed when the user was browing your site
userAgent string The user agent last observed when the user was browsing your site

We also recommend you follow a the patterns below for common user attributes. We have listed our recommendations below. Outside of this, you can add or update any user property you want – properties are completely custom.

Recommended attributes  
first_name String The user’s first name
last_name String The user’s last name
birthday Date The birthdate of the user. We recommend the ISO_8601 format but also accept UNIX timestamps for convenience.
phone String The phone number of the customer

Identify

This endpoint creates a new user profile if the user doesn’t exist yet. Otherwise, the user profile is updated based on the properties provided.

Parameters  
id Required The unique identifier of the customer
email Optional The email of the customer
data Optional A valid JSON hash containing key value pairs that represent the custom user properties you want to update

Note that when using our Javascript library, the data attribute is not used. Key value pairs are passed directly as parameters.

Note: Due to the high volume of requests, all requests to this endpoint are asynchronously processed. Valid requests will return a status 200 Accepted (which, strictly speaking, suggests synchronous processing).

Definition

POST 'https://api.getvero.com/api/v2/users/track'
vero.users.track!
N/A
$v->identify()

Example request

curl 'https://api.getvero.com/api/v2/users/track' \
  -d 'auth_token=AUTH_TOKEN' \
  -d 'id=123' \
  -d 'email=damienb@getvero.com' \
  -d 'data={"first_name": "Damien", "last_name": "Brzoska", "subscription": "medium"}'
include Vero::DSL

vero.users.track!({
  id: '123',
  email: 'damienb@getvero.com',
  data: {
    first_name: 'Damien',
    last_name: 'Brzoska',
    subscription: 'medium'
  }
})
_veroq.push(['user', {
  id: '123',
  email: 'damienb@getvero.com',
  first_name: 'Damien',
  last_name: 'Brzoska',
  subscription: 'medium'
}]);
$v->identify("1234", "john@smith.com",
  array('First name' => 'John',
        'Last name' => 'Smith')
);

Alias

This endpoint lets you change a user’s identifier (id).

Parameters  
id Required The old unique identifier of the user
new_id Required The new unique identifier of the user

Note: The alias method is used to merge two user identities, connecting two sets of user data as one. This is an advanced method, please get in touch if you have questions regarding its usage.

Note: Due to the high volume of requests, all requests to this endpoint are asynchronously processed. Valid requests will return a status 200 Accepted (which, strictly speaking, suggests synchronous processing).

Definition

PUT 'https://api.getvero.com/api/v2/users/reidentify'
vero.users.reidentify!
N/A
N/A

Example request

curl -XPUT 'https://api.getvero.com/api/v2/users/reidentify' \
  -d 'auth_token=AUTH_TOKEN' \
  -d 'id=123' \
  -d 'new_id=456'
include Vero::DSL

vero.users.reidentify!({
  id: '123', 
  new_id: '456'
})
_veroq.push([
  'reidentify', {
  '456', // The new user ID
  '123'// The old user ID
}]);
This endpoint is not supported by the gem at this time.

Unsubscribe

This endpoint unsubscribes a single user.

Parameters  
id Required The unique identifier of the user

Note: Due to the high volume of requests, all requests to this endpoint are asynchronously processed. Valid requests will return a status 200 Accepted (which, strictly speaking, suggests synchronous processing).

Definition

POST 'https://api.getvero.com/api/v2/users/unsubscribe'
vero.users.unsubscribe!
N/A
$v->unsubscribe()

Example request

curl 'https://api.getvero.com/api/v2/users/unsubscribe' \
  -d 'auth_token=AUTH_TOKEN' \
  -d 'id=123'
include Vero::DSL

vero.users.unsubscribe!({
  id: '123'
})
_veroq.push(['unsubscribe', '123']);
$v->unsubscribe('123');

Re-subscribe

This endpoint lets you resubscribe a single user.

Parameters  
id Required The unique identifier of the user

Note: Due to the high volume of requests, all requests to this endpoint are asynchronously processed. Valid requests will return a status 200 Accepted (which, strictly speaking, suggests synchronous processing).

Definition

POST 'https://api.getvero.com/api/v2/users/resubscribe'
vero.users.resubscribe!
N/A
N/A

Example request

curl 'https://api.getvero.com/api/v2/users/resubscribe' \
  -d 'auth_token=AUTH_TOKEN' \
  -d 'id=123'
include Vero::DSL

vero.users.resubscribe!({
  id: '123'
})
_veroq.push(['resubscribe', '123']);
This endpoint is not supported by the gem at this time.

Delete

This endpoint lets you delete a single user.

Parameters  
id Required The unique identifier of the user

Danger: When deleting a user, all properties and activities will be lost forever. Deleted users are not recoverable.

Note: Due to the high volume of requests, all requests to this endpoint are asynchronously processed. Valid requests will return a status 200 Accepted (which, strictly speaking, suggests synchronous processing).

Definition

POST 'https://api.getvero.com/api/v2/users/delete'
N/A
N/A
N/A

Example request

curl 'https://api.getvero.com/api/v2/users/delete' \
  -d 'auth_token=AUTH_TOKEN' \
  -d 'id=123'
This endpoint is not supported by the gem at this time.
This endpoint is not supported by the gem at this time.
This endpoint is not supported by the gem at this time.

Tags

The tags endpoint lets you add or remove tags to or from any of your users.

The Tag object

Attributes  
id String The name of the tag

Add

This endpoint adds a tag to a user’s profile.

Parameters  
id Required The unique identifier of the user
add Required Tags to add

Note: Due to the high volume of requests, all requests to this endpoint are asynchronously processed. Valid requests will return a status 200 Accepted (which, strictly speaking, suggests synchronous processing).

Definition

PUT 'https://api.getvero.com/api/v2/users/tags/edit'
vero.users.edit_user_tags!
N/A
$v->tags()

Example request

curl -X PUT 'https://api.getvero.com/api/v2/users/tags/edit' \
  -d 'auth_token=AUTH_TOKEN' \
  -d 'id=1234' \
  -d 'add=["prospect"]' \
  -d 'remove=[]'
include Vero::DSL

vero.users.edit_user_tags!({
  id: '123', 
  add: ['prospect'], 
  remove: []
})
_veroq.push(['tags', {    
  id: '123',    
  add: ['prospect'],    
  remove: []  
}]);
$v->tags('123',
  array('prospect'),
  array()
);

Remove

This endpoint removes a tag from a user’s profile.

Parameters  
id Required The unique identifier of the user
tag Required Tag to remove

Note: Due to the high volume of requests, all requests to this endpoint are asynchronously processed. Valid requests will return a status 200 Accepted (which, strictly speaking, suggests synchronous processing).

Definition

PUT 'https://api.getvero.com/api/v2/users/tags/edit'
vero.users.edit_user_tags!
N/A
$v->tags()

Example request

curl -X PUT 'https://api.getvero.com/api/v2/users/tags/edit' \
  -d 'auth_token=AUTH_TOKEN' \
  -d 'id=123' \
  -d 'add=[]' \
  -d 'remove=["prospect"]'
include Vero::DSL

vero.users.edit_user_tags!({
  id: '123', 
  add: [], 
  remove: ['prospect']
})
_veroq.push(['tags', {    
  id: '123',    
  add: [],    
  remove: ['prospect']  
}]);
$v->tags('123',
  array(),
  array('prospect')
);

Events API

The events API lets you track events based on actions your customers take in real time.

The event object

Reserved attributes  
event_name String The name of the event you are tracking

Note: Capitals, lowercase, spaces and underscores will all be treated the same by Vero’s API. Purchased Item, purchased item, and purchased_item will all be matched as one event in Vero’s backend.

Track

This endpoint tracks an event for a specific customer. If the customer profile doesn’t exist, Vero will create it.

Parameters  
identity Required A valid JSON hash containing the keys id and email used to identify the user for which the event is being tracked.
Both email and id are must be less than 255 characters and email must be a valid email address.
event_name Required The name of the event tracked.
Must be less than 255 characters.
data Optional A valid JSON hash containing key value pairs that represent any properties you want to track with this event
extras Optional A valid JSON hash containing key value pairs that represent reserved, Vero-specific operators. Refer to the note on “deduplication” below.

You can also track any custom meta data as event properties. The names of each meta data property are completely defined by you – these properties are completely custom.

Deduplication. We will automatically deduplicate events that are sent to our API with the exact same name and event properties and tracked against the same user ID. This deduplication spans a three minute window. This is designed predominantly to solve issues related Javascript-related connection and retry issues.
You can force Vero to ignore deduplication and track every event by including an extras hash in the request that includes a unique check_id field. check_id must be a valid integer. For an example of this in practice, refer to the curl code example.

Note that when using the Javascript library you do not need to pass an identity hash. Instead, ensure you make an identify API call first so that the current user's cookie is stored for use with this endpoint.

Note: Due to the high volume of requests, all requests to this endpoint are asynchronously processed. Valid requests will return a status 200 Accepted (which, strictly speaking, suggests synchronous processing).

Definition

POST 'https://api.getvero.com/api/v2/events/track'
vero.events.track!
N/A
$v->track()

Example request

curl 'https://api.getvero.com/api/v2/events/track' \
  -d 'auth_token=AUTH_TOKEN' \
  -d 'identity={"id": 1234, "email": "john@smith.com"}' \
  -d 'event_name=Viewed product' \
  -d 'data={"product_name": "Red T-shirt", "product_url": "http://www.yourdomain.com/products/red-t-shirt"}' \
  -d 'extras={"check_id": 146273733}'
include Vero::DSL

vero.events.track!({
  identity: {
    id: '123',
    email: 'john@smith.com'
  },
  event_name: 'Viewed product',
  data: {
    product_name: 'Red T-shirt',
    product_url: 'http://www.yourdomain.com/products/red-t-shirt'
  }
}
})
_veroq.push(['track', 'viewed product', {
  product_name: 'Red T-shirt',
  product_url: 'http://www.yourdomain.com/products/red-t-shirt'
}]);
$v->track('Viewed product',
array('id' => '123'),
array(
  'product_name' => 'Red T-shirt',
  'product_url' => 'http://www.yourdomain.com/products/red-t-shirt')
);