Suggest Edits

Authentication

 

Zaius provides two forms of authentication: Public and Private.

Keys are scoped at the account level

If you have multiple accounts within Zaius, the data within one account is not accessible to the others, you must utilize the appropriate API key.

Public API Keys (sometimes referred to as a Tracker ID) are used for most API calls that send data to Zaius and for a limited number of API calls that request data from Zaius and may be exposed publicly on the Internet.

Private API Keys can be used for querying data from Zaius for backend services and integrations.

Revoking Private API Keys

When you revoke a private API key, your existing key is available for 12 hours as a grace period to ease any transitions.

To view your API Keys, go to Account Settings -> APIs. The screen displays a table of all available APIs:

API Name

The name of the API

Usage Plan

The usage plan for the API will be Default, No Access or the name of a Custom Plan / Package that your company has access to.

Limits

The limits placed upon the API including rate limits and quotas (if applicable)

Public API Key and Tracker ID are synonymous within Zaius

Key Type
Description
Usage

Public / Tracker ID

Used for uploading data into Zaius (or in cases when getting data has limitations) or getting data with limitations (e.g. Lists)

Client-Side, Exposed Publicly

Private

Used for APIs that have access to PII or privileged information and/or actions

Server-Side, Not Exposed Publicly

 
Suggest Edits

Rate Limits

 

The rate limits below are the "Default" provided to most customers. You can check the specific rate limits for your account(s) by going to Account Settings -> APIs at any time.

API
Limitations

Profiles

10 requests / second

Events

No Limits

Objects

No Limits

Lists

No Limits

Compliance

1 request / second

 
Suggest Edits

Schema Basics

 

Object & Fields Overview

Before sending data into Zaius, spend a few minutes reviewing our Objects overview.

Schema

At the core of Zaius are events. Events are the actions that your customers perform, and reference customers, products and orders.

As an example, an order event generates an order summary in the Orders table and an event for each line item in the order which then references the products table. Every event you send to Zaius also references the customers table so we are always aware of the user performing the action.

 
Suggest Edits

Requirements

 

iOS

  • App has a minimum deployment target of iOS 8.0 or later or tvOS 9.0 or later
  • Base SDK is iOS 10.3 or later or tvOS 10.2 or later

Android

  • App runs on Android 4.1 (Jelly Bean, API level 16) and up
 
Suggest Edits

Validate & Troubleshoot

 

Once events are being sent to Zaius APIs, you can confirm Zaius is receiving your data and see that data as it streams into Zaius in realtime. This is done via the Event Inspector, which can be accessed by selecting Event Inspector from the Administration option in the menu.

Once you click Start Inspector your API calls will get recorded and be made visible in the UI by clicking "Refresh":

JSON formatted events such as the following will appear:

{"customer_id":"12345","event_type":"shop","tracker_id":"yfwfhfhewufkj", "ts":1452177429,"ip":"127.0.0.1","ua":"Mozilla/5.0 (Windows NT 5.1) AppleWebKit/536.11 (KHTML, like Gecko) Chrome/20.0.1132.57 Safari/536.11"}

Example Usage - Web Troubleshooting

  1. Go to Account Settings -> Event Inspector
  1. Visit the website you wish to troubleshoot (i.e. go to your-company.com in Chrome)

  2. Let's find your cookie ID! Right click anywhere on the site and select Inspect. This will open up the Chrome developer tools panel.

  1. Click the Console tab, and next to the blue arrow in the white space type: zaius.VUID and hit the enter key on your keyboard

  2. This is your personal cookie ID (Zaius names our cookie vuid); copy the vuid to your clipboard.

  1. Back in Zaius go to Event Inspector and click Refresh to get the latest updates. Search for your VUID by using the shortcut CTRL/CMD+F and pasting in the value above.
  1. Click the event that relates to your vuid to identify what data has been sent to Zaius
 

To utilize the Zaius API include your API Key in the x-api-key request header.

All requests will return a z-request-id header to provide end to end traceability.

Make your first API call:

curl --request GET --url https://api.zaius.com/v3/lists \
     --header "x-api-key: YOUR-KEY-HERE"
 

Get Web SDK Snippet

Visit Account Settings -> Integrations and view the Javascript SDK section.

The Zaius Web SDK snippet already includes your Public API Key / Tracker ID.

Place Snippet on Site

If you do not have a tag management system in place, we recommend to place the tag before the closing </head> element of your site.

The Web SDK requires you to initialize on every page you would like to track events and customer information.

 
Suggest Edits

Advanced Web Push

 

If you want to create your own web push subscribe experience, Zaius supports custom initialization options.

This Guide is for Advanced Use Cases

Most use cases will be satisfied by our default Web integration setup. Go to Account Settings -> Integrations -> Web Push to configure Web Push in the UI and deploy anywhere you've integrated Zaius.

Display Subscription Modal on Specific Page

Configure web push integration to NOT automatically initialize web push (page 5 of wizard). Integration of web push will not be marked as "live" but should be configured.

In JavaScript on your website, AFTER Zaius is initialized, perform any JS logic and call this when you are ready to show the subscription UI:

zaius.dispatch('webPush', 'initialize', {websiteID: '<ZAIUS_WEBSITE_ID>'})

ZAIUS_WEBSITE_ID

This is the name given in the web push subscribe setup, NOT your tracker_id.

Custom Initialization

Integration of web push list will not be marked as "live" but should be configured.

Configure web push integration to NOT automatically initialize web push

Go to page 5 of Web Push wizard within Zaius: Account Settings -> Integrations -> Web Push

In JavaScript on website, AFTER Zaius is initialized, perform any JS logic and call this when you are ready to show the subscription UI:

zaius.dispatch('webPush', 'initialize', 
               {websiteID: '<ZAIUS_WEBSITE_ID>', 
                subscribeUI: {enabled: false}}
              );

//Then, check the subscription status before showing your subscription UI:
zaius.dispatch('webPush', 'subscriptionStatus', function(status, token) {
  if (status !== 'subscribed' && status !== 'denied') {
    // show subscribe UI
  }
});

//Finally, when you want the browser to ask the user to allow push notifications call:
zaius.dispatch('webPush', 'askToSubscribe');
 
Suggest Edits

Add Mobile Apps

 

Visit Account Settings -> Apps & Data -> Mobile Apps and create a mobile app that you will refer to in your integration and when sending campaigns. Each app needs a name and identifier--for example: To-Do List

Apps are cross platform, meaning if you have an app that is available on both iOS and Android you should create a single app to represent them within Zaius.

Once you've created the app you need to upload the appropriate certificate and/or API keys so that we may send to your users.

Visit the iOS and Android sections to read more.

 

Create a mobile app in Zaius first!

Before starting ensure you've created the mobile app within Zaius.

 
Suggest Edits

Auto Integration

 

Install CocoaPods

If you don't already have CocoaPods installed you can do so by running the following command in your terminal:

gem install cocoapods

Create Project Podfile

If you don't already have a Podfile associate with your project, create one. To do this execute the following in the top level of your project’s directory:

pod init

This will result in a Podfile being added to the top level of your project’s directory.

Modify the Podfile

The newly created Podfile will be pre-populated with content.

  1. Start by making sure that at the top of your file you have the line platform :ios, '9.0'.
  2. Next, add the line use_frameworks! which will instruct CocoaPods to use the Zaius dynamic framework.
  3. Finally, you'll notice that the Podfile contains an entry for each target of your project. Add the line pod 'Zaius' which will indicate to CocoaPods that the target is dependent on the ZaiusSDK and will install it into that target.

Install Zaius CocoaPod

pod install

Once this command completes execution a new Xcode project workspace will be created (YOUR-PROJECT-NAME.xcworkspace).

You should now open the project workspace instead of the project file (YOUR-PROJECT-NAME.xcodeproj)

Then you may simply import the SDK into your AppDelegate like so:

#import <ZaiusSDK_iOS/ZaiusSDK_iOS.h> //iOS

#import <ZaiusSDK_tvOS/ZaiusSDK_tvOS.h> //tvOS
import ZaiusSDK_iOS //iOS

import ZaiusSDK_tvOS //tvOS

Initialize the SDK

Add this code into your application:didFinishLaunchingWithOptions: call within your AppDelegate:

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  
    [Zaius autoIntegrate:^(ZaiusBuilder *_Nonnull builder) {

      builder.trackerId = @"ZAIUS_TRACKER_ID";
      builder.appId = @"APP_ID";
      builder.launchOptions = launchOptions;
      builder.collectTokenWhenAnonymous = YES;

    }];
  
  // Initialize your application

}
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
	
  Zaius.autoIntegrate() { (builder) in
  	builder.trackerId = "ZAIUS_TRACKER_ID"
    builder.appId = "APP_ID"
    builder.launchOptions = launchOptions
    builder.collectTokenWhenAnonymous = true
    }
  
	// Initialize your application
}

Additional options include:

builder.sandbox // if this app is setup as a Sandbox app within Zaius
builder.collectTokenWhenAnonymous // collect push tokens when customer ID is not set (not recommended to disable)
builder.enablePushNotification // request push permissions on app initialization

Ensure you are setting an accurate `sandbox` property

An incorrect sandbox setting may result in an certificate mismatch (e.g. sending with a sandbox certificate to an app in "production" mode). Ensure this is set to false / NO before releasing to production.

Notification Types

The ZaiusSDK registers for all notification types UIUserNotificationTypeAlert | UIUserNotificationTypeBadge | UIUserNotificationTypeSound by default

If you would like to delay prompting the user to accept push notifications, set the builder property as follows:

builder.enablePushNotification = NO
builder.enablePushNotification = false

When you are ready to prompt the user for push permissions call the following:

[Zaius enablePushNotifications:YES]

If you are transitioning from another push provider, users will not be prompted for push permissions again

 
Suggest Edits

Manual Integration

Integrate without CocoaPods or autoIntegrate

 

A manual integration is not recommended, use the automatic integration unless absolutely necessary

Download and Extract

Extract the Zaius SDK and add the desired framework to your Xcode project:

  • ZaiusSDK_iOS.framework for iOS
  • ZaiusSDK_tvOS.framework for tvOS

In your Target's Build Phases, add the framework file you added to your project to the list of Embedded Frameworks

Bridging Header

If integrating the Zaius iOS SDK into a Swift project (when doing a manual integration), you will need to add a Bridging Header. This can be accomplished in two ways:

A. The easiest way is to add a temporary Objective-C file to your Swift project and Xcode will create the Bridging Header for you. You may now delete that temporary Objective-C file.

B. Create a file called `<ProductName>-Bridging-Header.h`. If your ProductName is Example, then your Bridging Header would be named `Example-Bridging-Header.h`. Once you create this file, go into your target's Build Settings and search for `Objective-C Bridging Header`. Set this value to the path of your header, which in our case would be `Example/Example-Bridging-Header.h` since our header lives within our project's Example folder.

Lastly, open your newly created Bridging Header and enter the following code:

//
//  Use this file to import your target's public headers that you would like to expose to Swift.
//

#import <ZaiusSDK_iOS/ZaiusSDK_iOS.h>

// Or for tvOS

#import <ZaiusSDK_tvOS/ZaiusSDK_tvOS.h>

Initialize

If you do not wish to use auto integration, you can manually integrate the Zaius SDK instead. First, you should initialize the Zaius SDK using start rather than autoIntegrate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  
  [Zaius start:^(ZaiusBuilder *_Nonnull builder) {
 		builder.trackerId = @"ZAIUS_TRACKER_ID";
    builder.appId = @"APP_ID";
    builder.launchOptions = launchOptions;
    builder.collectTokenWhenAnonymous = YES;
 	}];

  // Initialize your application
}
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
	
  Zaius.start() { (builder) in
  	builder.trackerId = "ZAIUS_TRACKER_ID"
    builder.appId = "APP_ID"
    builder.launchOptions = launchOptions
    builder.collectTokenWhenAnonymous = true
  }
  
	// Initialize your application
}

View the auto integration docs for all the builder variables that are available

To properly handle application lifestyle changes in the non-builder integration of the Zaius SDK requires that [Zaius suspend] be called when the application will resign active and will be terminating. Please add the following into your AppDelegate.

- (void)applicationWillResignActive:(UIApplication *)application {
	[Zaius suspend];
}

- (void)applicationWillTerminate:(UIApplication *)application {
  [Zaius suspend];
}
func applicationWillResignActive(_ application: UIApplication) {
	Zaius.suspend()
}

func applicationWillTerminate(_ application: UIApplication) {
	Zaius.suspend()
}

Additionally, you need to forward notifications to the ZaiusSDK. The SDK requires the following calls to be configured in order to setup push notifications and track open events. Again in your AppDelegate, ensure these calls are included:

- (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
	[Zaius didRegisterForRemoveNotificationsWithDeviceToken:deviceToken];
}

- (void)application:(UIApplication *)application didFailToRegisterForRemoteNotificationsWithError:(NSError *)error {
  [Zaius didFailToRegisterForRemoteNotificationsWithError:error];
}

// If your application receives background push notifications use this implementation:
- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler {
    [Zaius didReceiveRemoteNotification:userInfo];

    // EXAMPLE: if we are transitioning to foreground
    if ([UIApplication sharedApplication].applicationState == UIApplicationStateInactive) {
        // perform any required processing of the notification by your application
    }
    
    // Zaius SDK does not call the completion handler for you
    completionHandler(UIBackgroundFetchResultNoData);
}

// WARNING: This method has been deprecated in iOS 10. If targeting iOS 10 or above, use application:didReveiceRemoteNotification:fetchCompletionHandler instead.
// If your application does NOT receive background push notifications use this implementation:
- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo {
    [Zaius didReceiveRemoteNotification:userInfo];

    // EXAMPLE: if we are transitioning to foreground
    if ([UIApplication sharedApplication].applicationState == UIApplicationStateInactive) {
        // perform any required processing of the notification by your application
    }
}
func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data){
	Zaius.didRegisterForRemoteNotifications(withDeviceToken: deviceToken)
}

func application(_ application: UIApplication, didFailToRegisterForRemoteNotificationsWithError error: Error) {
	Zaius.didFailToRegisterForRemoteNotificationsWithError(error)
}

// If your application receives background push notifications use this implementation:
func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable : Any], fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
	Zaius.didReceiveRemoteNotification(userInfo)

	// EXAMPLE: if we are transitioning to foreground
	if application.applicationState == .inactive {
		// perform any required processing of the notification by your application
	}

	// Zaius SDK does not call the completion handler for you
	completionHandler(.noData)
}

