Data API Overview

Contents

Getting started with the API – Authentication
Listing accounts in an active-list
Retrieve engagement statistics for accounts in an active-list
Retrieve users from accounts in an active-list
Retrieve status lifecycle history for accounts in an active-list
Getting recent changes to an active-list
Paging through the result set
Error codes
Examples

Totango Data API is a RESTful interface providing programmatic access to engagement data and metrics in the Totango Engagement Database. The API is intended for:

Customers that require api access to Totango for the purpose of integrating it with with other backend systems
Partners developing 3rd party connectors to Totango

If you are looking to send data to Totango please refer to these docs and walkthroughs. The Data API provides the opposite – pulling data from Totango

Getting started with the API – Authentication

You will need your API key in order to access the API. Login to Totango, click on your email to open your user profile and copy the API Key.
Update Profile Totango

Note: Click Regenerate Token to create a new API token and invalidate the current one.

Listing accounts in an active-list

The core API endpoints are Totango Active-lists. Define an active list on the Totango UI, then use the API to access metrics on accounts matching that list.

Accessing an active-list is done through its ID, which can be found at the bottom of the active-list page
Activelist

The following will provide high-level information on accounts on a specific list
Request:

1 2	curl -H "Authorization: [your-token-here]" 'https://app.totango.com/api/v1/accounts/active_list/1/current.json'

Response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

Retrieve engagement statistics for accounts in an active-list

Use return=stats to add usage statistics for every account in the active-list.

Request:

1 2	curl -H "Authorization: [your-token-here]" 'https://app.totango.com/api/v1/accounts/active_list/1/current.json?return=stats'

Response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54

{ service_id:"YOUR_TOTANGO_SERVICE_ID",
_revision:"r12692",
_type:"accounts-active-list",
_version:1.0,
accounts:[
{
account_id:"a4949",
name: "Barksdale industries"
status: {current:"Trial", changed:1354754839000}
foreign_id:null,
SF_id:null,
engagement:{
score:{change:-29.0,current:35},
health:{current:"Poor", previous:"Good",reason:"Less than 10% license utilization", last_changed:1335303409487}
},
attributes:{
Region: "Baltimore",
Plan: "Pro",
Renewal-Date:"2012-04-22",
Licenses: "90",
},
stats:{
users:{
realtime_today:{ "all":4, modules{ "task-management": "2", "reporting":"2", "administration": "1"} }
past_1d:{ "all":4, modules{ "task-management": "2", "reporting":"2", "administration": "1"} }
past_3d:{ "all":8, modules{ "task-management": "6", "reporting":"2", "administration": "1"} }
past_14d:{ "all":12, modules{ "task-management": "12", "reporting":"3", "administration": "1"} }
past_30d:{ "all":41, modules{ "task-management": "39", "reporting":"6", "administration": "1"} }
past_90d:{ "all":54, modules{ "task-management": "54", "reporting":"6", "administration": "1"} }
},
activities:{
realtime_today:{ "all":40, actions: {"create-task": 14, "delegate-task":11, "report-complete":1}, modules: { "task-management": "2", "reporting":"2", "administration": "1"}}
past_1d:{ "all":50, actions: {"create-task": 25, "delegate-task":20, "report-complete":5}, modules: { "task-management": "2", "reporting":"2", "administration": "1"}}
past_3d:{ "all":90, actions: {"create-task": 65, "delegate-task":20, "report-complete":5}, modules: { "task-management": "2", "reporting":"2", "administration": "1"}}
past_14d:{ "all":1211, actions: {"create-task": 553, "delegate-task":259, "report-complete":399}, modules: { "task-management": "2", "reporting":"2", "administration": "1"}}
past_30d:{ "all":5432, actions: {"create-task": 2112, "delegate-task":1409, "report-complete":1911}, modules: { "task-management": "2", "reporting":"2", "administration": "1"}}
past_90d:{ "all":5492, actions: {"create-task": 2112, "delegate-task":1409, "report-complete":1971}, modules: { "task-management": "2", "reporting":"2", "administration": "1"}}

},
last_activity:1334661220000,
first_activity:1294561539000
},

},
// 99 more account omitted from example
],
total_items:700,
response_header:{
scope:"all",
length:100,
offset:0},
current_item_count:100
}

The users block contains the number of users active at different time-frames (today, yesterday, past 3, 14, 30 or 90days). Under modules you can see the number of users that used each module in your application during that period.

The activities block contains the number of times each user-action was performed.

Retrieve users from accounts in an active-list

Use return=users to add usage statistics for every account in the active-list.

Request:

1 2	curl -H "Authorization: [your-token-here]" 'https://app.totango.com/api/v1/accounts/active_list/1/current.json?return=users'

Response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

