CONTENT
  thinking about it, please hold on..

Search API

Overview

The Search API allows you to query Totango's online database for accounts (or users) that fit a certain search criteria (e.g. "all paying customers who were active in the last 90 days"). You can specify which data fields you'd like Totango to return for every account (user) that fits the criteria.  

Your Authentication Key

You will need your API key in order to access the API.

Login to Totango, click on your username (top-right corner of the page) and open your user profile. Your API Key is available under the INTEGRATION tab

Searching for Accounts

To search for accounts matching a certain criteria, use the https://app.totango.com/api/v1/search/accounts API endpoint. You will need to POST the search criteria and list the account fields you'd like returned as a JSON object.

For example, the following searches for all paying customers (Status Type = 'Paying'), returning their current health, the date health last changed and the name of the account's success manager.  

Request

curl --data 'query={
"terms":[
{"type":"string","term":"status_group","in_list":["paying"]}
],
"count":1000,
"offset":0,
"fields":[
{"type":"string","term":"health","field_display_name":"Health rank "},
{"type":"health_trend","field_display_name":"Health last change "},
{"type":"string_attribute","attribute":"Success Manager","field_display_name":"Success Manager"}
],
"sort_by":"display_name",
"sort_order":"ASC",
"scope":"all"
}'
--header 'app-token:YOUR-TOKEN-HERE' 'https://app.totango.com/api/v1/search/accounts'

 

Use the following parameters in the API call's query parameters:

  • terms (mandatory): An array contains one or more filter conditions to use for the search
  • fields (mandatory): list of fields to return as results. Note that the account name and account-id are always returned as well.
  • count (optional, default: 1000): The maximum number of accounts to return in the result set. If there are more results, you should use Paging to cycle through the result set. The max. value for count is 1000
  • sort_by, sort_order (optional, default display_name and ASC): The order to sort the result set by. 

Response

A sample result set will look like the following:

 

{
"response": {
"service_id":"2324",
"_revision":"r7e56629",
"_type":"status",
"_version":1.0,
"status":"success",
"stats":{
"total_hits":158
},
"accounts":{
"hits":[
{"name":"19934", // account-id
"display_name":"ACME Inc", // account-name
"last_activity_time":1421422240000,
"selected_fields":[ // requested fields
"red",
{"health":"red","health_prev":"green","change_date":1421614799999},
"George Xami"
]
},
// additional accounts omitted from response
],

}
}

NOTE that:

  • Results are provided in the "hits" array under the "accounts" object. Each array entry is a single account. 
  • Use the selected_fields array to retrieve the fields requested. The result is ordered in the same order as the response. I.e. The first field in selected_fields represents the first requested field and so on
  • The total number of results is available in the total_hits parameter. If it exceeds your requested count, you will need to page through the result set. 

 

Creating your search query

The easiest way to create a search query is to use the Totango UI and copy the resulting API call. 

1. Open the Accounts page on Totango and create a new account list

2. Add filters & columns to match your desired search parameters

3. Generate the API endpoint and copy the code

 

Searching for Users

 

To search for accounts matching a certain criteria, use thehttps://app.totango.com/api/v1/search/users API endpoint. You will need to POST the search criteria and list the account fields you'd like returned as a JSON object.

For example, the following searches for all users from paying customers (Status Type = 'Paying'), returning their last activity date and total number of activities in the last 14 days.

Request

..

curl --data 'query={
"terms":[
{"type":"parent_account","terms":[
{"type":"string","term":"status_group","in_list":["paying"]}
]
}
],
"count":1000,
"offset":0,
"fields":[
{"type":"date","term":"last_activity_time","field_display_name":"Last activity","desc":true},{"type":"named_aggregation","aggregation":"total_activities","duration":14,"field_display_name":"Activities (14d)"}
],
"scope":"all"
}'
--header 'app-token:YOUR-TOKEN-HERE' 'https://app.totango.com/api/v1/search/users'

 

 

Use the following parameters in the API call's query parameters:

  • terms (mandatory): An array contains one or more filter conditions to use for the search
  • fields (mandatory): list of fields to return as results. Note that the user name and id along with the account name and account-id are always returned as well. 
  • count (optional, default: 1000): The maximum number of accounts to return in the result set. If there are more results, you should use Paging to cycle through the result set. The max. value for count is 1000
  • sort_by, sort_order (optional, default display_name and ASC): The order to sort the result set by. 

Response

..

{
"response":{
"total_hits":2634},
"_revision":"r7e56629",
"_type":"status",
"_version":1.0,
"status":"success",
"users":{
"hits":[
{
"name":"moris@123.com",
"display_name":"moris@123.com",
"first_activity_time":1404296416000,
"last_activity_time":1423058976000,
"selected_fields":[1423058976000,1589]
},
// more users omited from response
]
}
}
}

NOTE that:

  • Results are provided in the "hits" array under the "users" object. Each array entry is a single account. 
  • Use the selected_fields array to retrieve the fields requested. The result is ordered in the same order as the response. I.e. The first field in selected_fields represents the first requested field and so on
  • The total number of results is available in the total_hits parameter. If it exceeds your requested count, you will need to page through the result set. 

 

Creating your search query

The easiest way to create a search query is to use the Totango UI and copy the resulting API call. 

1. Open the Accounts page on Totango and create a new user list

2. Add filters & columns to match your desired search parameters

3. Generate the API endpoint and copy the code

 

 

 

Have more questions? Submit a request

Comments

Follow
  • Avatar
    Sepulveda, Helder (ED)

    How do we convert those integers back to dates?
    Like this one:
    "last_activity_time":1423058976000

  • Avatar
    Oren Raboy

    Hi Helder,
    the last activity time is in unix time in milisecond. To convert to a date you would need to use the relevant function in your programming language.

    for example, in java you could use:
    java.util.Date lastActivity =new java.util.Date(last_activity_time);

    keep in mind that the number is in miliseconds, so if the function expects a number in seconds, simply divide by 1000.

Powered by Zendesk