// WARNING: This method has been deprecated in iOS 10. If targeting iOS 10 or above, use application:didReveiceRemoteNotification:fetchCompletionHandler instead.
// If your application does NOT receive background push notifications use this implementation:
func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable : Any]) {
    Zaius.didReceiveRemoteNotification(userInfo)

    // EXAMPLE: if we are transitioning to foreground
    if application.applicationState == .inactive {
		    // perform any required processing of the notification by your application
    }
}
 
 

The Zaius Android SDK collects and associates push tokens with customers and tracks app opens corresponding to push interactions by sending the necessary events through the Zaius API from your app.

Update build.gradle

repositories {
  maven {
    url  "http://maven.zaius.com"
  }
}

dependencies {
  ...
  compile 'com.zaius:androidsdk:<version>' // Add the Zaius SDK as a dependency
  compile 'com.google.firebase:firebase-messaging:<version>' // Only required if you want to use mobile push messaging
}

Initialize

Call Zaius.start from your Application implementation’s onCreate method:

public void onCreate() {
  
  String trackerId = "abc123"; // your Zaius tracker ID  
  boolean managePushTokens = true; // send push tokens to Zaius
  boolean collectTokensWhenAnonymous = true; // collect push tokens without customer ID set
  int flushIntervalSeconds = 60; // how frequently (in seconds) to send events to Zaius
  boolean enableLogging = false; // enable SDK logs for troubleshooting
	
  zaiusConfig = new Zaius.config(managePushTokens, collectTokensWhenAnonymous, flushIntervalSeconds)
    
  Zaius.start(this, trackerId, zaiusConfig);
  
}

Setup Push

Pass along the data in the RemoteMessage available in FirebaseMessagingService.onMessageReceived as extras in the Intent corresponding to push opens:

@Override
public void onMessageReceived(RemoteMessage remoteMessage) {
    sendNotification(remoteMessageToBundle(remoteMessage));
}

/**
 * Convert an FCM RemoteMessage into a Bundle
 *
 * @param remoteMessage message containing data to be translated
 * @return a Bundle containing Strings for each key in the data of the RemoteMessage
 */
private Bundle remoteMessageToBundle(RemoteMessage remoteMessage) {
    Bundle bundle = new Bundle();
    Map<String, String> data = remoteMessage.getData();
    for (String key : data.keySet()) {
        bundle.putString(key, data.get(key));
    }
    return bundle;
}

/**
 * Create and show a simple notification containing the received push data.
 *
 * @param data a Bundle of push data
 */
private void sendNotification(Bundle data) {
    Intent intent = new Intent(this, MyActivity.class); // Open this activity when the notification is clicked
    intent.putExtras(data); // Put the bundle of data from the message in here
    PendingIntent pendingIntent = PendingIntent.getActivity(this, MY_REQUEST_CODE, intent, PendingIntent.FLAG_ONE_SHOT);
    // ... etc, rest of notification code ...
}

Zaius.pushOpened is required to track push opens

Zaius.pushOpened accepts either a Firebase RemoteMessage or an Android Bundle corresponding to the notification so that metadata associated with the push can be linked to the open event for analytics and reporting in Zaius (e.g. the Zaius campaign that sent the notification)

Pass along the Bundle to Zaius.pushOpened in the YourActivity.onCreate method

Register for Registration Callbacks

Optional Step

The Zaius Mobile SDK for Android supports event callbacks. Push token registration is supported for clients who want to be notified of push token registration events.

Implement a class extending ZaiusReceiver:

public class MyReceiver extends ZaiusReceiver {
  @Override
  public void onTokenRegistration(Context context, String token) {
    // Do something with the token (e.g. fire an event)
  }
}

Reference the receiver inside the application element of your AndroidManifest.xml:

<receiver android:name=".MyReceiver" exported="false">
  <intent-filter>
    <action android:name="com.zaius.androidsdk.TOKEN_REGISTRATION_ACTION" />
  </intent-filter>
</receiver>
 
Suggest Edits

CSV Uploads

 

Zaius supports bulk data imports via CSV files. This functionality is commonly utilized for historical data imports.

Columns

The input file consists of a header line identifying all of the fields to be found within the file. These field names must match the expected field names exactly. To view available fields, go to Account Settings -> Objects & Fields.

To upload a CSV navigate to Upload CSV (Cog => Data Management => Integrations).

File Naming

We recommend using a unique name for every file you upload to Zaius. Each file has a prefix which identifies the type of data and must end with .csv or .csv.gz

File Name

File contain products must be prefixed with zaius_products, files containing customers must be prefixed with zaius_customers and files containing orders must be prefixed with zaius_orders; e.g.

  • zaius_products-2016-01-01.csv
  • zaius_customers-2016-02-03.csv
  • zaius_orders-2016-03-04.csv

File Format

For customers and products, the remainder of the file consists of one line per input record. Orders can contain multiple items, and are documented in a bit more detail below on this page. In all cases, these records have the following limitations:

  • Values must be UTF-8 encoded
  • Values must be comma delimited
  • Records must end with a newline (\n)
  • Any value may be optionally quoted via double quote (") characters
  • Any field containing a double quote must be quoted. The escape character for an embedded quote is a second quote character. (For example: "Customers think this product is ""Amazing!""")
  • Each record must contain exactly the same number of fields as the header does
  • No carriage return (\r) or newline (\n) may exist within a record.

Fields and Data Types

Go to Account Settings -> Objects & Fields to view available fields.

All data types allow for null values represented by an empty field.

  • string: Strings may contain any printable UTF-8 character, including space. Strings are limited to 1024 characters unless otherwise specified.
  • number: A number represented in standard decimal format (Example: 0, 3.14159, -2.3, -0.112)
  • boolean: Boolean values must be one of 0, 1, true or false. (0 and false represent false values. 1 and true represent true values)
  • timestamp: Timestamps must be formatted as ISO 8601 format or unix epoch (seconds since January 1, 1970). Examples: 1435708800, 2015-07-01T00:00:00-00:00, 2015-07-01T12:30:00-07:00. Note: If time and time zone are not provided the time is assumed be 12am UTC.
  • email: Email is validated against a regex of: /.+@.+\..+/

Orders

A single order can contain multiple items. Each row of the CSV contains the following fields which correspond to an order:

  • customer_id
  • action ("purchase" and "return" are acceptable values here)
  • order_id
  • total
  • discount
  • subtotal
  • tax
  • shipping
  • coupon_code
  • first_name
  • last_name
  • bill_address
  • ship_address
  • ts (timestamp in epoch time or ISO-8601 format)

Bolded fields are required.

Each row of the CSV also contains the following fields which correspond to an item within an order:

  • item_product_id
  • item_sku
  • item_price
  • item_quantity
  • item_discount
  • item_subtotal

Within the file, all items of an order must be on consecutive lines, and values of order-level fields must match - that is, the order-level information is repeated on every line which corresponds to that order. Zaius will also ingest any order file which contains order information on the first row of that order, and contains only order item values on subsequent rows (those rows will contain empty strings for each order field value). New order event delineation is determined when the value for any one of the order_id, action, or ts fields changes. The examples below shows an order in each format.

For each order represented in the file, the order's subtotal field will be calculated using the sum of the individual order item's subtotal values. To avoid this behavior simply specify the order's subtotal on the first line of the CSV that represents the order.

For order-lever or event-level fields, custom field values must contain the same value that was specified in the first line of the order sequence. If it is determined that the value differs between rows, that specific order will not be loaded. To avoid potential ambiguity in cases where you have defined a custom field with the same name on orders and items, but you only want the value to be applied in your CSV to one of these, simply supply an 'order' or 'item' prefix to the column header and that value will only be set on either the order or item.

Custom Fields on Orders

When creating custom fields for orders, any custom field created on the orders object will be share among all items in that order. Use this for values such as shipping mechanism or retail employee who handled the order.

Any custom field which is per item (such as color or style) should be created as part of the events object in Zaius. The name for this field will them be prefixed with item_ in the CSV file. In the example below, a text field named "style" would be created on events to allow style information to be ingested.

Example Files

customer_id,action,order_id,total,discount,subtotal,tax,shipping,coupon_code,item_product_id,item_sku,item_price,item_quantity,item_discount,item_subtotal,ts,item_style
1,"purchase",15,13.75,5,13.50,1.35,19,"ZAIUS 20% OFF","ZAIUS T-Shirt","Z-1453",13.75,1,5,12.50,1508773855,"red logo"
1,"purchase",15,13.75,5,13.50,1.35,19,"ZAIUS 20% OFF","ZAIUS Baseball Cap","Z-1353",6.75,1,95,0.25,1508773855,"size 8"
2,"purchase",16,13.75,5,13.50,1.35,19,"ZAIUS 20% OFF","ZAIUS T-Shirt","Z-1453",13.75,1,5,12.50,1508773855,"Zira face"
,,,,,,,,,"ZAIUS Baseball Cap","Z-1353",6.75,1,95,0.25
1,"refund",2,-10.00,0.00,-10.00,0.00,1.00,"coupon",123,"Z-1345",18.00,1,0.00,-10.00,1508773855,"size 7 5/8"
customer_id,first_name,last_name,email,phone
zaius-342,Johnny,Zaius,"johnny.zaius@zaius.com","617-545-5001"
product_id,category,name,brand
A13847388,"Apparel > T-Shirts","ZAIUS T-shirt (Medium Mens)",ZAIUS
type,action,hostname,page,customer_id,ts,product_id
product,add_to_cart,zaius.com,/pricing,z0002,1454033935,zp_00143
pageview,,zaius.com,/thank-you,z0002,1454034013,

Error Handling

Each field in a bulk files is validated against it's data type and may include additional validation. Any record that contains an invalid field will be ignored. If more than 1% of the data is invalid, the entire file will be rejected. The Activity Log will show the status of the uploads, any errors generated, and a success entry if the data is loaded successfully.

Amazon S3 Upload

See Amazon S3

 
Suggest Edits

Amazon S3

 

Load files can be uploaded to Zaius via an Amazon S3 bucket. Contact Zaius for credentials. Zaius will provide a document with the following information:

Customer Tracker ID is: 
-----------------------
<your tracker ID>

Two buckets were Created for <customer name>
-------------------------------------------
s3://zaius-incoming/<your tracker ID>/
s3://zaius-incoming-temp/<your tracker ID>/

The Customer access keys are as follows:
-------------------------------------------
AWS_ACCESS_KEY_ID=<Your AWS ACCESS_KEY ID> 
AWS_SECRET_ACCESS_KEY=<Your AWS_SECRET_ACCESS_KEY>

Given these credentials, you'll be able to access two buckets in S3:

s3://zaius-incoming/<your tracker ID>/
s3://zaius-incoming-temp/<your tracker ID>/

The zaius-incoming bucket is for data that will be automatically ingested by Zaius. See here for CSV requirements, or here for JSON. The zaius-incoming-temp bucket serves as a scratch space for ad hoc purposes like sharing data with Zaius Customer Success.

There are various tools at your disposal to upload data to your S3 buckets. If you prefer a command line interface, install the AWS CLI tools and then refer to the S3 command line reference . For example, in order to upload a local products CSV file named zaius_products.csv to your S3 bucket that is used for automated ingest, you would run:

aws s3 cp zaius_customers.csv s3://zaius-incoming/<your tracker ID>/ --sse 

You can also sync a complete directory of files by running:

aws s3 sync /tmp/yourlocaldir/ s3://zaius-incoming-temp/<your tracker ID>/ --sse 

You can then check the Activity Log in Zaius in order to monitor ingest status.

Graphical Interface

If you prefer a graphical interface, Cyberduck is a free tool that you can use to browse S3 buckets. In order to use Cyberduck, first download the client here. Once installed, launch Cyberduck and click Open Connection:

In the top dropdown, select S3 (Amazon Simple Storage Service). Enter the AWS Access Key ID that Zaius provided in the Username field, and enter the AWS Secret Access Key in the Password field and connect to "zaius-incoming.s3.amazonaws.com".

Click Go and then Go to folder in the menu.

Finally, enter zaius-incoming/<your tracker ID> if uploading data for automated ingest, or zaius-incoming-temp/<your tracker ID> if uploaded to your scratch space.

Click Connect. At this point you can drag and drop files directly into the Cyberduck explorer in order to upload to S3.

If you wish to turn on server side encryption for your data, click "Cyberduck", then "preferences" in the top menu. Select "S3" and set Encryption to "AES256", as shown below:

 

Zaius accepts raw JSON data as input. A file containing one or more JSON objects may be ingested to ZAIUS by way of an upload to a specific Amazon S3 bucket. Please contact technical support to
get credentials to access the bucket.

This JSON matches the format of customer, event and product API defined in the HTTP API documentation. The input file name must match the type of data being ingested:

  • Customer data files must end with "customers.zaius"
  • Products data files must end with "products.zaius"
  • Event data files, including orders, must end with "events.zaius"
  • Orders data files, including orders, must end with "orders.zaius"

JSON Examples

For example, the following file (named mystore.customers.zaius) would produce three customers:

{"type":"customer","data":{"customer_id":"1","email":"floyd@zaius.com","first_name":"Floyd","last_name":"Dogg"}}
{"type":"customer","data":{"customer_id":"2","email":"johnny@zaius.co","first_name":"Johnny","last_name":"Zaius"}}
{"type":"customer","data":{"customer_id":"3","email":"jdoe@zaius.com","first_name":"John","last_name":"Doe"}}

The following file (named mystore.products.zaius) would produce two products:

{"type":"product","data":{"product_id":"1","sku":"1234","name":"Planet of the Apes","category":"Books"}}
{"type":"product","data":{"product_id":"2","sku":"4321","name":"Escape from Planet of the Apes","category":"Movies"}}

The following file, named mystore.orders.zaius, would produce one order:

{"type":"order","data":{"ts":1460392935,"ip":"192.168.1.1","email":"floyd@zaius.com","action":"purchase","ua":"Firefox","order":{"order_id":"1009","items":[{"product_id":"765","sku":"zm64","quantity":"1","subtotal":"59.95"}],"subtotal":6.99,"tax":0.0,"shipping":25.75,"discount":0.0,"total":32.74,"email":"floyd@zaius.com","first_name":"Floyd","last_name":"Dogg","phone":"16175455001"}}}
 
Suggest Edits

Custom Integration Guide

 

Javascript Snippet/Integration

The first step in order for you to start getting data into the Zaius platform is to implement our Javascript snippet on your site or set up the integration with Shopify or Magento. If you are not integrating with Magento or Shopify, you should place your Javascript snippet on the header of every page on your site. You can find the snippet in your account by going to Settings (cogwheel) > Data Mangement > Integrations > Javascript Tag.

To make sure you implemented properly, you can check your Event Inspector to see if pageview data is coming through.

Data Overview

Data in Zaius falls into one of four categories (unless you have custom dimensions):

Data Type
Description

Customer

All fields that describe a customer and their attributes.

Product

Every item in your product catalogue should be expressed as a product entity in Zaius.

Orders

Order data tracks purchases in Zaius. Each order has a unique ID but can be updated over time if, for example, there is a return for a specific Order.

Events

Events are the core of Zaius. Events represent the touch points a customer has with your brand.

These data categories work together to enable you to utilize all of the features in Zaius.

Customer Data

If you are not sure what Customer data includes, please reference the customer entities document here.

For Historical information, we want to make sure we upload a file of all emails and metadata you have associated with them. Typically when first integrating with Zaius, we want to include those who have subscribed, unsubscribed, and any other email status a user may have. Providing other information outlined in the customer entities document is very helpful but the most important is a user's email. Zaius has a number of native fields which are listed on the customer entities document. You may come across fields in your data that are not reserved by Zaius and you will want to create custom fields.

Here is an example CSV file of what the formatting needs to be in order to upload the data into Zaius. For custom fields, make sure to use the Tag Name (example_field) and not the Display Name (Example Field).

Your CSV file name should begin with 'zaius_customers'.

To capture ongoing customer data, you will want to track when a user subscribes on a form, orders, logs in, registers for an account, etc. Essentially we recommend tracking any form where a user can identify themselves on the website (places where a user would type in their email). When we see an email/customer id field that is not already in our database, we will add a new customer record. If we see that user already, we will update the fields that you pass us and associate any events ongoing with that user.

zaius.entity("customer",
            {email: "johnny.zaius@zaius.com",
             first_name: "Johnny",
             last_name: "Zaius",
             phone: "617-545-5001"}
);
//Requires Initialization First!
<script type="text/javascript">
  zaius.event("account",
    {
      action: "checkout_form",
      email:"bob@gmail.com",
      first_name: "Bob",
      last_name: "example",
      // Add any other fields to collect. Please refer to our reserved fields in the Entities document if you are unsure of what we will accept. Refer to custom fields below if we do not.
    }
  );
</script>
POST /v2/entities
Host: api.zaius.com
Content-Type: application/json
Zaius-Tracker-Id: <YOUR TRACKER ID>

{"type": "customer",
"data": {"email": "johnny.zaius@zaius.com",
         "first_name": "Johnny",
         "last_name": "Zaius"}
}
curl -H 'Content-Type: application/json' -H 'Zaius-Tracker-Id: <YOUR TRACKER ID>' -d '{"type": "customer",
"data": {"email": "johnny.zaius@zaius.com",
         "first_name": "Johnny",
         "last_name": "Zaius"}
}' https://api.zaius.com/v2/entities