the users array contains a list of users active in each account. first_usage & last_usage provides a timestamp (unix time) of when this user was first and last seen

Retrieve status lifecycle history for accounts in an active-list

Use return=lifecycle to get a log of changes to the account status attribute of each account.

Request:

1 2	curl -H "Authorization: [your-token-here]" 'https://app.totango.com/api/v1/accounts/active_list/1/current.json?return=lifecycle'

Response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

The lifecycle object holds the current status, including all past changes. The changed parameter is a unix-time value representing the time this status update occurred.

Getting recent changes to an active-list

Use /recent.json or /past.json to get a list accounts that were recently added or removed from the active-list, respectively. You must provide a since=<TIME-STAMP> parameter indicating the timestamp after which changes should be provided. TIME-STAMP must be in unix-time format.

This is useful for procedures that need to act on all accounts that match a certain list. E.g. a daily script that pulls on an “Inactive Accounts” Active-list to send an email to the end-user. Rather than iterating on the entire list and figuring out who has already received such an email, use the recent.json?since=XXXX API call to get a list of new relevant accounts since your last run.

Example: Retrieve all accounts that entered the active-list since Christmas Day

For /recent.json to work, the active list must be followed by at least one user. To follow a list, click the [Follow] button next to its name on the Totango UI. This enables the change-log on the list which is required for it to return information about recent changes

Request:

1 2	curl -H "Authorization: [your-token-here]" 'https://app.totango.com/api/v1/accounts/active_list/1/recent.json?since=1356912000'

Response:
Same as a current.json response format, but including only those accounts that entered the list since the provided timestamp (since= param)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

Paging through the result set

By default, Totango returns the first 100 accounts in the result set. Use the following parameters to page through the entire list:

length number of accounts to return (default: 100)
offsetresult set page. A value of 0 means the beginning of the list, 1 the second page of accounts (length+1) and so forth

The following PHP example iterates through the entires result set.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69

<?php

/************************************************************************************************/
/* Sample PHP code for using the Totango Data API.    */
/*    */
/* this script print outs accounts currently in an active-list (name + engagement score) */
/* (by default "all accounts", but you can pass a different ID as an argument to the script */
/************************************************************************************************/
$API_KEY = "--your api key here--"; // get it from: https://app.totango.com/app.html#!/updateProfile

$activeListID = 1; // default read the all-accounts active-list
if (isset($argv[1])) {
$activeListID = $argv[1];
}

// some basic code to cycle through returned accounts and print them out. interesting stuff is
// happening in the totangoActiveListCurrent() function below
$max = 0xffff; $total = 0; $count=0;
for ($page=0; $total < $max; $page++) {
$res = totangoActiveListCurrent($API_KEY, $activeListID, $page);

if ($res == null) {
die("invalid API response. Please make sure you are using a valid API KEY\n ");
}

if ($res->_error) {
die("error fetching list: {$res->_error}\n");
}

$max = $res->total_items;
$total += $res->current_item_count;

$accounts = $res->accounts;

foreach ($accounts as $account) {
$count++;
echo "$count] {$account->account_id} ({$account->name}) engagement:{$account->engagement->score->current} \n";
}
var_dump($account);

}

/************************************************************************************************************/
/* This function fetches a page of accounts from an active-list */
/* - $API_KEY : Your API token. Get it from: get it from: https://app.totango.com/app.html#!/updateProfile */
/* - $activeListID: ID of the list you are fetching. You can find it at the bottom of the */
/* Active Lists's page on totango */
/* - $page, $pageLength: Used to page through results.    */
/************************************************************************************************************/

function totangoActiveListCurrent($API_KEY, $activeListID, $page, $pageLength = 100) {

echo "** calling Totango API for page: $page ($pageLength accounts each page)\n";
$ch = curl_init();
curl_setopt($ch,CURLOPT_HTTPHEADER, array("Authorization: $API_KEY"));
curl_setopt($ch, CURLOPT_URL, "https://app.totango.com/api/v1/accounts/active_list/$activeListID/current.json?length=$pageLength&offset=$page&return=$returnType");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$res = curl_exec($ch);

$resObj = json_decode($res);

return $resObj;
}

?>

Error codes

All API call return a 200 – OK for successful API calls or one of the following errors:

300 Unauthorized: Incorrect credentials. Make sure you’re providing a valid API-key as explain in the Getting Started section above.
400 Bad Request: The parameters provided are invalid. See message content for details
500 Internal Server Error: Should not happen. Please Open a support case for help (make sure to add your API call and the response to help us troubleshoot)

Examples

See Basic PHP Example or the totango-commandline-utilities for a collection of useful PHP scripts, such as the ActivitiesExporter which generates a CSV file with the number of times specific activities were performed by accounts matching an Active-list. A perfect way to summarize usage.

Was this article useful? No, it was not helpful