Introduction to Toovio API

Welcome to the Toovio API!

Purpose

The purpose of Toovio is to provide clients with an intelligent decisioning tool that leverages advance modeling while doing so within a simplified programtic guided approach. Toovio does not intregate into an output channel, rather it returns a list of customer available to action against and how to treat them.

Setup

To start leveraging Toovio decisions you must setup a client account. This client account allows Toovio to begin the work on setting you up with your own toovio.com domain as well as your client credentials (required to access any Toovio API).

Transactions

Toovio requires data to do it's decisioning and advance modelling. The type of data we find most valuable is transactional data. Transactional data is any data feed that documents customer behavior (i.e. point of sales, customer activity, etc..). Typically this data is time keyed. Toovio typically takes in transactional data from multiple sources.

Experiment

Within Toovio, a experiment is a decision that a client wants to take against a customer (i.e. upsell, churn, purchase a product, etc...) and how we define success. A experiment contains the rules / logic to determine qualifying customers and associated variant. You can further define the purpose or type of experiment (i.e. Next Best Time, Next Best Channel, etc...) as well as group experiments to return the result of multiple experiments within a single decision.

Variant

Within Toovio, variants are associated to experiments. A variant is the result of an experiment decision, this could be an offer, outcome, next best time, next best channel, etc...

Conversions

Converions are an important metric tracked against experiments. Conversions represent the successful action against a experiment (i.e. customer purchased a product, customer bought an additional service).

Predictive Models

Toovio leverages advanced predictive models to predicte customer behavior. Models can be build manually or managed automatically by Toovio by defining the beahvior audience.

Step 1. credentials

Once your Toovio account is processed you need an API key and 3 other key attributes to begin using our APIs. Once you’ve received your keys and endpoints, you’re ready to roll.

Keys

Parameter	Description
CLIENT_ID	Unique client identifier
API_KEY	Unique Application Access Key
ENDPOINT_URL	The url of the target AudienceFlume endpoint (e.g. https://xyz.toovio.com)

Step 2. authenticate

Clients are authenticated using a combination of their CLIENT_ID and API_KEY against their unique ENDPOINT_URL.

See the panel on the right on how to authenticate via: Shell, Python and Java

Step 3. transactions APIs

Define transaction

Defination

POST https://ENPOINT_URL/api/v1/transactions

curl "https://ENPOINT_URL/api/v1/transactions" \
    -H 'Authorization: Bearer test_api_token' \
    -H 'content-type: application/json' \
    -X POST
    -d '{
          "name" : "pos",
          "file_name" : "trans_pos",
          "fields" : [
            {
              "name": "field1",
              "type": "String",
              "description": "Field1 description",
              "format":""
            },
            {
              "name": "field2",
              "type": "Int",
              "description": "Field2 description",
              "format":""
            },
            {
              "name": "field3",
              "type": "Date",
              "description": "Field3 description",
              "format":"mm/dd/yyyy"
            }
          ]
      }'

Response

{
  "status": "Success",
  "errors": ""
}

Using the transactions API, clients define their transactional files to Toovio.

POST

HTTP Request /transactions

Responses

Code	Description
200	200 response

Pass transactions

Defination

PUT https://ENPOINT_URL/api/v1/transactions

curl "https://ENPOINT_URL/api/v1/transactions" \
    -F ‘data=@path/transaction_pos.csv’ \
    -H 'Authorization: Bearer test_api_token' \
    -H 'content-type: application/json' \
    -X PUT
    -d '{
          "type" : "transactions_pos",
          "date" : "yyyy/mm/dd"
      }'

Response

{
  "status": "Success",
  "errors": ""
}

Using the transaction API, clients can upload their transactional files to Toovio.

PUT

HTTP Request /transactions

Responses

Code	Description
200	200 response

List transactions

Defination

GET https://ENPOINT_URL/api/v1/transactions/{transaction_name}

curl "https://ENPOINT_URL/api/v1/transactions/{transaction_name}" \
    -H 'Authorization: Bearer test_api_token' \
    -X GET

Response

{
    "data": [
        {
            "name": "pos",
            "file_name": "trans_pos",
            "fields": [
                {
                    "name": "field1",
                    "type": "String",
                    "description": "Field1 description",
                    "format": ""
                },
                {
                    "name": "field2",
                    "type": "Int",
                    "description": "Field2 description",
                    "format": ""
                },
                {
                    "name": "field3",
                    "type": "Date",
                    "description": "Field3 description",
                    "format": "mm/dd/yyyy"
                }
            ]
        }.
        {
            "name": "views",
            "file_name": "trans_view",
            "fields": [
                {
                    "name": "field1",
                    "type": "String",
                    "description": "Field1 description",
                    "format": ""
                },
                {
                    "name": "field2",
                    "type": "Int",
                    "description": "Field2 description",
                    "format": ""
                },
                {
                    "name": "field3",
                    "type": "Date",
                    "description": "Field3 description",
                    "format": "mm/dd/yyyy"
                }
            ]
        }
    ],
    "status": "Success",
    "errors": ""
}