Anytime you send Zaius an event, we need an identifier to associate the event with the right customer in the system (or create a new one). Foreign keys that need to be referenced: email, customer_id, etc. You can create your own identifier by simply putting zaiusaliasyour field here. For example, if you wanted to identify by IP address, you can send us zaius_alias_IP and that would stitch users together with the same value for zaius_alias_IP.

Product Data

If you are not sure what Product data includes, please reference the product entities document here.

For custom integrations, the best way to send us your product data is to either to upload daily to an S3 bucket (we would create this for you) or send us the products via our entities endpoint (view the code below as an example).

The product data feed is a static feed that does not contain historical information. For example, if you update an image on a product, we do not then store the old image URL and the new URL.

Your CSV file name should begin with 'zaius_products'.
If using gzip compression, your file must end in .gz: zaius_products_update.csv.gz

POST /v2/entities HTTP/1.1
Host: api.zaius.com
Content-Type: application/json
Zaius-Tracker-Id: <YOUR TRACKER ID>

{
  "type": "product",
	"data": {
  	"product_id": "A13847388",
    "category": "Apparel > T-Shirts",
    "name": "ZAIUS T-shirt (Medium Mens)",
    "brand": "ZAIUS"
  }
<script type="text/javascript">
zaius.entity("product", {
	product_id: "A13847388",
	category: "Apparel > T-Shirts",
	name: "ZAIUS T-shirt (Medium Mens)",
	brand: "ZAIUS"
});
</script>
curl -H 'Content-Type: application/json' -H 'Zaius-Tracker-Id: <YOUR TRACKER ID>' -d '{
"type": "product",
"data": {"product_id": "A13847388",
         "category": "Apparel > T-Shirts",
         "name": "ZAIUS T-shirt (Medium Mens)",
         "brand": "ZAIUS"}
}' https://api.zaius.com/v2/entities

Foreign key that needs to be referenced: product_id

Order Data

If you are not sure what Order data includes, please reference the order entities document here.

For custom integrations, you will want to send us your historical information via CSV. When you send order data, we will automatically create an event for order along with the user you send in the file/event. We also create events called 'Order Line Item Purchase' for every item that is purchased. For example, if 3 items are purchased in a single order, we will have those 3 events created so we are able to associate the correct product data together.

Your CSV file name should begin with 'zaius_orders'.

For ongoing data, we recommend to not send us orders via JavaScript or client-side. There can be issues with JavaScript loading on peoples devices sometimes and users could be using Ad Blockers to block our script from loading. This could result in a data loss of 1-5%. We recommend you send us the data via our HTTP API. You can use this with any webhooks your system has and we can make sure that all orders and revenue are 100% accurate. Since we get this data on the back end, we will want to make sure you track an event for the checkout form. This is so we can identify the user on the client side to associate website data like what actions they did on the site, referral data, etc. and the order data into one profile.

POST /v2/events
Host: api.zaius.com
Content-Type: application/json
Zaius-Tracker-Id: <YOUR TRACKER ID>

{
  "type": "order",
  "data": {
    "action": "purchase",
    "email": "bob@gmail.com",
    "order": {
      "order_id": "OR345",
      "total": 109.65,
      "discount": 5.00,
      "subtotal": 103.00,
      "tax": 5.15,
      "shipping": 6.50,
      "coupon_code": "5OFF",
      "items": [
        {
          "product_id": "2045",
          "price": 19.00,
          "quantity": 5,
          "discount": 0.00,
          "subtotal": 95.00
        },
        {
          "product_id": "2091",
          "price": 10.00,
          "quantity": 1,
          "discount": 2.00,
          "subtotal": 8.00
        }
      ]
    }
  }
}
POST /v2/events
Host: api.zaius.com
Content-Type: application/json
Zaius-Tracker-Id: <YOUR TRACKER ID>

{
  "type": "order",
  "data": {
    "action": "return",
    "email": "bob@gmail.com",
    "order": {
      "order_id": "OR345",
      "total": 10,
      "discount": 5.00,
      "subtotal": 10.00,
      "items": [
        {
          "product_id": "2045",
          "price": 19.00,
          "quantity": 5,
          "discount": 0.00,
          "subtotal": 95.00
        }
      ]
    }
  }
}

For returns and similar events, you can refer here for more detail. You can send us a positive or negative amount because we see that the event is a return, cancel, or refund.

Foreign key that needs to be referenced: order_id

Event Data

There are two parts to an event, an Event Type and an Action. The Event Type is a categorical name associated with the event. An Action is an activity a user did. For example, 'order' and 'product are Event Types 'purchase', 'return', 'add_to_cart', 'detail' would be actions. When you send us the event data you would send these together in an API call. Refer to the JavaScript code examples below for reference.

//Requires Initialization First!
<script type="text/javascript">
  zaius.event("product",
    {
      action: "remove_from_cart",
      product_id: "product-2143",
    }
  );
</script>
//Requires Initialization First!
<script type="text/javascript">
  zaius.event("product",
    {
      action: "add_to_cart",
      product_id: "product-2143",
    }
  );
</script>
//Requires Initialization First!
<script type="text/javascript">
  zaius.event("product",
    {
      action: "detail",
      product_id: "product-2143",
    }
  );
</script>
//Requires Initialization First!
<script type="text/javascript">
  zaius.event("navigation", 
    {
      action: "search",
      search_term:"cameras, vcr",
      category: "electronics > consumer",
    }
  );
</script>
//Requires Initialization First!
<script type="text/javascript">
  zaius.event("account",
    {
      action: "login",
      email:"johnny.zaius@gmail.com",
    }
  );
</script>
//Requires Initialization First!
<script type="text/javascript">
  zaius.event("account",
    {
      action: "log_out",
  	email: "bob@gmail.com"
    }
  );
</script>
//Requires Initialization First!
<script type="text/javascript">
  zaius.event("account",
    {
      action: "register",
      email:"bob@gmail.com",
      // Add any other fields to collect. Please refer to our reserved fields in the Entities document if you are unsure of what we will accept. Refer to custom fields below if we do not.
    }
  );
  zaius.entity("customer",
    {
      email: "bob@gmail.com",
      first_name: "Bob",
      last_name: "example",
    }
  );
</script>
//Requires Initialization First!
<script type="text/javascript">
  zaius.event("account",
    {
      action: "checkout_form",
      email:"bob@gmail.com",
      // Add any other fields to collect. Please refer to our reserved fields in the Entities document if you are unsure of what we will accept. Refer to custom fields below if we do not.
    }
  );
  zaius.entity("customer",
    {
      email: "bob@gmail.com",
      first_name: "Bob",
      last_name: "example",
    }
  );
</script>
//Requires Initialization First!
<script type="text/javascript">
  zaius.event("newsletter",
    {
      action: "subscribe",
      email: "bob@gmail.com",
    }
  );
</script>
//Requires Initialization First!
// This is for if you have a specific list you want to add the user to. If you just have a newsletter subscribe, use 'Newsletter Subscribe'
<script type="text/javascript">
  zaius.subscribe(
     {
      list_id: 'cg_list', 
      email: "bob@gmail.com",
);
</script>

When tracking an event such as Product Add to Cart, you can just pass us the product_id and quantity. You do not need to pass us the price, image, or anything associated with the product as we already have that stored in the product feed and can refer to it in reporting and in your email templates. You would want to pass something like quantity.

When uploading historical events, please refer to the CSV example.

Your CSV file name should begin with 'zaius_events'.

Custom Fields

Custom fields are needed if they are not provided in our reserved list in the entities documents for each dimension. Once you create a custom field, it will only capture the new data that you refer to. For example, if you were trying to send us a custom field for a week, and then created it, we will not have that previous weeks data stored in our database.

When uploading data for custom fields please use the Tag Name. If you are not sure what the tag name is, go to your Settings > Data Management > Data Fields in your Zaius account.

 
 

Zaius provides a number of standard Objects for your use: Events, Customers, Orders, Products & Categories.

Below are a series of tables outlining what fields are available on each of these objects and when to use the Object API to update vs other methods.

Object Name
Available Fields
When to use Object API

Products

Always

Categories

Always

Object Name
Available Fields
When to use Object API

Orders

Use Event API for refunds, returns & cancellations.

Use the Object API in those cases you need to update top-level order information.

Events & Customers are Special Objects

Send event and customer updates via the Event and Profile API & SDK methods

Object Name
Available Fields
When to use Object API

Events

Never; use Event API

Customers

Never; use Profile API

 
Suggest Edits

Create Objects & Fields

 

Custom objects and fields are used to track information relevant to your business beyond the Zaius default schema. Objects and fields must be defined before data is sent to them.

Create Fields before Sending Data!

If you send data via Zaius APIs or SDKs, Zaius will accept data destined for Objects and Fields that are defined and drop all other data.

Create Objects

Custom object creation is currently available to customers in certain packages. Find out more by contacting your Customer Success Manager.

Create Fields via the UI

Users must be assigned a role that has permission to create new fields in the UI (e.g. Developer Role)

To add a new custom field:

  1. Go to Account Settings -> Objects & Fields.

  2. Click the "Create New Custom Field" button.

  3. Define your field.

Container

Select the object (also support custom objects) that will contain the custom field

Display Name

The user-friendly name used throughout Zaius in non-technical contexts

Field Name

The technical / developer-friendly name used in Liquid, CSVs, SDKs & APIs

Type

The data type of the field for Zaius to expect and validate against

Field Data Types
Details

Number

Numbers up to 18 total digits, with a max of 4 digits after the decimal point

String

Strings less than or equal to 1024 characters

Timestamp

Unix timestamp

Boolean

These must be one of 0, 1, false, or true

  1. Save.

Example

Zaius' Customers object provides a number of fields suitable for most businesses. Two customer custom fields that can enable interesting use-cases are birth year and birth month, with these fields you can segment customers based on age and birthday.

We will model birth year and month as numbers. Create new custom fields with the following details:

Container
Display Name
Field Name
Type

Customers

Birth Year

birth_year

Number

Customers

Birth Month

birth_month

Number

These new fields can now be specified on your profile calls like regular fields.

Create Fields & Objects via API

Coming Soon!

 
Suggest Edits

Update Object

 
posthttps://api.zaius.com/v3/objects/object

Path Params

object
string
required

the name of the object to update

 
curl --request POST \
  --url https://api.zaius.com/v3/objects/object
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.zaius.com/v3/objects/object' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.zaius.com/v3/objects/object")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.zaius.com/v3/objects/object");

xhr.send(data);
import requests

url = "https://api.zaius.com/v3/objects/object"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available
 
Suggest Edits

Identity Resolution

 

Zaius utilizes a number of identifiers to resolve users together. Including one or more of these identifiers on an event identifies the user who performed the event and allows Zaius to merge users together when enough information becomes available.

By including as many known identifiers on event updates as possible, you ensure higher quality user resolution over time.

Identifier Types

Identifiers
Profile Field Name
Description

Customer ID

customer_id

A custom identifier utilized by your company across all data sources, only recommended in advanced use cases

Email

email

The email address of the user

VUID

vuid

The cookie / device of the user generated by the Zaius SDKs. Unique per browser or device.

Zaius Alias

zaius_alias_{name}

A custom identifier used for resolving users together (e.g. cart identifiers, hashed credit card, phone number)

Customer ID

Zaius only recommends Customer ID use in cases where Companies have defined identifiers (e.g. a data lake or DMP) outside of Zaius. If you don't use Customer ID, Zaius will resolve users together based on all available information and assign an internal User ID.

Not all identifiers are exposed via customer profiles. Device identifiers such as VUID are not exposed, and alias fields are not exposed by default. If your alias field should be exposed on the profile, create and populate a custom field as per usual - but continue sending the zaius_alias version of that field as well!

Customer Profile

Each of your Customers within Zaius has a set of profile attributes. The available set of default attributes is available at Account Settings -> Objects & Fields. You can also create new fields at this location.

 
 
 
Suggest Edits

Create / Update Profile(s)

 
posthttps://api.zaius.com/v3/profiles

Body Params

attributes
object
attributes.email
string
attributes.gender
string
attributes.name
string
attributes.first_name
string
attributes.last_name
string
attributes.phone
string
attributes.timezone
string

The timezone of the user in the following format: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones

attributes.street1
string
attributes.street2
string
attributes.city
string
attributes.state
string
attributes.zip
string
attributes.country
string

The three letter code of the user's country: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3

attributes.image_url
string

The profile photo of the user as a valid URL

{
    "attributes": { 
        "email":"foo@bar.com", 
        "gender":"M", 
        "first_name": "Foo"
    } 
}

This endpoint supports a maximum of 1000 profiles in each batch call.

[{
    "attributes": { 
        "email":"foo@bar.com", 
        "gender":"M", 
        "first_name": "Foo"
    } 
},
{
    "attributes": { 
        "email":"bar@foo.com", 
        "gender":"F", 
        "first_name": "Bar"
    } 
}]

If you want to set a custom attribute for a customer, ensure you create the field first!

Visit Account Settings -> Objects & Fields and create a new field.

curl --request POST \
  --url https://api.zaius.com/v3/profiles
var request = require("request");

var options = { method: 'POST', url: 'https://api.zaius.com/v3/profiles' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.zaius.com/v3/profiles")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.zaius.com/v3/profiles");

xhr.send(data);
import requests

url = "https://api.zaius.com/v3/profiles"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available
 
Suggest Edits

Get Profile

 
gethttps://api.zaius.com/v3/profiles

Query Params

email
string

The email of the user you want to collect data for

vuid
string

The cookie ID (available on websites with the Web SDK via zaius.VUID) that you want data for

zaius_alias_NAME
string

The custom alias of the user you want data for; replace NAME with the name of the alias

customer_id
string

The customer ID of the user you want data for (customer ID must be set for your users)

 
curl --request GET \
  --url https://api.zaius.com/v3/profiles
var request = require("request");

var options = { method: 'GET', url: 'https://api.zaius.com/v3/profiles' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.zaius.com/v3/profiles")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.zaius.com/v3/profiles");

xhr.send(data);
import requests

url = "https://api.zaius.com/v3/profiles"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
    "attributes": { 
        "email":"foo@bar.com", 
        "gender":"M", 
        "first_name": "Foo"
    } 
}
 

