Skip to content

01 Getting Started

joelrose2 edited this page Nov 21, 2019 · 12 revisions

Welcome to the Convizit API

This REST API is used to retrieve the granular website visitor activity data, that is automatically captured and tagged by Convizit, in order to use it in your own systems; to manage the defined website projects being used with Convizit; and to create and manage visitor activity triggers for which Convizit will send notifications to your system, via webhooks, when those triggers have been activated by visitor actions.

This page contains:

Essential Usage Points

It is imperative to implement the following points when calling the API, to ensure successful results:

Base URI

Every function in the API is called by appending its function cateory and function name to the following base URI: https://api.convizit.com (example: https://api.convizit.com/activity/getevents).

Content-Type

Every function call must include the following key:value pair in the header section of the request:

   Content-Type: application/json

If this Content-Type parameter is omitted from the header, some requests will not be properly processed (e.g., filters will be ignored).

Session Authentication Token

Every call to the API requires the use of a per-session authentication token. The token is obtained by calling the Authorize function before calling any other function during a particular session. The returned token must be included in the header of every subsequent call to the API. For example:

   X-Auth-Token: WZNPVf0JlDSeNNl_t28Q6cKEQ3
   Accept: application/json
   Content-Type: application/json

The received authentication token remains valid for 20 minutes from the last time any API function was called using it. The Authorize function should only be called again if 20 minutes have elapsed since the last call to the API; otherwise, the authentication token received previously remains valid. As a best practice, the Authorize function should only be called in the event that any other function call returns an HTTP error 403 (unauthorized).


Functions Overview

Following is a summary of all available functions. Click a category name or function name to jump directly to the relevant documentation.

General Functions

  • Authorize – Log in to the API and receive an X-Auth-Token that will allow calling all the other functions.

  • AddWebsite – Create a new website project that will receive data from a particular website.

  • UpdateWebsite – Change the base URL, username and/or password for an existing website project.

  • DeleteWebsite – Delete an existing website project.

  • GetWebsites – Retrieve the details of defined website projects.

Visitor Activity Data Functions

  • GetElements – Retrieve the details of the page elements with which visitors have interacted in the current website.

  • GetPages – Retrieve the URLs and HTML titles of pages viewed by visitors in the current website.

  • GetEvents – Retrieve the details of visitor interactions with page elements for the current website.

  • GetPageviews – Retrieve the details of visitor pageviews that have occurred in the current website.

  • GetSessions – Retrieve the details of visitor sessions that have occurred in the current website.

Trigger Rule Functions

  • SetListener – Set the URL of the webhooks listener for a particular website project.

  • AddTriggerRule – Create a new visitor activity rule that will trigger webhook notifications.

  • UpdateTriggerRule – Update an existing visitor activity trigger rule.

  • DeleteTriggerRule – Delete an existing visitor activity trigger rule.

  • GetTriggerRules – Retrieve the details of defined visitor activity trigger rules.

  • GetTriggerRuleStats – Retrieve statistics of trigger rules that have been triggered by visitor activity.

  • GetNotifications – Retrieve the details of trigger rules that have been triggered by visitor activity.


Data Types

All values passed to/from the API are of one of the following data types:

Data Type Description
string A string of alphanumeric characters
number A numeric value
boolean true or false
timestamp A date and time specified as a Unix epoch time (in UTC unless noted otherwise)
array A one- or two-dimensional JSON array
object A JSON object containing one or more key/value pairs

Note: As per the REST API standard, all field names and values (except numeric and boolean values) are enclosed in double quotation marks (").


Comparison Operators

Some functions contain request parameters that will filter the results returned by the function. These parameters can receive a "comparison operator" and a value to match.

Notes:

  • If only a literal value is included, without a comparison operator, then the default "equals" operator is assumed.
  • String comparison operations are case sentitive.
  • Numeric operators will only filter named tags that contain numeric values; this is relevant only for the functions GetElements and GetEvents.
  • The syntax in which comparison operators are used in a function Request is:
    • Syntax: "paramName": {"operator": "value"}
    • Example: "elementName": {"startswith": "Add"}
  • The syntax in which comparison operators are used in a function Request specifying a named tag value is:
    • Syntax: "namedTag":[{"name": "paramName", "value": {"operator": "value"}}]
    • Example: "namedTag":[{"name": "price", "value": {"gt": 100}}]
  • If Content-Type: application/json is not included in the request header (read more), results filtering will not function.

The following string and numeric comparison operators may be used in these request parameters:

String Comparison Operators

Comparison Operator Description
equals Returns elements that exactly match the specified string value – this is the default comparison operator assumed, if one is not specified.
startswith Returns elements that begin with the same characters as in the specified string value.
endswith Returns elements that end with the same characters as in the specified string value.
contains Returns elements that contain, anywhere within the name, the specified string value.
regex Returns elements that match the specified regular expression.

Numeric Comparison Operators

Comparison Operator Description
equals Returns named tags with the exact numeric value specified.
notequals Returns named tags with any numeric value other than the one specified.
gt Returns named tags with numeric values greater than the one specified.
lt Returns named tags with numeric values less than the one specified.
gte Returns named tags with numeric values greater than or equal to the one specified.
lte Returns named tags with numeric values less than or equal to the one specified.

Function Response Codes

Besides any data that may be returned in a function's response, every function returns an HTTP response code indicating whether the function call was successful or if an error occurred. The following are the possible HTTP response codes returned:

HTTP Response Code Description
200 OK: The function call was successful.
400 Bad request: The function call was invalid.
403 Forbidden: The function call was not authorized.
404 Not found: The function name was not recognized.
500 Internal Server Error: The function call was valid, but a problem occurred.

Response Paging

By default, all functions that use the GET HTTP method will return 10,000 records (the default page size) in any response (assuming there are at least 10,000 records to return). To request a smaller or larger page size, append the input parameter $pagesize=n where n is the number of records to return. The maximum supported page size is 200,000.

To request subsequent pages of results, repeat the request with the additional parameter $skip=n where n is the number of resulting records of the entire result set to skip over when returning the current page.

The $pagesize and $skip parameters may be added to any function request.

Examples

The following request will return the first 10,000 records (assuming there are at least 10,000 records to return):

https://api.convizit.com/activity/GetElements?startTime=1514764800&endTime=1546300799

The following request will return the next 10,000 records, i.e., the second page:

https://api.convizit.com/activity/GetElements?startTime=1514764800&endTime=1546300799&$skip=10000

The following two requests will (a) return the first 100,000 records, and (b) return the second page consisting of an additional 100,000 records:

https://api.convizit.com/activity/GetElements?startTime=1514764800&endTime=1546300799&pagesize=100000

https://api.convizit.com/activity/GetElements?startTime=1514764800&endTime=1546300799&pagesize=100000&$skip=100000

You can’t perform that action at this time.