List all configured transaction files.

GET

HTTP Request /transactions/{transaction_name}

Responses

Code	Description
200	200 response

Step 4. create predictive model

Defination

PUT https://ENPOINT_URL/api/v1/models

curl "https://ENPOINT_URL/api/v1/models" \
    -F ‘data=@path/customer_list.csv’ \
    -H 'Authorization: Bearer test_api_token' \
    -d '{
          "name" : "model_name"
      }'

Response

{
  "build_version": 1,
  "status": "Success",
  "errors": ""
}

A Toovio predictive model can be built using the model API. The audience can be deined against transaction data sources or provided within the API body. The loaded customer list csv file is a collection of customers who match the models expected behavior (the 1s) and a list of customers who don't meet the expected behavior (the 0s).

PUT

HTTP Request /models

Responses

Code	Description
200	200 response

Step 5. varient APIs

Create varient

Defination

POST https://ENPOINT_URL/api/v1/varients

curl "https://ENPOINT_URL/api/v1/varients" \
    -H 'Authorization: Bearer test_api_token' \
    -H 'content-type: application/json' \
    -X POST
    -d '{
          "name" : "varient1",
          "code" : "varient_code1",
          "category" : "varient_category",
          "message" : "varient message"
          "rules" : [
            {
              "transaction" : "trans_name1",
              "field" : "field1",
              "formula": "gt {value}"
            },
            {
              "transaction" : "trans_name1",
              "field" : "field2",
              "formula": "eq {value}"
            },
            {
              "transaction" : "trans_name1",
              "field" : "field3",
              "formula": "lt {value}"
            }
          ]
      }'

Response

{
  "experiment_id": 27,
  "status": "Success",
  "errors": ""
}

A Toovio varient defines a outcome, message or offer that can be assigned to experiments. Toovio varients have propensity models automatically associated. Additionally Toovio varients can have eligibility rules that can determine presentation.

POST

HTTP Request /varients

Parameters

Name	Located in	Description	Required	Type	Example
name	body	unique varient name	yes	string	varient1
code	body	unique varient identifier	yes	string	varient1
category	body	varient category	yes	string	category1
message	body	varient output message	yes	string
rules	body array	array list of variant rules	no	string
rules:transaction	fields	source transaction	no	string
rules:field	fields	transaction field	no	string
rules:formula	fields	formula	no	string

Responses

Code	Description
200	200 response
400	400 Experiment not configured (check response errors value)

List varients

Defination

GET https://ENPOINT_URL/api/v1/varients/{varient_name}

curl "https://ENPOINT_URL/api/v1/varients/{varient_name}" \
    -H 'Authorization: Bearer test_api_token' \
    -X GET

Response

{
    "data": [
    {
      "name" : "varient1",
      "code" : "varient_code1",
      "category" : "varient_category",
      "message" : "varient message"
      "rules" : [
        {
          "transaction" : "trans_name1",
          "field" : "field1",
          "formula": "gt {value}"
        },
        {
          "transaction" : "trans_name1",
          "field" : "field2",
          "formula": "eq {value}"
        },
        {
          "transaction" : "trans_name1",
          "field" : "field3",
          "formula": "lt {value}"
        }
      ]
    },
    {
      "name" : "varient2",
      "code" : "varient_code2",
      "category" : "varient_category",
      "message" : "varient message"
      "rules" : [
        {
          "transaction" : "trans_name1",
          "field" : "field1",
          "formula": "gt {value}"
        },
        {
          "transaction" : "trans_name1",
          "field" : "field2",
          "formula": "eq {value}"
        },
        {
          "transaction" : "trans_name1",
          "field" : "field3",
          "formula": "lt {value}"
        }
      ]
    }
    ],
    "status": "Success",
    "errors": ""
}

Use the varient list API to return a list of your Toovio varients and meta data.

GET

HTTP Request /varients

Responses

Code	Description
200	200 response

Step 6. experiment APIs

Create experiment

Defination

POST https://ENPOINT_URL/api/v1/experiments

curl "https://ENPOINT_URL/api/v1/experiments" \
    -H 'Authorization: Bearer test_api_token' \
    -H 'content-type: application/json' \
    -X POST
    -d '{
          "name" : "experiment1",
          "type" : "NBC",
          "model": "model_name",
          "variants" : [
            "variant_id1",
            "variant_id2"
          ]
      }'

Response

{
  "experiment_id": 27,
  "status": "Success",
  "errors": ""
}

A Toovio experiment defines an audience to receive an action. Toovio expeiremnts are made up of variants which use propensity for weighting.