Update Profile

zaius.entity("customer", {
	email: "johnny.zaius@zaius.com",
	first_name: "Johnny",
	last_name: "Zaius",
	phone: "6175455001"
});

Customer ID (Advanced Use Cases)

// Set the customer ID 
zaius.identify(customer_id);

// Remove the customer ID 
zaius.anonymize();
 

Update Customer Profile

We recommend making requests to our Profile API for any profile updates your customers may have on their mobile devices.

Customer ID (Advanced Use Cases)

Improper use of Customer ID can result in corrupt data

Ensure you need to use Customer ID before proceeding. Most clients do not require Customer ID and can rely on Zaius identity resolution.

- (void)customerLoggedIn:(NSString*)customerId {
    // Set the customer ID 
    [Zaius setCustomerId:customerId];
}

- (void)customerLoggedOut {
    // remove the customer ID 
    [Zaius anonymize];
}
func customerLoggedIn(withCustomerId customerId: String) {
	  // Set the customer ID
    Zaius.setCustomerId(customerId)
}

func customerLoggedOut() {
	  // remove the customer ID
    Zaius.anonymize()
}
 
 

Update Customer Profile

We recommend making requests to our Profile API for any profile updates your customers may have on their mobile devices.

Customer ID (Advanced Use Cases)

Improper use of Customer ID can result in corrupt data

Ensure you need to use Customer ID before proceeding. Most clients do not require Customer ID and can rely on Zaius identity resolution.

- (void)customerLoggedIn:(NSString*)customerId {
    // Set the customer ID 
    [Zaius setCustomerId:customerId];
}

- (void)customerLoggedOut {
    // remove the customer ID 
    [Zaius anonymize];
}
func customerLoggedIn(withCustomerId customerId: String) {
	  // Set the customer ID
    Zaius.setCustomerId(customerId)
}

func customerLoggedOut() {
	  // remove the customer ID
    Zaius.anonymize()
}
 
 

Zaius has two types of events: Standard & Custom.

Standard Events are events that have a pre-defined event type/action and expected by Zaius to be accompanied with certain fields.

Custom Events are events that you create the event type/action for and choose what fields to use and/or create.

Events are composed of a Type, Action and additional metadata via object fields.

The Event Type is a categorical name associated with the event. An Action is an activity a user did. For example, 'order' and 'product are Event Types 'purchase', 'return', 'add_to_cart', 'detail' would be actions.

At minimum, events require an event type.

The exact object representation of an Event depends on the SDK / API being used

Examples of Standard Events

type: product 
action: add_to_cart
product_id: abc123
type: pageview
page: /products/shoes/black-shoe-abc123

Examples of Custom Events

type: venue 
action: visited
venue_name: TD Garden
type: support_ticket 
action: created
ticket_id: 789

Visit Objects & Fields to View Available Fields

Go to Account Settings -> Objects & Fields to see the standard fields available for use on events or to create custom fields.

Sending Events Across Platforms

All events are composed of type, action, identifiers and fields. The exact representation of these depends however on the platform you're utilizing:

zaius.event("account", { // the event type
  action: "login", // the event action
  email:"bob@gmail.com", // at least one identifier
  // add any additional fields / identifiers here
});
curl --request POST \
  --url https://api.zaius.com/v3/events \
  --data '{"type": "pageview", "identifiers": {"email": "tm@abc.com"},"data": {"page": "/foo"}}'
// sending custom events with custom fields
let event = ZaiusEvent(eventType: "map", action: "explore")
// page is a field available on any event, buy primarily used for pageviews
event["page"] = "map_explorer"
// where map_region is a custom field you added to events in the Zaius App
event["map_region"] = "North America"
Zaius.event(event)
ZaiusEvent genericEvent = new ZaiusEvent("my_event_type")
  .action("my_action")
  .addField("some_other_key", "some_custom_field_value");
Zaius.sendEvent(genericEvent);
 

Client-Side Orders

We recommend not sending Zaius orders client-side (i.e. via the Web or Mobile SDKs). There can be issues with the Zaius SDK loading on customer devices (due to ad blockers or network connectivity issues). This could result in significant data loss. Instead, send order and revenue modification events server-side via our Event API.

Order Actions

The four order actions with special meaning in Zaius are:

  1. purchase - a customer has made an order purchase.

  2. return - a customer has returned some or all of the items in an order and been refunded.

  3. refund - a customer has been issued a refund for a given order. Semantically, refunds are treated the same as returns in Zaius (e.g., negative impact on revenue). You can use either. Use both if you want to distinguish between inventory being returned to you (a return) and just money being issued to the original purchaser (a refund). If inventory is returned and money is issued back to the purchaser, Zaius recommends using the 'return' order action.

  4. cancel - a customer has canceled their order. The order purchase and cancel events remain in Zaius (e.g., on the customer profile page, and for segmentation), and revenue is negatively impacted, but the order no longer figures in to determining the customer's lifecycle. This is in contrast to returns and refunds, where the order still counts in determining the order count, and thus lifecycle, for a customer.

Note that order returns, refunds, and cancels can be partial. Zaius determines if they are partial by tracking whether the running tally of the order's subtotal field across all events is greater than zero (partial) or not. Zaius allows the subtotal and total fields for an order to go negative (e.g., to support purchase and refund events coming in out of order, or to support cases where the refund amount legitimately exceeds the purchase amount), so be cautious not to issue duplicate refund, return, and cancel events.

Duplicate Handling

An order in Zaius is identified by a unique order_id. Only one purchase event is allowed for a given order_id in Zaius in order to provide safety, e.g., in the case of multiple order events being sent from Javascript in the case of browser refresh. If you need the ability to add items to an order that was already created, you must use a different order_id on the subsequent order purchase events. Zaius will ignore subsequent order purchase events with the same order_id, though it will process updates to fields on the order in this case. For example:

  1. Order purchase with order_id 123 happened yesterday with no ship_address field populated

  2. Order purchase with order_id 123 happens again today, this time with the ship_address field populated

The customer will only have the first order purchase in their event history, but after the second event the order will have the ship_address field populated.

Order cancel, return, and refund events are not subject to the same duplicate prevention logic as purchases because Zaius supports partial actions. For example:

  1. Order purchase with order_id 123 happened two days ago with three items and a subtotal of $100.

  2. Order return with order_id 123 and subtotal $20 happened yesterday because the customer returned one of the items.

  3. Order return with order_id 123 and subtotal $30 happens today because the customer returned another item in the order.

Zaius supports this flow of order activity, and tracks revenue accordingly. In this case, after the two return events, the order contributes $50 to revenue.

Order Updates

As mentioned in the previous section, an order can be updated via return, refund, or cancel events. The total and subtotal fields will be maintained as a running tally, where for these actions the subtotal and total associated with the events will be coerced negative. The rest of the fields (ship_address, bill_address, coupon_code) are updated to be the value provided in the final event that included the field. Additionally, Zaius supports updating order attributes at any time, not just when order events are fired. For example, if a customer has an order purchase event yesterday, and today you want to add an order level coupon_code to the order, you can do so by issuing an entities request. See the order entities documentation for details and examples.

 
 

You don't need to include all product metadata on each event. As long as you upload your products into the Zaius Product object, you can simply refer to products by ID in the product_id field.

Product Feed Updates

Setup regular product feed updates via CSV by reviewing our Amazon S3 guide.

 
 
 
Suggest Edits

Upload Event

 

Read the Event Overview first

Check out our quick overview of Events here.

Below is an example of an event sent in via the Web SDK:

zaius.event("account", { // the event type
  action: "login", // the event action
  email:"bob@gmail.com", // at least one identifier
  // add any additional fields / identifiers here
});

All events are composed of a combination of event type, event action, and fields.

 
Suggest Edits

Add to Cart

 
<script type="text/javascript">
  zaius.event("product", {
    action: "add_to_cart",
    product_id: "product-2143",
  });
</script>
 
Suggest Edits

Remove from Cart

 
<script type="text/javascript">
  zaius.event("product", {
    action: "remove_from_cart",
    product_id: "product-2143",
  });
</script>
 
Suggest Edits

Product Detail View

 
<script type="text/javascript">
  zaius.event("product", {
		action: "detail",
		product_id: "product-2143",
	});
</script>
 
Suggest Edits

Product Listing

 
<script type="text/javascript">
  zaius.event("product", {
		action: "listing",
		product_id: "product-2143",
	});
</script>
 
Suggest Edits

Page View

 
zaius.event("pageview", {
  email:"bob@acme.com", // at least one identifier
  page:"/products/shoes/", // the page the customer visited
});
 
 
 
Suggest Edits

Upload Event(s)

 
posthttps://api.zaius.com/v3/events

Body Params

type
string
required

state the type of event

action
string

state the action of the event

identifiers
object
required

identify the customer that this event belongs to

identifiers.email
string
identifiers.vuid
string
data
object
required

include additional event metadata

data.ts
integer

Timestamp of the event in unix time (epoch time). Automatically set to now if not present.

data.product_id
string

The product identifier associated with this event.

data.category
string

The category associated with this event. This can either be a flat category (Laptops) or hierarchical category using > as delimiters (Electronics > Computers > Laptops).

data.channel
string

The channel of this event. Automatically inferred as web when using Javascript tag, and offline when using HTTP API.

data.ua
string

The user-agent of the customer creating the event. Automatically inferred when using Javascript tag.

data.ip
string

The IP address of the customer. Automatically inferred when using Javascript tag.

data.title
string

The title of the page requested. Automatically inferred when using Javascript tag.

data.hostname
string

The hostname of the URL requested. Automatically inferred when using Javascript tag.

data.page
string

The path of the URL requested. For example /v1.0/docs/event-model. Automatically inferred when using Javascript tag.

data.source
string

Referral source for this event. Automatically inferred when using Javascript tag.

data.medium
string

Referral medium for this event. Automatically inferred when using Javascript tag.

data.campaign
string

Referral campaign for this event. Automatically inferred when using Javascript tag.

data.content
string

Referral content for this event. Automatically inferred when using Javascript tag.

data.keywords
string

Search keywords. Automatically inferred when using Javascript tag.

data.language
string

Browser language.

data.character_set
string

Browser character set. Automatically inferred when using Javascript tag.

data.days_since_last_visit
integer

Number of days since this customer's last visit. Automatically inferred when using Javascript tag.

data.landing
boolean

True when the event is generated from a landing page. Automatically inferred when using Javascript tag.

data.referrer
string

Referrer URL. Automatically inferred when using Javascript tag.

data.search_term
string

Search term for on-site search.

data.filter_field
string
data.filter_value
string
data.sort_direction
string
data.sort_field
string
{
  "type": "pageview",
  "identifiers": {
    "vuid": "12345",
  },
  "data": {
    "page": "/foo"
  }
}

A maximum batch size of 1000 events is permitted

[{
  "type": "pageview",
  "identifiers": {
    "vuid": "12345",
  },
  "data": {
    "page": "/foo"
  }
},
{
  "type": "pageview",
  "identifiers": {
    "vuid": "12345",
  },
  "data": {
    "page": "/bar"
  }
}]
curl --request POST \
  --url https://api.zaius.com/v3/events
var request = require("request");

var options = { method: 'POST', url: 'https://api.zaius.com/v3/events' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.zaius.com/v3/events")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.zaius.com/v3/events");

xhr.send(data);
import requests

url = "https://api.zaius.com/v3/events"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available
 
Suggest Edits

Add to Cart

 
posthttps://api.zaius.com/v3/events

Body Params

type
string
required

state the type of event

action
string

state the action of the event

identifiers
object
required

identify the customer that this event belongs to

data
object
data.product_id
string

the id of the product added to cart

{
  "type": "product",
  "action": "add_to_cart",
  "identifiers": {
    "vuid": "12345",
  },
  "data": {
    "product_id": "123"
  }
}
curl --request POST \
  --url https://api.zaius.com/v3/events
var request = require("request");

