The Search API allows you to query Totango's online database for accounts (or users) that fit 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.
Before you begin
- You need your Totango API token key.
- For US services, please use
https://api.totango.com - For EU services, please use
https://api-eu1.totango.com - Like all APIs, there is a global rate limit of 100 calls/minute for each token.
- There is a maximum of 10,000 total records that can be accessed through this API.
Search for accounts
To search for accounts matching certain criteria, use the /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://api.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.
-
offset (optional, default: 0): Record number (0 states "start at record 0"). The record size can be defined using the count parameter (and limited to 1000).
*To page through results, ask for 1000 records (count: 1000). If you receive 1000 records, assume there’s more, in which case you want to pull the next 1000 records (offset: 1000…then 2000…etc.). Repeat paging until the number of records returned is less than 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
],
}
}
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.
Create your account search query
The easiest way to create a search query is to use the Totango UI and copy the resulting API call.
- Create a new account segment.
- Add filters and columns to match your desired search parameters.
- From the Ellipses (...), click Generate the API endpoint.
- Copy the code.
Search for users
To search for accounts matching certain criteria, use the /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 the 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://api.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.
-
offset (optional, default: 0): Record number (0 states "start at record 0"). The record size can be defined using the count parameter (and limited to 1000).
*To page through results, ask for 1000 records (count: 1000). If you receive 1000 records, assume there’s more, in which case you want to pull the next 1000 records (offset: 1000…then 2000…etc.). Repeat paging until the number of records returned is less than 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
]
}
}
}
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.
Create your user search query
The easiest way to create a search query is to use the Totango UI and copy the resulting API call.
- Create a new user segment.
- Add filters and columns to match your desired search parameters.
- From the Ellipses (...), click Generate the API endpoint.
- Select the Insert my API token box, and click Copy
The API token here uses the session token, which is either the legacy v1 token or a session token generated upon login. It's not a personal access token.
Test your query using Postman
The following steps were tested using Postman v7.21.2 and support both accounts and users search API
- Copy the API Endpoint from Totango.
Make sure you marked the Insert my API token option using the steps detailed above.
- Open Postman and open the Import option
- Select the Paste Raw Text tab and paste your API endpoint.
- Postman will open a new request tab. Review the header (set up the token, if not exists) and the body and send the request.