POST

HTTP Request /experiments

Parameters

Name	Located in	Description	Required	Type	Example
name	body	unique experiment name	yes	string	experiment1
type	body	experiment type (i.e. Next Best Channel, Next Best Time, Varient, etc...)	yes	string	NBC
model	body	propensity of the customer to qualify for the experiment	no	string	model_name
variants	array	array list of variants	no	string	model_name
variant_id	id	variant id	no	string	model_name

Responses

Code	Description
200	200 response
400	400 Experiment not configured (check response errors value)

Enable experiment

Defination

PATCH https://ENPOINT_URL/api/v1/experiments/{experiment_name}?enabled={true/false}

curl "https://ENPOINT_URL/api/v1/experiments/{experiment_name}?enabled=true" \
    -H 'Authorization: Bearer test_api_token' \
    -X PATCH

Response

{
  "name": "experiment1",
  "type": "NBC",
  "model": "model_name",
  "enabled": true,
  "status": "Success",
  "errors": ""
}

A Toovio experiment must be enabled to start decisioning. To enable / disable Toovio experiments, use the experiments PATCH API.

PATCH

HTTP Request /experiments

Parameters

Name	Located in	Description	Required	Type	Format	Example
name	body	unique transaction name	yes	string		pos
enable	fields	transaction fields	yes	string

Responses

Code	Description
200	200 response
400	400 Experiment not configured (check response errors value)

List experiment

Defination

GET https://ENPOINT_URL/api/v1/experiments/{experiment_name}

curl "https://ENPOINT_URL/api/v1/experiments/{experiment_name}" \
    -H 'Authorization: Bearer test_api_token' \
    -X GET

Response

{
    "data": [
        {
            "name": "experiment1",
            "type": "NBC",
            "model": "model_name",
      "enabled": true
        }.
        {
            "name": "experiment2",
            "type": "NBT",
            "model": "",
      "enabled": false
        }
    ],
    "status": "Success",
    "errors": ""
}

Use the experiment list API to return a list of your Toovio experiments and status / meta data.

GET

HTTP Request /experiments

Responses

Code	Description
200	200 response

Group experiments

Defination

POST https://ENPOINT_URL/api/v1/experiments_group

curl "https://ENPOINT_URL/api/v1/experiments_group" \
    -H 'Authorization: Bearer test_api_token' \
    -H 'content-type: application/json' \
    -X POST
    -d '{
          "group_name" : "experiment_group1",
          "description" : "experiment_group description",
          "experiments" : [
            "experiment_id1",
            "experiment_id2"
          ]
      }'

Response

{
  "experiment_group_id": 5,
  "status": "Success",
  "errors": ""
}

Toovio experiments can be grouped to allow multiple experiments to be be executed within a single decisioning call. Using the experiments_group API you can group multiple experiments.

POST

HTTP Request /experiments_group

Parameters

Name	Located in	Description	Required	Type	Example
group_name	body	experiemnt group name	yes	string	experiment1
description	body	experiment group description	yes	string	NBC
experiments	array	array of experiment ids	no	string	model_name
experiment_id	array value	experiment id	no	string	model_name

Responses

Code	Description
200	200 response
400	400 Experiment not configured (check response errors value)

Step 7. Conversions APIs

Define conversions

Defination

POST https://ENPOINT_URL/api/v1/define_conversions

curl "https://ENPOINT_URL/api/v1/define_conversions" \
    -H 'Authorization: Bearer test_api_token' \
    -H 'content-type: application/json' \
    -X POST
    -d '{
          "name" : "conversion_name",
          "experiment" : "experiment_name",
          "value" : 10,
          "params" : [
            {
              "transaction" : "trans_name1",
              "field" : "field1",
              "formula": "gt {value}"
            },
            {
              "transaction" : "trans_name1",
              "field" : "field2",
              "formula": "eq {value}"
            },
            {
              "transaction" : "trans_name1",
              "field" : "field3",
              "formula": "lt {value}"
            }
          ]
      }'

Response

{
  "status": "Success",
  "errors": ""
}

If Toovio has the requried transactions, clients can have Toovio calculate conversions for them. Using the conversions API, clients can (by referencing existing transactions) define conversions (against a experiment). Toovio will (nightly) build up conversions against experiments. Note, conversions are calcaulted against a 30 day after experiment presentation period.

POST

HTTP Request /define_conversions

Parameters

Name	Located in	Description	Required	Type
name	body	unique conversion name	yes	string
experiment	body	target experiment	yes	string
value	body	dollar value of the conversion	yes	string
params	body array	transaction fields	yes	array
params:transaction	fields	source transaction	yes	string
params:field	fields	transaction field	yes	string
params:formula	fields	formula	yes	string

Responses

Code	Description
200	200 response
400	400 Experiment not configured (check response errors value)