var options = { method: 'POST', url: 'https://api.zaius.com/v3/events' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.zaius.com/v3/events")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.zaius.com/v3/events");

xhr.send(data);
import requests

url = "https://api.zaius.com/v3/events"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available
 
Suggest Edits

Remove from Cart

 
posthttps://api.zaius.com/v3/events

Body Params

type
string
required

state the type of event

action
string

state the action of the event

identifiers
object
required

identify the customer that this event belongs to

data
object
data.product_id
string

the id of the product added to cart

{
  "type": "product",
  "action": "remove_from_cart",
  "identifiers": {
    "vuid": "12345",
  },
  "data": {
    "product_id": "123"
  }
}
curl --request POST \
  --url https://api.zaius.com/v3/events
var request = require("request");

var options = { method: 'POST', url: 'https://api.zaius.com/v3/events' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.zaius.com/v3/events")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.zaius.com/v3/events");

xhr.send(data);
import requests

url = "https://api.zaius.com/v3/events"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available
 
Suggest Edits

Product Detail View (PDP)

 
posthttps://api.zaius.com/v3/events

Body Params

type
string
required

state the type of event

action
string

state the action of the event

identifiers
object
required

identify the customer that this event belongs to

data
object
data.product_id
string

the id of the product viewed

{
  "type": "product",
  "action": "detail",
  "identifiers": {
    "vuid": "12345",
  },
  "data": {
    "product_id": "123"
  }
}
curl --request POST \
  --url https://api.zaius.com/v3/events
var request = require("request");

var options = { method: 'POST', url: 'https://api.zaius.com/v3/events' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.zaius.com/v3/events")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.zaius.com/v3/events");

xhr.send(data);
import requests

url = "https://api.zaius.com/v3/events"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available
 
Suggest Edits

Product Listing

 
posthttps://api.zaius.com/v3/events

Body Params

type
string
required

state the type of event

action
string

state the action of the event

identifiers
object
required

identify the customer that this event belongs to

data
object
data.product_id
string

the id of the product listed

{
  "type": "product",
  "action": "listing",
  "identifiers": {
    "vuid": "12345",
  },
  "data": {
    "product_id": "123"
  }
}
curl --request POST \
  --url https://api.zaius.com/v3/events
var request = require("request");

var options = { method: 'POST', url: 'https://api.zaius.com/v3/events' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.zaius.com/v3/events")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.zaius.com/v3/events");

xhr.send(data);
import requests

url = "https://api.zaius.com/v3/events"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available
 
Suggest Edits

Page View

 
posthttps://api.zaius.com/v3
 
curl --request POST \
  --url https://api.zaius.com/v3
var request = require("request");

var options = { method: 'POST', url: 'https://api.zaius.com/v3' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.zaius.com/v3")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.zaius.com/v3");

xhr.send(data);
import requests

url = "https://api.zaius.com/v3"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available
 
Suggest Edits

Order Purchase

Send Zaius events for Order Purchases

 
posthttps://api.zaius.com/v3/events

Body Params

type
string
required

order event type

action
string

order action of purchase

identifiers
object
required

identify the customer that this event belongs to

data
object
required

event metadata

data.ts
integer

Timestamp of the event in unix time (epoch time). Automatically set to now if not present.

data.product_id
string

The product identifier associated with this event.

data.category
string

The category associated with this event. This can either be a flat category (Laptops) or hierarchical category using > as delimiters (Electronics > Computers > Laptops).

data.channel
string

The channel of this event. Automatically inferred as web when using Javascript tag, and offline when using HTTP API.

data.ua
string

The user-agent of the customer creating the event. Automatically inferred when using Javascript tag.

data.ip
string

The IP address of the customer. Automatically inferred when using Javascript tag.

data.title
string

The title of the page requested. Automatically inferred when using Javascript tag.

data.hostname
string

The hostname of the URL requested. Automatically inferred when using Javascript tag.

data.page
string

The path of the URL requested. For example /v1.0/docs/event-model. Automatically inferred when using Javascript tag.

data.source
string

Referral source for this event. Automatically inferred when using Javascript tag.

data.medium
string

Referral medium for this event. Automatically inferred when using Javascript tag.

data.campaign
string

Referral campaign for this event. Automatically inferred when using Javascript tag.

data.content
string

Referral content for this event. Automatically inferred when using Javascript tag.

data.keywords
string

Search keywords. Automatically inferred when using Javascript tag.

data.language
string

Browser language.

data.character_set
string

Browser character set. Automatically inferred when using Javascript tag.

data.days_since_last_visit
integer

Number of days since this customer's last visit. Automatically inferred when using Javascript tag.

data.landing
boolean

True when the event is generated from a landing page. Automatically inferred when using Javascript tag.

data.referrer
string

Referrer URL. Automatically inferred when using Javascript tag.

data.search_term
string

Search term for on-site search.

data.filter_field
string
data.filter_value
string
data.sort_direction
string
data.sort_field
string
{
  "type": "order",
  "action": "purchase",
  "identifiers": {
  	"email":"bob@acme.com"
  },
  "data": {
    "order": {
      "order_id": "OR345",
      "total": 109.65,
      "discount": 5.00,
      "subtotal": 103.00,
      "tax": 5.15,
      "shipping": 6.50,
      "coupon_code": "5OFF",
      "items": [
        {
          "product_id": "2045",
          "price": 19.00,
          "quantity": 5,
          "discount": 0.00,
          "subtotal": 95.00
        },
        {
          "product_id": "2091",
          "price": 10.00,
          "quantity": 1,
          "discount": 2.00,
          "subtotal": 8.00
        }
      ]
    }
  }
}
curl --request POST \
  --url https://api.zaius.com/v3/events
var request = require("request");

var options = { method: 'POST', url: 'https://api.zaius.com/v3/events' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.zaius.com/v3/events")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.zaius.com/v3/events");

xhr.send(data);
import requests

url = "https://api.zaius.com/v3/events"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available
 
Suggest Edits

Order Refund

Send an event when a customer has been issued a refund for an order

 
posthttps://api.zaius.com/v3/events

Body Params

type
string
required

order event type

action
string

order action of refund

identifiers
object
required

identify the customer that this event belongs to

data
object
required

event metadata

data.ts
integer

Timestamp of the event in unix time (epoch time). Automatically set to now if not present.

data.product_id
string

The product identifier associated with this event.

data.category
string

The category associated with this event. This can either be a flat category (Laptops) or hierarchical category using > as delimiters (Electronics > Computers > Laptops).

data.channel
string

The channel of this event. Automatically inferred as web when using Javascript tag, and offline when using HTTP API.

data.ua
string

The user-agent of the customer creating the event. Automatically inferred when using Javascript tag.

data.ip
string

The IP address of the customer. Automatically inferred when using Javascript tag.

data.title
string

The title of the page requested. Automatically inferred when using Javascript tag.

data.hostname
string

The hostname of the URL requested. Automatically inferred when using Javascript tag.

data.page
string

The path of the URL requested. For example /v1.0/docs/event-model. Automatically inferred when using Javascript tag.

data.source
string

Referral source for this event. Automatically inferred when using Javascript tag.

data.medium
string

Referral medium for this event. Automatically inferred when using Javascript tag.

data.campaign
string

Referral campaign for this event. Automatically inferred when using Javascript tag.

data.content
string

Referral content for this event. Automatically inferred when using Javascript tag.

data.keywords
string

Search keywords. Automatically inferred when using Javascript tag.

data.language
string

Browser language.

data.character_set
string

Browser character set. Automatically inferred when using Javascript tag.

data.days_since_last_visit
integer

Number of days since this customer's last visit. Automatically inferred when using Javascript tag.

data.landing
boolean

True when the event is generated from a landing page. Automatically inferred when using Javascript tag.

data.referrer
string

Referrer URL. Automatically inferred when using Javascript tag.

data.search_term
string

Search term for on-site search.

data.filter_field
string
data.filter_value
string
data.sort_direction
string
data.sort_field
string

Refunds are treated the same as returns in Zaius (i.e. negative impact on revenue). You can use either. Use both if you want to distinguish between inventory being returned to you (a return) and just money being issued to the original purchaser (a refund). If inventory is returned and money is issued back to the purchaser, Zaius recommends using the return order action.

{
  "type": "order",
  "action": "refund",
  "identifiers": {
  	"email":"bob@acme.com"
  },
  "data": {
    "order": {
      "order_id": "OR345",
      "total": 109.65,
      "discount": 5.00,
      "subtotal": 103.00,
      "tax": 5.15,
      "shipping": 6.50,
      "coupon_code": "5OFF",
      "items": [
        {
          "product_id": "2045",
          "price": 19.00,
          "quantity": 5,
          "discount": 0.00,
          "subtotal": 95.00
        },
        {
          "product_id": "2091",
          "price": 10.00,
          "quantity": 1,
          "discount": 2.00,
          "subtotal": 8.00
        }
      ]
    }
  }
}
curl --request POST \
  --url https://api.zaius.com/v3/events
var request = require("request");

var options = { method: 'POST', url: 'https://api.zaius.com/v3/events' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.zaius.com/v3/events")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.zaius.com/v3/events");

xhr.send(data);
import requests

url = "https://api.zaius.com/v3/events"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available
 
Suggest Edits

Order Return

Send an event when a customer has returned some or all of the items in an order and been refunded

 
posthttps://api.zaius.com/v3/events

Body Params

type
string
required

order event type

action
string

order action of return

identifiers
object
required

identify the customer that this event belongs to

data
object
required

event metadata

data.ts
integer

Timestamp of the event in unix time (epoch time). Automatically set to now if not present.

data.product_id
string

The product identifier associated with this event.

data.category
string

The category associated with this event. This can either be a flat category (Laptops) or hierarchical category using > as delimiters (Electronics > Computers > Laptops).

data.channel
string

The channel of this event. Automatically inferred as web when using Javascript tag, and offline when using HTTP API.

data.ua
string

The user-agent of the customer creating the event. Automatically inferred when using Javascript tag.

data.ip
string

The IP address of the customer. Automatically inferred when using Javascript tag.

data.title
string

The title of the page requested. Automatically inferred when using Javascript tag.

data.hostname
string

The hostname of the URL requested. Automatically inferred when using Javascript tag.

data.page
string

The path of the URL requested. For example /v1.0/docs/event-model. Automatically inferred when using Javascript tag.

data.source
string

Referral source for this event. Automatically inferred when using Javascript tag.

data.medium
string

Referral medium for this event. Automatically inferred when using Javascript tag.

data.campaign
string

Referral campaign for this event. Automatically inferred when using Javascript tag.

data.content
string

Referral content for this event. Automatically inferred when using Javascript tag.

data.keywords
string

Search keywords. Automatically inferred when using Javascript tag.

data.language
string

Browser language.

data.character_set
string

Browser character set. Automatically inferred when using Javascript tag.

data.days_since_last_visit
integer

Number of days since this customer's last visit. Automatically inferred when using Javascript tag.

data.landing
boolean

True when the event is generated from a landing page. Automatically inferred when using Javascript tag.

data.referrer
string

Referrer URL. Automatically inferred when using Javascript tag.

data.search_term
string

Search term for on-site search.

data.filter_field
string
data.filter_value
string
data.sort_direction
string
data.sort_field
string

Returns are treated the same as refunds in Zaius (i.e. negative impact on revenue). You can use either. Use both if you want to distinguish between inventory being returned to you (a return) and just money being issued to the original purchaser (a refund). If inventory is returned and money is issued back to the purchaser, Zaius recommends using the return order action.

{
  "type": "order",
  "action": "return",
  "identifiers": {
  	"email":"bob@acme.com"
  },
  "data": {}
}
curl --request POST \
  --url https://api.zaius.com/v3/events
var request = require("request");

var options = { method: 'POST', url: 'https://api.zaius.com/v3/events' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.zaius.com/v3/events")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.zaius.com/v3/events");

xhr.send(data);
import requests

url = "https://api.zaius.com/v3/events"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available
 
Suggest Edits

Order Cancellation

Send an event when a customer has canceled their order

 
posthttps://api.zaius.com/v3/events

Body Params

type
string
required

order event type

action
string

order action of cancel

identifiers
object
required

identify the customer that this event belongs to

data
object
required

event metadata

data.ts
integer

Timestamp of the event in unix time (epoch time). Automatically set to now if not present.

data.product_id
string

The product identifier associated with this event.

data.category
string

The category associated with this event. This can either be a flat category (Laptops) or hierarchical category using > as delimiters (Electronics > Computers > Laptops).

data.channel
string

The channel of this event. Automatically inferred as web when using Javascript tag, and offline when using HTTP API.

data.ua
string

The user-agent of the customer creating the event. Automatically inferred when using Javascript tag.

data.ip
string

The IP address of the customer. Automatically inferred when using Javascript tag.

data.title
string

The title of the page requested. Automatically inferred when using Javascript tag.

data.hostname
string

The hostname of the URL requested. Automatically inferred when using Javascript tag.

data.page
string

The path of the URL requested. For example /v1.0/docs/event-model. Automatically inferred when using Javascript tag.

data.source
string

Referral source for this event. Automatically inferred when using Javascript tag.

data.medium
string

Referral medium for this event. Automatically inferred when using Javascript tag.

data.campaign
string

Referral campaign for this event. Automatically inferred when using Javascript tag.

data.content
string

Referral content for this event. Automatically inferred when using Javascript tag.

data.keywords
string

Search keywords. Automatically inferred when using Javascript tag.

data.language
string

Browser language.

data.character_set
string

Browser character set. Automatically inferred when using Javascript tag.

data.days_since_last_visit
integer

Number of days since this customer's last visit. Automatically inferred when using Javascript tag.

data.landing
boolean

True when the event is generated from a landing page. Automatically inferred when using Javascript tag.

data.referrer
string

Referrer URL. Automatically inferred when using Javascript tag.

data.search_term
string

Search term for on-site search.

data.filter_field
string
data.filter_value
string
data.sort_direction
string
data.sort_field
string

The order purchase and cancel events remain in Zaius (e.g., on the customer profile page, and for segmentation), and revenue is negatively impacted, but the order no longer impacts customer lifecycle. This is in contrast to returns and refunds, where the order still counts in determining the order count, and thus lifecycle, for a customer.

{
  "type": "order",
  "action": "cancel",
  "identifiers": {
  	"email":"bob@acme.com"
  },
  "data": {}
}
curl --request POST \
  --url https://api.zaius.com/v3/events
var request = require("request");

