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 specified, request data should be passed to the API as JSON objects via POST. The documentation for each API endpoint contains details of the parameters accepted by that endpoint.

Official API libraries

Vero has written official API libraries for the following languages. The Github repository for each library contains more information on setup and usage.

Community supported API libraries

We don't guarantee that all community-supported libraries are maintained and up to date. We keep them linked here as they can be a useful reference.

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 setup and usage.

Questions or problems

Have questions or can’t get something to work? Get in touch via support@getvero.com or join our community Slack channel.

Authentication

Authentication against the Vero API is done using a valid Authentication Token. Authentication Tokens should be kept secret. They have the power to write data to your account and, in the future, will have the ability to read data too.

To authenticate against the Vero API, you need to initialize the Vero gem using a valid API Key and API Secret. API Secrets should be kept secret. In the future, API Secrets will have the ability to read data from your Vero account.

To authenticate against the Vero API, you need to initialize the Vero Javascript library using a valid and active API Key. Whilst in future API releases API Secrets and Authentication Tokens will be able to read from your Vero account, API Keys will only ever be able to track data into Vero.

To generate and access API credentials visit the Settings page in your Vero account.

Requests are authenticated by providing a parameter called auth_token with each request. This parameter must contain a valid and active Authentication Token.

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

All API requests must be made over HTTPS. Calls made over plain HTTP will fail.

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 the 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 endpoint.

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 user records.

The user object

Required attributes  
id String The unique identifier of the customer.

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

Reserved attributes  
email String The email address of the customer. Note: If you supply an email and no id, Vero will automatically use the email as the id.
timezone integer The timezone of the user as a GMT offset (-7, 10, etc.)
locale string The IETF, ISO 3166-1 formated language last observed when the user was browsing your site.
userAgent string The user agent last observed when the user was browsing your site.

You can add or update any user property you want – properties are completely custom. Here are some examples of common user properties we recommend.

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 user.

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 Conditionally required The unique identifier of the customer.
email Conditionally required The email of the customer.
channels Optional A valid JSON array containing hashes of key/value pairs that represent the user’s device token. Each hash should represent a single device token and include the fields type, address, and platform.
data Optional A valid JSON hash containing key value pairs that represent the custom user properties you want to update.

Note: when using our Javascript library, the data attribute is not used. Key value pairs are passed directly as parameters. Similarly, channels cannot currently be passed in the Javascript library.

Due to the volume of requests, all requests to this endpoint are asynchronously processed. Valid requests will return a status 200 Accepted.

Definition

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

Example request

curl \
  --header "Content-Type: application/json" \
  --request POST \
  --data '{
    "auth_token":"AUTH_TOKEN",
    "id":"1234",
    "email":"test@getvero.com",
    "channels": [{"type": "push", "address": "UNIQUE_DEVICE_TOKEN", "platform": "android"}],
    "data": {"first_name": "John", "last_name": "Doe"}
  }' \
  https://api.getvero.com/api/v2/users/track

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, merging two sets of user data into one. This is an advanced method and may have unintended consequences. Please get in touch if you have questions regarding its usage.

Due to the volume of requests, all requests to this endpoint are asynchronously processed. Valid requests will return a status 200 Accepted.

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 globally unsubscribes a user.

Parameters  
id Required The unique identifier of the user.

Due to the volume of requests, all requests to this endpoint are asynchronously processed. Valid requests will return a status 200 Accepted.

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 globally resubscribe a user.

Parameters  
id Required The unique identifier of the user.

Due to the volume of requests, all requests to this endpoint are asynchronously processed. Valid requests will return a status 200 Accepted.

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 user.

Parameters  
id Required The unique identifier of the user.

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

Due to the volume of requests, all requests to this endpoint are asynchronously processed. Valid requests will return a status 200 Accepted.

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  
name String The name of the tag.

Add

This endpoint adds tags to a user’s profile.

Parameters  
id Required The unique identifier of the user.
add Required An array of tags to add.

Due to the volume of requests, all requests to this endpoint are asynchronously processed. Valid requests will return a status 200 Accepted.

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 tags from a user’s profile.

Parameters  
id Required The unique identifier of the user.
tag Required An array of tags to remove.

Due to the volume of requests, all requests to this endpoint are asynchronously processed. Valid requests will return a status 200 Accepted.

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 users take.

The event object

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

Note: capitalized and lowercase letters and spaces and underscores will be treated the same by Vero's API. For example, 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 user. If the user 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 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 the 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.

Deduplication. We will automatically deduplicate events that are sent to our API with the same event_name, the same properties and that are tracked against the same user `id` within a three minute window. This is designed to solve issues related to Javascript event handling and retries.
You can force Vero to ignore deduplication and track every event by including a property within data with a unique timestamp. This will ensure the event is not seen by the Vero system as a duplicate due to the unique data.

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

When using the Javascript library you do not need to pass an identity hash. Instead you must make a call to the user/identify API method first. A cookie is then stored and used to track future events.

Due to the volume of requests, all requests to this endpoint are asynchronously processed. Valid requests will return a status 200 Accepted.

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')
);