List defined conversions

Defination

GET https://ENPOINT_URL/api/v1/define_conversions/{conversion_name}

curl "https://ENPOINT_URL/api/v1/define_conversions/{conversion_name}" \
    -H 'Authorization: Bearer test_api_token' \
    -X GET

Response

{
  "data": [
    {
      "name": "conversion_name",
      "experiment": "experiment_name",
      "value": 10,
      "params": [
        {
          "transaction": "trans_name1",
          "field": "field1",
          "formula": "gt {value}"
        },
        {
          "transaction": "trans_name1",
          "field": "field2",
          "formula": "eq {value}"
        },
        {
          "transaction": "trans_name1",
          "field": "field3",
          "formula": "lt {value}"
        }
      ]
    },
    {
      "name": "conversion_name 2",
      "experiment": "experiment_name",
      "value": 15,
      "params": [
        {
          "transaction": "trans_name1",
          "field": "field1",
          "formula": "gt {value}"
        },
        {
          "transaction": "trans_name1",
          "field": "field2",
          "formula": "eq {value}"
        },
        {
          "transaction": "trans_name1",
          "field": "field3",
          "formula": "lt {value}"
        }
      ]
    }
  ],
  "status": "Success",
  "errors": ""
}

List all defined conversion.

GET

HTTP Request /define_conversions/{conversion_name}

Responses

Code	Description
200	200 response

Pass conversions

Defination

PUT https://ENPOINT_URL/api/v1/conversions

curl "https://ENPOINT_URL/api/v1/conversions" \
    -F ‘data=@path/conversions_file.csv’ \
    -H 'Authorization: Bearer test_api_token' \
    -H 'content-type: application/json' \
    -X PUT'

Response

{
  "status": "Success",
  "errors": ""
}

Optional. If conversions are not calcualted by Toovio, clients can load conversions into Toovio via the conversions API or loaded via the Toovio SFTP. The file should be a csv with the following columns.

File contents

Name	Description
customer_id	customer identifier
experiment	experiment identifier
conversion date/time	date / time of the conversion
conversion value	dollar value of the conversion

POST

HTTP Request /conversions

Responses

Code	Description
200	200 response
400	400 Experiment not configured (check response errors value)

List conversions

Defination

GET https://ENPOINT_URL/api/v1/conversions/{experiment_id}?conversion_date={conversion_date}

curl "https://ENPOINT_URL/api/v1/conversions/{experiment_id}?conversion_date={conversion_date}" \
    -H 'Authorization: Bearer test_api_token' \
    -X GET

Response

{
  "data": [
    {
      "customer_id": "customer_id1",
      "experiment_id": "experiment_id",
      "value": 10,
      "date": "yyyy/mm/dd hh:mm:ss"
    },
    {
      "customer_id": "customer_id2",
      "experiment_id": "experiment_id",
      "value": 15,
      "date": "yyyy/mm/dd hh:mm:ss"
    }
  ],
  "status": "Success",
  "errors": ""
}

List all conversion for a specific date.

GET

HTTP Request /conversions/{conversion_name}?conversion_date={conversion_date}

Responses

Code	Description
200	200 response

Step 8. receive results

Defination

GET https://ENPOINT_URL/api/v1/results?date={date}

curl "https://ENPOINT_URL/api/v1/results?date={date}" \
    -H 'Authorization: Bearer test_api_token' \
    -X GET

Response

{
  "data": [
    {
      "customer_id": "customer_id1",
      "experiment_id": "experiment_id",
      "date": "yyyy/mm/dd hh:mm:ss",
      "varient": "varient"
    },
    {
      "customer_id": "customer_id2",
      "experiment_id": "experiment_id",
      "date": "yyyy/mm/dd hh:mm:ss",
      "varient": "varient"
    }
  ],
  "status": "Success",
  "errors": ""
}

Toovio results can be retrieved via the results API. Calling the results API will return a json object with the results of the lastest experiment runs (you can also pass a date to return older results).

GET

HTTP Request /results?date={date}

Parameters

Name	Located in	Description	Required	Type	Format	Example
date	url	date to return results for	yes	date		yyyy/mm/dd

Responses

Code	Description
200	200 response

Step 9. go live

Once you have successfully completed the required steps it is time to Go LIVE !!!

Please reach out to Toovio who will provide you with your credentials to get started.

Errors

The Toovio light API uses the following error codes:

Error Code	Meaning
400	Bad Request -- Your request is invalid.
401	Unauthorized -- Your API key is wrong.
403	Forbidden -- Locked or unavailable resource.
404	Not Found -- The specified page / API could not be found.
405	Method Not Allowed -- You tried to access an API with an invalid method or parameters.
406	Not Acceptable -- You requested a format that isn't json.
429	Too Many Requests -- Too many API requests.
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.