var options = { method: 'POST', url: 'https://api.zaius.com/v3/events' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.zaius.com/v3/events")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.zaius.com/v3/events");

xhr.send(data);
import requests

url = "https://api.zaius.com/v3/events"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available
 
Suggest Edits

Registration

 
posthttps://api.zaius.com/v3/events

Body Params

type
string
required

the type of event

action
string

the type of action

identifiers
object
required

identify the customer that this event belongs to

{
  "type": "account",
  "action": "register",
  "identifiers": {
  	"email":"bob@acme.com"
  }
}
curl --request POST \
  --url https://api.zaius.com/v3/events
var request = require("request");

var options = { method: 'POST', url: 'https://api.zaius.com/v3/events' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.zaius.com/v3/events")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.zaius.com/v3/events");

xhr.send(data);
import requests

url = "https://api.zaius.com/v3/events"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available
 
posthttps://api.zaius.com/v3/events

Body Params

type
string
required

the type of event

action
string

the type of action

identifiers
object
required

identify the customer that this event belongs to

{
  "type": "account",
  "action": "login",
  "identifiers": {
  	"email":"bob@acme.com"
  }
}
curl --request POST \
  --url https://api.zaius.com/v3/events
var request = require("request");

var options = { method: 'POST', url: 'https://api.zaius.com/v3/events' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.zaius.com/v3/events")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.zaius.com/v3/events");

xhr.send(data);
import requests

url = "https://api.zaius.com/v3/events"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available
 
posthttps://api.zaius.com/v3/events

Body Params

type
string
required

the type of event

action
string

the type of action

identifiers
object
required

identify the customer that this event belongs to

{
  "type": "account",
  "action": "logout",
  "identifiers": {
  	"email":"bob@acme.com"
  }
}
curl --request POST \
  --url https://api.zaius.com/v3/events
var request = require("request");

var options = { method: 'POST', url: 'https://api.zaius.com/v3/events' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.zaius.com/v3/events")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.zaius.com/v3/events");

xhr.send(data);
import requests

url = "https://api.zaius.com/v3/events"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available
 
 
posthttps://api.zaius.com/v3/events

Body Params

type
string
required

the type of event

action
string

the type of action

identifiers
object
required

identify the customer that this event belongs to

data
object
required

event metadata

 
curl --request POST \
  --url https://api.zaius.com/v3/events
var request = require("request");

var options = { method: 'POST', url: 'https://api.zaius.com/v3/events' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.zaius.com/v3/events")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.zaius.com/v3/events");

xhr.send(data);
import requests

url = "https://api.zaius.com/v3/events"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available
 
Suggest Edits

Ad Impression

 
posthttps://api.zaius.com/v3/events

Body Params

type
string
required

the type of event

action
string

the type of action

identifiers
object
required

identify the customer that this event belongs to

data
object
required

event metadata

{
  "type": "navigation",
  "action": "search",
  "identifiers": {
  	"email":"bob@acme.com"
  },
  "data": {
			"search_term":"cameras, vcr",
     	"category": "electronics > consumer",
    }
  }
}
curl --request POST \
  --url https://api.zaius.com/v3/events
var request = require("request");

var options = { method: 'POST', url: 'https://api.zaius.com/v3/events' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.zaius.com/v3/events")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.zaius.com/v3/events");

xhr.send(data);
import requests

url = "https://api.zaius.com/v3/events"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available
 
 
 
Suggest Edits

Send Event

 
// sending custom events with custom fields
ZaiusEvent* event = [ZaiusEvent eventWithEventType:@"map" action:@"explore"];
// page is a field available on any event, but primarily used for pageviews
event[@"page"] = @"map_explorer";
// where map_region is a custom field you added to events in the Zaius App
event[@"map_region"] = @"North America";
[Zaius event:event];
// sending custom events with custom fields
let event = ZaiusEvent(eventType: "map", action: "explore")
// page is a field available on any event, buy primarily used for pageviews
event["page"] = "map_explorer"
// where map_region is a custom field you added to events in the Zaius App
event["map_region"] = "North America"
Zaius.event(event)
 
Suggest Edits

Page Viewed

 
[Zaius event:[ZaiusEvent pageview:@"page1"]];
Zaius.event(ZaiusEvent.pageview("page1"))
 
 
 
 
Suggest Edits

Send Event

 
ZaiusEvent genericEvent = new ZaiusEvent("my_event_type")
  .action("my_action")
  .addField("some_other_key", "some_custom_field_value");
Zaius.sendEvent(genericEvent);
 
Suggest Edits

Page Viewed

 
Zaius.sendEvent(new ZaiusPageView().page("page1"));
 
 

Zaius supports the concept of Lists to manage communication consent and enable preference centers with unique opt-outs such as newsletters, promotions, and product updates.

Global Opt-In vs List Subscriptions

Global Opt-In

Communication Consent

Does not change the customer's list subscriptions, but determines whether or not the customer can receive messages via Zaius

List Subscription

Communication Preferences

A specific type of communication that the customer prefers to receive or your team has decided the user should receive. For example: Promotions, Product Updates, and more

When using {{zaius.unsub_url}} in an email message, Zaius automatically adds an unsubscribe link that unsubscribes the user from the list within the campaign constraints. If no list is defined, a global opt-out is used.

zaius_all list

For backwards compatibility purposes, Zaius provides a list named zaius_all to manage global opt-ins. Adding a user to the zaius_all list is identical to setting their opted_in status to true. Always use the opted-in boolean field over the zaius_all list whenever possible as zaius_all will be deprecated over time.

Once a user has been globally opted-out, they will not receive messages under any circumstance unless explicitly opted-in again (or added to the legacy zaius_all list)

 
Suggest Edits

List Events

 

All updates to a customer's list subscriptions generate an event with an event type list and an event action of subscribe.

We recommend sending a list event directly only in those cases wherein you need to utilize custom fields.

 

Our Web SDK has built-in subscribe and unsubscribe functions. These functions support adding (or removing) a user from one or more lists in a simple syntax.

As these functions are often called after completing a form which may collect additional customer information, they also support updating the customer profile in a single consolidated syntax.

//Subscribe Johnny to newsletters only
zaius.subscribe({list_id: 'newsletter', email: 'johnny@zaius.com'});

//Remove Johnny from newsletters
zaius.unsubscribe({list_id: 'newsletter', email: 'johnny@zaius.com'});
//Subscribe Johnny to all three lists at once
zaius.subscribe({
  list_id: ["newsletter", "promotion", "product_update"], 
  email: "johnny@zaius.com"
});

//Remove Johnny from the newsletter and product update lists.
zaius.unsubscribe({
  list_id: ["newsletter", "product_update"], 
  email: "johnny@zaius.com"
});
zaius.subscribe({
  //Subscribe Johnny to all lists
  list_id: ["newsletter", "promotion", "product_update"],
  email: "johnny@zaius.com",
  //Update Johnny's record to include his full name
  first_name: "Johnny",
  last_name: "Zaius",
  //Store information on the subscribe events
  event_custom_field: "my custom value",
  custom_number_field: 123
});

//zaius.unsubscribe also fully supports this syntax.
zaius.subscribe(subscriptionObject, onSuccess, onError);
zaius.unsubscribe(subscriptionObject, onSuccess, onError);

//subscriptionObject is required and must have the keys list_id and email
//    list_id must be a nonempty string or array of nonempty strings
//    email must be a nonempty email-like string

Adding Additional Fields

Any fields beyond email and list_id are submitted on all event & profile updates triggered by the call.

If a field name exists on both events and the customer profile, it will be stored in both places.

Both methods also support onSuccess and onError callbacks. These are called in response to client-side success (parameters passed validation, after we've triggered our tracking calls) or failure (validation failed, no tracking calls submitted).

 
 
 
Suggest Edits

View Lists

Returns all lists (name and ID) for the authenticated Zaius account.

 
gethttps://api.zaius.com/v3/lists
 
curl --request GET \
  --url https://api.zaius.com/v3/lists
var request = require("request");

var options = { method: 'GET', url: 'https://api.zaius.com/v3/lists' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.zaius.com/v3/lists")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.zaius.com/v3/lists");

xhr.send(data);
import requests

url = "https://api.zaius.com/v3/lists"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
    "lists": [
        {
            "name": "Example List",
            "created_at": "2018-09-10T21:07:10+00:00",
            "list_id": "example_list"
        },
        {
            "name": "Example List 2",
            "created_at": "2018-10-15T13:43:46+00:00",
            "list_id": "example_list_2"
        }
    ]
}
 
Suggest Edits

Change List Name

 
puthttps://api.zaius.com/v3/lists/list-id

Path Params

list-id
string
required

The id of the list to update

Body Params

name
string

The new name of the list

 
curl --request PUT \
  --url https://api.zaius.com/v3/lists/list-id
var request = require("request");

var options = { method: 'PUT',
  url: 'https://api.zaius.com/v3/lists/list-id' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.zaius.com/v3/lists/list-id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("PUT", "https://api.zaius.com/v3/lists/list-id");

xhr.send(data);
import requests

url = "https://api.zaius.com/v3/lists/list-id"

response = requests.request("PUT", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "updated": {
    "list_id": "foo-id",
    "name": "foo"
  }
}
{
  "title": "Bad Request",
  "status": 400,
  "timestamp": "2018-03-15T18:18:32Z",
  "detail": {
    "invalids": [
      {
        "name": "foo",
        "reason": "List name must be unique"
      }
    ]
  }
}
 
Suggest Edits

Get Subscriptions

Fetch the list subscriptions for a customer given a identifier query parameter

 
gethttps://api.zaius.com/v3/lists/subscriptions

Query Params

email
string

the customer's email

customer_id
string

identifier shared with Zaius

include
string

optional comma separated list of list_ids to limit result

exclude
string

optional comma separated list of list_ids to remove from the result

Note this will also return the zaius_all list which represents the customer's global subscription status.

curl --request GET \
  --url https://api.zaius.com/v3/lists/subscriptions
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.zaius.com/v3/lists/subscriptions' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.zaius.com/v3/lists/subscriptions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.zaius.com/v3/lists/subscriptions");

xhr.send(data);
import requests

url = "https://api.zaius.com/v3/lists/subscriptions"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "customer": {
    "email": "email@address"
  },
  "opted_in": true,
  "subscriptions": [
    {
      "name": "foo",
      "list_id": "foo",
      "subscribed": true
    },
    {
      "name": "bar",
      "list_id": "bar",
      "subscribed": true
    }
  ]
}
{
  "title": "Bad Request",
  "status": 400,
  "timestamp": "2018-03-15T19:07:51Z",
  "detail": {
    "invalids": [
      {
        "name": [
          "vuid",
          "zek",
          "zm64_id"
        ],
        "reason": "One of parameters vuid or zek + zm64_id is required"
      }
    ]
  }
}
{
  "title": "Bad Request",
  "status": 400,
  "timestamp": "2018-03-15T19:10:39Z",
  "detail": {
    "invalids": [
      {
        "name": [
          "email",
          "customer_id"
        ],
        "reason": "One of parameters email or customer_id required"
      }
    ]
  }
}
 
Suggest Edits

Create List

Create a new List

 
posthttps://api.zaius.com/v3/lists

Body Params

name
string

The name of the List to create

{
  "name": "foo"
}
curl --request POST \
  --url https://api.zaius.com/v3/lists
var request = require("request");

var options = { method: 'POST', url: 'https://api.zaius.com/v3/lists' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.zaius.com/v3/lists")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.zaius.com/v3/lists");

xhr.send(data);
import requests

url = "https://api.zaius.com/v3/lists"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "created": {
    "list_id": "api generated id",
    "name": "foo"
  }
}
{
  "title": "Bad Request",
  "status": 400,
  "timestamp": "2018-03-15T18:18:32Z",
  "detail": {
    "invalids": [
      {
        "name": "foo",
        "reason": "List name must be unique"
      }
    ]
  }
}
 
Suggest Edits

Update Channel Opt-In

Update the consent for a user to receive emails

 
posthttps://api.zaius.com/v3/lists/subscriptions

Body Params

opted_in
boolean
required
email
string
required
{
	"opted_in": true,
	"email": "foo"
}
curl --request POST \
  --url https://api.zaius.com/v3/lists/subscriptions
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.zaius.com/v3/lists/subscriptions' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.zaius.com/v3/lists/subscriptions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.zaius.com/v3/lists/subscriptions");

xhr.send(data);
import requests

url = "https://api.zaius.com/v3/lists/subscriptions"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

No response examples available
 
Suggest Edits

Update Subscription (Public)

Update one or more subscriptions for a customer

 
posthttps://api.zaius.com/v3/lists/subscriptions

Body Params

list_id
string
required
email
string
required
subscribed
boolean
required
{
	"list_id": "all",
	"email": "foo@acme.com",
	"subscribed": true
}
curl --request POST \
  --url https://api.zaius.com/v3/lists/subscriptions
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.zaius.com/v3/lists/subscriptions' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.zaius.com/v3/lists/subscriptions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.zaius.com/v3/lists/subscriptions");

xhr.send(data);
import requests

url = "https://api.zaius.com/v3/lists/subscriptions"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
    {
      "list_id": "all",
      "email": "foo@acme.com",
      "subscribed": true
    }
}
{
  "title": "Bad Request",
  "status": 400,
  "timestamp": "2018-03-15T18:45:34Z",
  "detail": {
    "invalids": [
      {
        "name": [
          "list_id",
          "email",
          "subscribed"
        ],
        "reason": "list_id, email and subscribed are required"
      }
    ]
  }
}
{
  "title": "Not Found",
  "status": 404,
  "timestamp": "2018-03-15T18:48:54Z",
  "detail": {
    "message": "List 'does not exist' was not found"
  }
}
 
Suggest Edits

Update Multiple

Update one or more subscriptions for a customer

 
posthttps://api.zaius.com/v3/lists/subscriptions

Body Params

array
array of objects
required

unnamed array

[
  {
    "opted_in": true,
    "email": "foo"
  },
  {
    "list_id": "bar",
    "email": "bar",
    "subscribed": true
  }
]
curl --request POST \
  --url https://api.zaius.com/v3/lists/subscriptions
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.zaius.com/v3/lists/subscriptions' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.zaius.com/v3/lists/subscriptions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.zaius.com/v3/lists/subscriptions");

xhr.send(data);
import requests

