thinking about it, please hold on..

List API


The Totango LIST API returns all accounts currently matching a list based on the list's ID.

This API is provided for backwards compatibility. The Search API is a newer API with more flexibility. 

Your authentication key

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.

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


Listing all accounts in a list

To use the List API, you will need the Totango ID of the list you would like to access. Open your list and obtain the list ID from the "Generate API Endpoint" menu option.


curl -H "Authorization: [your-token-here]" 


{   service_id:"YOUR_TOTANGO_SERVICE_ID",
        name: "Barksdale industries"
        status: {current:"Trial", changed:1354754839000}
            health:{current:"Poor", previous:"Good",reason:"Less than 10% license utilization", last_changed:1335303409487}
            Region: "Baltimore",
            Plan: "Pro",
            Licenses: "90",

    // 99 more account omitted from example 


Paging through the result set

By default, Totango returns the first 1000 accounts in the result set. To page though the result set use the count and offset parameters

  • count: The total number of results to return. (max = 1000) 
  • offset: First result to return. A number of 1,000 will return the 1001 account on the list. 

The following is a sample script that cycles through the results (PHP)


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


/* 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 = ""; // get it from:!/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) {
echo "$count] {$account->account_id} ({$account->name}) engagement:{$account->engagement->score->current} \n";


/* This function fetches a page of accounts from an active-list
/* - $API_KEY : Your API token. Get it from: get it from:!/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) {

$url = "$activeListID/current.json?length=$pageLength&offset=$page";
echo "** calling Totango API for page: $page ($pageLength accounts each page)\n";
echo "$url\n....\n";
$ch = curl_init();
curl_setopt($ch,CURLOPT_HTTPHEADER, array("Authorization: $API_KEY"));
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$res = curl_exec($ch);
// todo: error check the result before decoding...
$resObj = json_decode($res);

return $resObj;


Sorting Options

"The List API has some sorting options, though they are not as comprehensive as the Search API (In fact, that was one of the motivations for us to develop the Search API)

With the List API you can add an optional sort= parameter to the query string with any of the following tokens: first_activity, last_activity, active_users,engagement,name,health,contract_value,create_date and status

This will return the results sorted accordingly (see example below). You can also specify the sort_direction (asc & desc) as in the example below

curl --header 'app-token:YOUR_TOKEN_HERE' ' ID/current.json?length=5&sort_direction=asc&sort=active_users';

The Search API for this use-case can take an approach of building the fields section of the API call programmatically. I.e. by using a configuration file with the list of attributes or metrics they need. In this way, they add/remove fields without changing code."


Have more questions? Submit a request


Powered by Zendesk