url = "https://api.zaius.com/v3/lists/subscriptions"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
    {
      "list_id": "all",
      "email": "sean@zaius.com",
      "subscribed": true
    }
}
{
  "title": "Bad Request",
  "status": 400,
  "timestamp": "2018-03-15T18:45:34Z",
  "detail": {
    "invalids": [
      {
        "name": [
          "list_id",
          "email",
          "subscribed"
        ],
        "reason": "list_id, email and subscribed are required"
      }
    ]
  }
}
{
  "title": "Not Found",
  "status": 404,
  "timestamp": "2018-03-15T18:48:54Z",
  "detail": {
    "message": "List 'does not exist' was not found"
  }
}
 
Suggest Edits

Update Subscription(s)

Update one or more subscriptions for a customer

 
posthttps://api.zaius.com/v3/lists/subscriptions

Body Params

list_id
string
required
email
string
required
subscribed
boolean
required

Users must be opted-in to receive emails!

{
	"list_id": "bar",
	"email": "foo@acme.com",
	"subscribed": true
}
curl --request POST \
  --url https://api.zaius.com/v3/lists/subscriptions
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.zaius.com/v3/lists/subscriptions' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.zaius.com/v3/lists/subscriptions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.zaius.com/v3/lists/subscriptions");

xhr.send(data);
import requests

url = "https://api.zaius.com/v3/lists/subscriptions"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
	"list_id": "bar",
  "email": "bar"
	"subscribed": true
}
{
  "title": "Bad Request",
  "status": 400,
  "timestamp": "2018-03-15T18:45:34Z",
  "detail": {
    "invalids": [
      {
        "name": [
          "list_id",
          "email",
          "subscribed"
        ],
        "reason": "list_id, email and subscribed are required"
      }
    ]
  }
}
{
  "title": "Not Found",
  "status": 404,
  "timestamp": "2018-03-15T18:48:54Z",
  "detail": {
    "message": "List 'does not exist' was not found"
  }
}
 
Suggest Edits

Overview

Provides personalized production recommendations for your customers.

 
 
 
Suggest Edits

Products

Fetch production recommendations for a single customer. Customer can be identifier using one of vuid, customer_id or email. In addition products can be filtered using rules based on fields found on the products in your catalog. Speak with your customer service representative if you have a requirement to set up default filtering.

Product records that are returned will include all the base Zaius product fields in addition to any custom fields defined in your Product objects.

 
gethttps://api.zaius.com/v3/recommendations/products

Query Params

vuid
string

tag based customer identifier

customer_id
string

customer's identifier

email
string

customer's email address

zaius_alias_*
string

customer's alias

sort
string

product field to sort on. default sort is highest to lowest recommendation rank

limit
int32

number of top products to recommend

order
string

sort order. valid values are asc and desc

 
curl --request GET \
  --url https://api.zaius.com/v3/recommendations/products
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.zaius.com/v3/recommendations/products' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.zaius.com/v3/recommendations/products")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.zaius.com/v3/recommendations/products");

xhr.send(data);
import requests

url = "https://api.zaius.com/v3/recommendations/products"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

[
  {
    "product_id": "1",
    "name": "Product One",
    "brand": "brand",
    "sku": "one",
    "upc": "1",
    "category": "Products",
    "price": "1.00",
    "image_url": "https://path.to.image/product-1",
  },{
    "product_id": "2",
    "name": "Product Two",
    "brand": "brand",
    "sku": "two",
    "upc": "2",
    "category": "Products",
    "price": "2.00",
    "image_url": "https://path.to.image/product-2",
  }
]
[]
 
Suggest Edits

Overview

The exports API will allow you do perform on demand full object exports of your Zaius data.

 

This API is in Beta

Request & response formats are subject to change

 
Suggest Edits

Export Objects

Asynchronously export your objects to s3 buckets. Determining when your request has been completed can be done in one of two ways. First a "complete.json" will be written to bucket specified in the response. The status check endpoint can also be polled with the identifier returned from the response to get the status.

 
posthttps://api.zaius.com/v3/exports

Body Params

objects
array of strings

Array of objects names to export. When absent all objects will be exported.

format
string

The export format. Valid options are CSV and Parquet, defaults to CSV

delimiter
string

Delimiter to use for field separator. Valid options are comma, tab, and pipe. Defaults to comma.

Response format

field
type
description

id

string

Request identifier. Use this when consuming the get status api to pull the status for your export request.

path

string

s3 path to the bucket where the export files will be placed

state

string

Export requests go through a set of states.

  • pending: export job is waiting to start
  • running: export job is running
  • completed: export completed
  • completed_with_errors: export completed but one or more of the objects couldn't be exported.

requested_at

iso 8601 date time

when the request was received

detail.id

string

export definition identifier

detail.format

string

requested exported format

detail.delimiter

string

requested delimiter

detail.objects

array

requested objects to be exported

{
	"objects": ["events"],
  "format": "csv",
  "delimiter": "comma"
}
A binary file was returned

You couldn't be authenticated

{
  "id": "220bd245-59dc-4423-a4d1-4090d70b2904",
  "path": "s3://zaius-outgoing/tracker-id/data-exports/220bd245-59dc-4423-a4d1-4090d70b2904",
  "state": "pending",
  "requested_at": "2018-09-11T08:51:12.738-04:00",
  "detail": {
    "id": "446dc886-489d-43a6-9634-effe045046c5",
    "format": "csv",
    "delimiter": "comma",
    "objects": [
      "events"
    ]
  }
}
{
  "title": "Unprocessable Entity",
  "status": 422,
  "timestamp": "2018-09-11T13:22:31.833Z",
  "detail": {
    "message": "Unable to process request.  The following object(s) are currently being exported: events"
  }
}
 
Suggest Edits

Export Objects with Filtering

Asynchronously export your objects to s3 buckets. Determining when your request has been completed can be done in one of two ways. First a "complete.json" will be written to bucket specified in the response. The status check endpoint can also be polled with the identifier returned from the response to get the status.

The exports endpoint supports a filtering capability in addition to the full table exports that are possible when using the objects field in the request JSON. Filtering is trigger by using the select field. Select provides a simple JSON syntax for selecting certain fields and filtering that can span several related Objects. Filters support conjunctions (and & or) to any depth and field comparisons include all the operators you would expect for doing simple sql-like where clause filtering.

 
posthttps://api.zaius.com/v3/exports

Body Params

format
string

The export format. Valid options are CSV and Parquet, defaults to CSV

delimiter
string

Delimiter to use for field separator. Valid options are comma, tab, and pipe. Defaults to comma.

select
object
select.object
string
required

Base object for the filter

select.fields
array of strings
required

Array of fields you wish to include in the export. Fields can span different Objects, eg ["page", "referrer", "product.name"]. ["*"] can be used to select all fields on the specified object.

select.filter
object

Optional filter specification. Filters can include simple field comparisons or can be arbitrarily nested conjunctions (ands ors) of comparisons. Comparison operators include: {"=", "!=", ">", ">=", "<", "<=", "like", "not like", "ilike", "not ilike", "is", "is not"}. null and not null comparisons are also supported (see examples below). like based operators support value wildcarding using the '%' character.

select.sorts
array of s

Order by specification applied for each export file (a single table export will cross multiple files). Simple array of field and order tuples. Order is optional with valid values of {asc, desc} with asc being the default if not supplied.

 
{
  "select": {
    "fields": ["page", "referrer"],
    "object": "events"
  }
}
{
  "select": {
    "fields": ["page","product.name"],
    "object": "events",
    "filter": {
      "field": "product.name",
      "operator": "!=",
      "value": null
    }
  }
}
{
  "select": {
    "fields": ["page", "product.name", "product.parent_product.name"],
    "object": "events",
    "filter": {
      "and" : [{
        "field": "page",
        "operator": "!=",
        "value": null
      },{
        "or": [{
          "field": "product.name",
          "operator": "ilike",
          "value": "%shirt%"
        },{
          "field": "product.name",
          "operator": "ilike",
          "value": "%pants%"
        }]
      }]
    },
    "sorts": [{"field": "product.name"}]
  }
}
A binary file was returned

You couldn't be authenticated

{
  "id": "e04ae6f9-9dd7-4999-a555-a518c852223c",
  "path": "s3://zaius-outgoing-staging/vdl/data-exports/e04ae6f9-9dd7-4999-a555-a518c852223c",
  "state": "pending",
  "requested_at": "2018-10-23T11:56:56.347-04:00",
  "detail": {
    "id": "19350c1d-273c-4493-b01c-06f86803a441",
    "format": "csv",
    "delimiter": "comma",
    "select": {
      "object": "events",
      "fields": [
        "page",
        "product.name"
      ],
      "filter": {
        "and": [
          {
            "field": "page",
            "operator": "!=",
            "value": null
          },
          {
            "or": [
              {
                "field": "product.name",
                "operator": "ilike",
                "value": "%shirt%"
              },
              {
                "field": "product.name",
                "operator": "ilike",
                "value": "%pants%"
              }
            ]
          }
        ]
      },
      "sorts": [
        {
          "field": "product.name",
          "order": null
        }
      ]
    },
    "objects": [
      "events"
    ]
  }
}
{
  "title": "Not Found",
  "status": 404,
  "timestamp": "2018-10-23T15:59:47.217Z",
  "detail": {
      "message": "Unable to locate relation events.produt."
  }
}
 
Suggest Edits

Export Status

Fetch the status of export requests. By default the endpoint will return all in flight (pending or running) export requests. Specific export requests can be requested by including the export_id path parameter.

 
gethttps://api.zaius.com/v3/exports/export_id

Path Params

export_id
string
required

Identifier provided in the response from the export request.

Response format

field
type
description

id

string

Request identifier. Use this when consuming the get status api to pull the status for your export request.

path

string

s3 path to the bucket where the export files will be placed

state

string

Export requests go through a set of states.

  • pending: export job is waiting to start
  • running: export job is running
  • completed: export completed
  • completed_with_errors: export completed but one or more of the objects couldn't be exported.

requested_at

iso 8601 date time

when the request was received

detail.id

string

export definition identifier

detail.format

string

requested exported format

detail.delimiter

string

requested delimiter

detail.objects

array

requested objects to be exported.

curl --request GET \
  --url https://api.zaius.com/v3/exports/export_id
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.zaius.com/v3/exports/export_id' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.zaius.com/v3/exports/export_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.zaius.com/v3/exports/export_id");

xhr.send(data);
import requests

url = "https://api.zaius.com/v3/exports/export_id"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "id": "1cdecaed-98cf-47cb-a3e3-49331a0e9980",
  "path": "s3://zaius-outgoing-staging/vdl/data-exports/1cdecaed-98cf-47cb-a3e3-49331a0e9980",
  "state": "running",
  "requested_at": "2018-09-11T09:29:07-04:00",
  "detail": {
    "id": "2fe41023-a1c9-447a-8305-c10990f222cf",
    "format": "csv",
    "delimiter": "comma",
    "objects": [
      "events"
    ]
  }
}
 
 

This API is in beta

Request & response formats are subject to change

Objects are composed of Fields. Fields link objects together via Relations.

Objects

{
  "name": "object_name",
  "display_name": "Display Name",
  "alias": "object_alias",
  "fields": [],
  "relations": []
}
property
description

name

name for the object

display_name

user-friendly name shown within Zaius

alias

alternative name for the object that can be used for ingest

fields

collection of Field objects constituting the Object

relations

collection of Relation objects|

Fields

{
  "name": "field_name",
  "type": "number",
  "auto": true,
  "display_name": "Display Name",
  "description": "Description of field",
  "created_by": "zaius",
  "primary_key": true
}
property
description

name

name of the field

type

field data type. options are number, timestamp, text, boolean

auto

(read only) marks the field as one that is auto populated by Zaius

display_name

the user-friendly name used within Zaius

description

description of the field

created_by

(read only) specifies what/who created the field. current values as zaius and account

primary_key (optional)

marks the field as identifying for the containing object. only allowed during object creation.

Relations

Representation describing a relationship between two objects. The Object containing the Relation definition is the parent object.

{
  "name": "relation_name",
  "display_name": "Relation Display Name",
  "child_object": "child_object_name",
  "join_fields": [{
    "parent": "child_id",
    "child": "child_id"
  }]
}
field
description

name

name for the relation

display_name

user-friendly name shown within Zaius

child_object

child Object name

join_fields

collection of parent child pairs. parent is the field name (foreign key) on the owning Object and child is the related Objects primary key. Multiple are allowed to support objects with compound primary keys.

 
 
{
  "name": "object_name",
  "display_name": "Display Name",
  "alias": "object_alias",
  "fields": [],
  "relations": []
}
property
description

name

name for the object

display_name

user-friendly name shown within Zaius

alias

alternative name for the object that can be used for ingest

fields

collection of Field objects constituting the Object

relations

collection of Relation objects|

 
Suggest Edits

Create Object

Create a new Object within Zaius, define its fields, and how it relates to other objects

 
posthttps://api.zaius.com/v3/schema/objects

Body Params

name
string
required

lower snake case, alphanumeric, must start with alpha character. must be unique within the schema across both other object's name and aliases. should be plural

display_name
string
required

user-friendly name for object. must be unique across all object display names within the schema

alias
string

alias for the object that can be used during ingest. should be the singular form of the name field. must be unique across all object names and aliases within the schmea

fields
object
fields.name
string
required

the name of the field

fields.type
string
required

the type of the field: number, timestamp, text, boolean

fields.display_name
string
required

the user-friendly name used within Zaius

fields.primary
boolean
required

marks the field as primary

relations
object
relations.name
string

name for the relation

relations.display_name
string

user-friendly name shown within Zaius

relations.child_object
string

object that the relation points to

relations.join_fields
object
relations.join_fields.parent
string

the field name on this object

relations.join_fields.child
string

the related field (primary) on another object

{
  "name": "objects",
  "display_name": "Object",
  "alias": "object",
  "fields": [
    {
      "name": "object_id",
      "display_name": "New Object Identifier",
      "type": "string",
      "primary": true
    },{
      "name": "another_field",
      "display_name": "Another Fields",
      "type": "string"
    },{
      "name": "child_id",
      "display_name": "Child Identifier",
      "type": "number"
    }
  ],
  "relations": [
    {
      "name": "my_relation",
      "display_name": "My Relationship",
      "child_object": "child",
      "join_fields": [{
        "parent": "child_id",
        "child": "child_id"
      }]
    }
  ]
}
curl --request POST \
  --url https://api.zaius.com/v3/schema/objects
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.zaius.com/v3/schema/objects' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.zaius.com/v3/schema/objects")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.zaius.com/v3/schema/objects");

xhr.send(data);
import requests

url = "https://api.zaius.com/v3/schema/objects"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "name": "objects",
  "display_name": "Object",
  "alias": "object",
  "fields": [
    {
      "name": "object_id",
      "display_name": "New Object Identifier",
      "type": "string",
      "primary": true
    },{
      "name": "another_field",
      "display_name": "Another Fields",
      "type": "string"
    },{
      "name": "child_id",
      "display_name": "Child Identifier",
      "type": "number"
    }
  ],
  "relations": [
    {
      "name": "my_relation",
      "display_name": "My Relationship",
      "child_object": "child",
      "join_fields": [{
        "parent": "child_id",
        "child": "child_id"
      }]
    }
  ]
}
{
  "title": "Bad Request",
  "status": 400,
  "timestamp": "2018-08-07T13:44:17.659Z",
  "detail": {
    "invalids": [
      {
        "field": "name",
        "reason": "already used by another object"
      },
      {
        "field": "alias",
        "reason": "already used by another object"
      },
      {
        "field": "display_name",
        "reason": "already used by another object"
      },
      {
        "field": "fields",
        "reason": "at least one primary key field required"
      },
      {
        "field": "relations[0].child_object",
        "reason": "does not exist"
      }
    ]
  }
}
 
Suggest Edits

List Objects

Get a list of all objects and their associated fields within Zaius

 
gethttps://api.zaius.com/v3/schema/objects
 
curl --request GET \
  --url https://api.zaius.com/v3/schema/objects
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.zaius.com/v3/schema/objects' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.zaius.com/v3/schema/objects")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.zaius.com/v3/schema/objects");

xhr.send(data);
import requests

url = "https://api.zaius.com/v3/schema/objects"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

[
  {
    "name": "tickets",
    "display_name": "Tickets",
    "alias": "ticket",
    "fields": [
      {
        "name": "field_name",
        "type": "number",
        "display_name": "Display Name",
        "primary": true
      }
    ],
    "relations": [
      {
        "name": "my_relation",
        "display_name": "My Relationship",
        "child_object": "target_object_name",
        "join_fields": [
          {
            "parent": "child_id",
            "child": "child_id"
          }
        ]
      }
    ]
  },
  {
    "name": "concerts",
    "display_name": "Concerts",
    "alias": "concert",
    "fields": [
      {
        "name": "field_name",
        "type": "number",
        "display_name": "Display Name",
        "primary": true
      }
    ],
    "relations": [
      {
        "name": "my_relation",
        "display_name": "My Relationship",
        "child_object": "target_object_name",
        "join_fields": [
          {
            "parent": "child_id",
            "child": "child_id"
          }
        ]
      }
    ]
  }
]
 
Suggest Edits

Get Object

Get a specific object and its associated fields within Zaius

 
gethttps://api.zaius.com/v3/schema/objects/object_name

Path Params

object_name
string
required

the name of the object to view

 
curl --request GET \
  --url https://api.zaius.com/v3/schema/objects/object_name
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.zaius.com/v3/schema/objects/object_name' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.zaius.com/v3/schema/objects/object_name")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.zaius.com/v3/schema/objects/object_name");

xhr.send(data);
import requests

url = "https://api.zaius.com/v3/schema/objects/object_name"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "name": "tickets",
  "display_name": "Tickets",
  "alias": "ticket",
  "fields": [{
  	"name": "field_name",
  	"type": "number",
  	"display_name": "Display Name",
    "created_by" "account",
  	"primary": true
   }],
  "relations": [{
  	"name": "my_relation",
  	"display_name": "My Relationship",
  	"child_object": "target_object_name",
  	"join_fields": [{
    	"parent": "child_id",
    	"child": "child_id"
   	}]
   }]
}
{
  "title": "Not Found",
  "status": 404,
  "timestamp": "2018-08-07T12:42:27.281Z",
  "detail": {
    "message": "Unable to locate object does_not_exist"
  }
}
 
{
  "name": "field_name",
  "type": "number",
  "auto": true,
  "display_name": "Display Name",
  "description": "Description of field",
  "created_by": "zaius",
  "primary_key": true
}
property
description

name

name of the field

type

field data type. options are number, timestamp, text, boolean

auto

(read only) marks the field as one that is auto populated by Zaius

display_name

the user-friendly name used within Zaius

description

description of the field

created_by

(read only) specifies what/who created the field. current values as zaius and account

primary_key (optional)

marks the field as identifying for the containing object. only allowed during object creation.

 
Suggest Edits

Create Field

Create new fields on an Object within Zaius

 
posthttps://api.zaius.com/v3/schema/objects/object_name/fields

Path Params

object_name
string
required

The name of the owning object

Body Params

name
string
required

the name of the field. lower snake case, alphanumeric, must start with alpha character. must be unique across all field names within the object.

type
string
required

the type of the field: number, timestamp, text, boolean

display_name
string
required

the user-friendly name used within Zaius. must be unique across all display names within the object.

description
string

description of the field, referenced in the UI

{
  "fields": [{
  	"name": "field_name",
  	"type": "number",
  	"display_name": "Display Name",
  	"primary_key": true
   },{
  	"name": "field_name_2",
  	"type": "string",
  	"display_name": "Display Name 2",
  	"primary_key": false
   }]
}
curl --request POST \
  --url https://api.zaius.com/v3/schema/objects/object_name/fields
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.zaius.com/v3/schema/objects/object_name/fields' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.zaius.com/v3/schema/objects/object_name/fields")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.zaius.com/v3/schema/objects/object_name/fields");

xhr.send(data);
import requests

url = "https://api.zaius.com/v3/schema/objects/object_name/fields"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "name": "and_another_field",
  "display_name": "And Another Field",
  "type": "string"
}
{
  "title": "Bad Request",
  "status": 400,
  "timestamp": "2018-08-07T13:50:10.017Z",
  "detail": {
    "invalids": [
      {
        "field": "name",
        "reason": "must not be blank"
      },
      {
        "field": "type",
        "reason": "must be supported type"
      },
      {
        "field": "display_name",
        "reason": "must not be blank"
      }
    ]
  }
}
{
  "title": "Not Found",
  "status": 404,
  "timestamp": "2018-08-07T13:51:25.937Z",
  "detail": {
    "message": "Unable to locate object does_not_exist"
  }
}
 
Suggest Edits

List Object Fields

Get the fields on a given object

 
gethttps://api.zaius.com/v3/schema/objects/object_name/fields

Path Params

object_name
string
required

the name of the owning object

 
curl --request GET \
  --url https://api.zaius.com/v3/schema/objects/object_name/fields
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.zaius.com/v3/schema/objects/object_name/fields' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.zaius.com/v3/schema/objects/object_name/fields")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.zaius.com/v3/schema/objects/object_name/fields");

xhr.send(data);
import requests

url = "https://api.zaius.com/v3/schema/objects/object_name/fields"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

[
  {
    "name": "object_id",
    "display_name": "New Object Identifier",
    "type": "string",
    "created_by" "account",
    "primary": true
  },
  {
    "name": "another_field",
    "display_name": "Another Fields",
    "type": "string",
    "created_by" "account"
  },
  {
    "name": "child_id",
    "display_name": "Child Identifier",
    "type": "number",
    "created_by" "account"
  }
]
{
  "title": "Not Found",
  "status": 404,
  "timestamp": "2018-08-07T13:47:02.052Z",
  "detail": {
    "message": "Unable to locate object obects"
  }
}
 
Suggest Edits

Get Object Field

Get the fields on a given object

 
gethttps://api.zaius.com/v3/schema/objects/object_name/fields/field_name

Path Params

object_name
string
required

the name of the owning object

field_name
string
required

the name of the field to return

 
curl --request GET \
  --url https://api.zaius.com/v3/schema/objects/object_name/fields/field_name
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.zaius.com/v3/schema/objects/object_name/fields/field_name' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.zaius.com/v3/schema/objects/object_name/fields/field_name")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.zaius.com/v3/schema/objects/object_name/fields/field_name");

xhr.send(data);
import requests

url = "https://api.zaius.com/v3/schema/objects/object_name/fields/field_name"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  	"name": "field_name",
  	"type": "number",
  	"display_name": "Display Name",
  	"auto": true,
  	"description": "The venue that the user visisted.",
    "created_by" "zaius",
}
{
  "title": "Not Found",
  "status": 404,
  "timestamp": "2018-08-07T12:44:53.729Z",
  "detail": {
    "message": "Unable to locate field object.does_not_exist"
  }
}
 
Suggest Edits

Relationships

 

Representation describing a relationship between two objects. The Object containing the Relation definition is the parent object.

{
  "name": "relation_name",
  "display_name": "Relation Display Name",
  "child_object": "child_object_name",
  "join_fields": [{
    "parent": "child_id",
    "child": "child_id"
  }]
}
field
description

name

name for the relation

display_name

user-friendly name shown within Zaius

child_object

child Object name

join_fields

collection of parent child pairs. parent is the field name (foreign key) on the owning Object and child is the related Objects primary key. Multiple are allowed to support objects with compound primary keys.

 
Suggest Edits

Create Relationship

Create a new relation between Objects within Zaius

 
posthttps://api.zaius.com/v3/schema/objects/object_name/relations

Path Params

object_name
string
required

The name of the owning object

Body Params

relations
object
relations.name
string

name for the relation

relations.display_name
string

user-friendly name shown within Zaius

relations.object
string

object which owns this relation

relations.join_fields
object
relations.join_fields.source
string

the field name on this object

relations.join_fields.target
string

the related field on another object

{
  "name": "my_relation",
  "display_name": "My Relationship",
  "child_object": "child",
  "join_fields": [{
    "parent": "child_id",
    "child": "child_id"
  }]
}
curl --request POST \
  --url https://api.zaius.com/v3/schema/objects/object_name/relations
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.zaius.com/v3/schema/objects/object_name/relations' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.zaius.com/v3/schema/objects/object_name/relations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.zaius.com/v3/schema/objects/object_name/relations");

xhr.send(data);
import requests

url = "https://api.zaius.com/v3/schema/objects/object_name/relations"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "name": "my_relation",
  "display_name": "My Relationship",
  "child_object": "child",
  "join_fields": [{
    "parent": "child_id",
    "child": "child_id"
  }]
}
{
  "title": "Bad Request",
  "status": 400,
  "timestamp": "2018-08-14T12:23:04.500Z",
  "detail": {
    "invalids": [
      {
        "field": "join_fields[0].parent",
        "reason": "does not match child data type"
      }
    ]
  }
}
 
Suggest Edits

List Object Relationships

Get a specific object and its associated fields within Zaius

 
gethttps://api.zaius.com/v3/schema/objects/object_name/relations

Path Params

object_name
string
required

the name of the owning object

 
curl --request GET \
  --url https://api.zaius.com/v3/schema/objects/object_name/relations
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.zaius.com/v3/schema/objects/object_name/relations' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.zaius.com/v3/schema/objects/object_name/relations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.zaius.com/v3/schema/objects/object_name/relations");

xhr.send(data);
import requests

url = "https://api.zaius.com/v3/schema/objects/object_name/relations"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

[
  {
    "name": "my_relation",
    "display_name": "My Relationship",
    "child_object": "child",
    "join_fields": [{
      "parent": "child_id",
      "child": "child_id"
    }]
  }
]
 
Suggest Edits

Get Relationship

Get a specific object and its associated fields within Zaius

 
gethttps://api.zaius.com/v3/schema/objects/object_name/relations/relation_name

Path Params

object_name
string
required

the name of the owning object

relation_name
string
required

the name of the relation

 
curl --request GET \
  --url https://api.zaius.com/v3/schema/objects/object_name/relations/relation_name
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.zaius.com/v3/schema/objects/object_name/relations/relation_name' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.zaius.com/v3/schema/objects/object_name/relations/relation_name")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.zaius.com/v3/schema/objects/object_name/relations/relation_name");

xhr.send(data);
import requests

url = "https://api.zaius.com/v3/schema/objects/object_name/relations/relation_name"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "name": "my_relation",
  "display_name": "My Relationship",
  "child_object": "target_object_name",
  "join_fields": [{
    "parent": "child_id",
    "child": "child_id"
  }]
}
{
  "title": "Not Found",
  "status": 404,
  "timestamp": "2018-08-07T12:47:51.954Z",
  "detail": {
    "message": "Unable to locate relation events.does_not_exist"
  }
}
 
Suggest Edits

Compliance Opt-Out

For a given identifier, find all known associated identifiers, redact relevant profiles, stop new updates to user's profile and don't send messages in the future to the user.

 
posthttps://api.zaius.com/v3/optout

Body Params

requester
string
required

The email of the user requesting the optout on behalf of the data subject (not the data subject themselves). Utilized for audit purposes

email
string

the email of the user to opt-out

phone
string

the phone number of the user to opt-out

vuid
string

the cookie (known as vuid to Zaius) to opt-out

If you're trying to opt-out users from a list or a specific channel, do not use this API.

Utilize the List API for managing a typical communication based opt-outs.

Utilize this API for compliance based opt-outs (e.g. GDPR).

This API takes all identifiers provided to it, finds other identifiers that we know that are associated with the same user and adds them to our "opt-out" pool. Then we redact the customer record for that user. All new events and object updates that come in associated with that user will persist, but will be associated with the redacted profile.

Phone numbers must match exactly what was provided previously to Zaius

Zaius stores phone numbers as strings and does not transform them after ingest. Phone numbers in this request must match what was initially uploaded to Zaius.

curl --request POST \
  --url https://api.zaius.com/v3/optout
var request = require("request");

var options = { method: 'POST', url: 'https://api.zaius.com/v3/optout' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.zaius.com/v3/optout")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.zaius.com/v3/optout");

xhr.send(data);
import requests

url = "https://api.zaius.com/v3/optout"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "title": "Bad Request",
  "status": 400,
  "timestamp": "2018-04-16T18:19:43.742Z",
  "detail": {
    "invalids": [
      {
        "field": "email",
        "reason": "Either phone or vuid is required when email is not provided."
      },
      {
        "field": "requester",
        "reason": "must not be empty"
      }
    ]
  }
}
 
Suggest Edits

Getting Started

This page will help you get started with Zaius API.

 

This is where you show your users how to set it up. You can use code samples, like this:

$http.post('/someUrl', data).success(successCallback);

alert('test');

Try dragging a block from the right to see how easy it is to add more content!

 
Suggest Edits

Getting Started

This page will help you get started with Identifier API.

 

This is where you show your users how to set it up. You can use code samples, like this:

$http.post('/someUrl', data).success(successCallback);

alert('test');

Try dragging a block from the right to see how easy it is to add more content!