The Search API (events) endpoints can be used to search any type of events in Totango, that fit certain search criteria (e.g., "all touchpoints created in the last 90 days"). 

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
• The API will return up to 1000 events per call and supports pagination. You can use the offset property to get the next page.

Search for events

To search for accounts matching certain criteria, use the POST {US or EU api URL}/api/v2/events/search API endpoint.

For example, the following searches for touchpoints and campaigns events, for a specific account:

curl --data 'query={"terms": [{"type":"or","or":[{"type":"event_property","name":"event_type","eq":"note"},{"type":"event_property","name":"event_type","eq":"campaign_touch"}]}],"fields": [], "offset": 0, "count": 5 }' \
--data 'account_id=ACCOUNT_ID' \
--header 'app-token:YOUR-TOKEN-HERE' 'https://api.totango.com/api/v2/events/search'

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 (refer to Term section to view different options of terms)
• fields (mandatory): list of fields to return as results. Note that this should be always empty (i.e., []).
• count (mandatory): 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 (mandatory): Page number (0 is the 1st-page). The page size can be defined using the count parameter (and limited to 1000).

Other available parameters in the API call:

• account_id (optional): filter the results for a specific account.

Response

A sample result set will look like the following:

{
 "_type": "status",
 "_revision": "r70b99d7",
 "_version": 1,
 "response": {
 "events": {
 "hits": [
 {
 "id": "1233",
 "timestamp": 1588493035000,
 "type": "note",
 "account": {
 "id": "ACCOUNT_ID"
 },
 "is_new": null,
 "note_content": {
 "text": " @person1 @person2 Please let me know when I can start the process.\n ",
 "totango_user": {
 "user_name": "someone@totango.com"
 },
 "note_id": 10871655
 },
 "properties": {
 "customers_visibility": false,
 "informed": [
 "person1@totango.com",
 "person2@totango.com"
 ],
 "activity_type_id": "support",
 "parent_id": 1234,
 "subject": "Task/Touchpoint Migration",
 "meeting_type": "internal_note",
 "totango_participants": [
 "person1@totango.com",
 "person2@totango.com"
 ]
 }
 }
 ],
 "total": 5
 }
 },
 "status": "success",
 "service_id": "0000" //Service Id
}

Results are provided in the "hits" array under the "events" object. Each array entry is a single account. 

Terms

The following are common terms you can use to query the data.

Get notes (touchpoints)

{"terms": [{"type":"event_property","name":"event_type","eq":"note"}], "fields": [], "offset": 10, "count": 5 }

Optional values for event_type are "note" (touchpoint), "campaign_touch: (campaigns event), "alert" (health change), "task" (task event - created, updated, completed)

Get notes (touchpoints) and campaigns events

{"terms": [{"type":"or","or":[{"type":"event_property","name":"event_type","eq":"note"},{"type":"event_property","name":"event_type","eq":"campaign_touch"}]}],"fields": [], "offset": 0, "count": 5 }

Get notes (touchpoints) and campaigns events created yesterday

{"terms": [{ "type":"date", "term" : "date", "joker" : "yesterday"},{"type":"or","or":[{"type":"event_property","name":"event_type","eq":"note"},{"type":"event_property","name":"event_type","eq":"campaign_touch"}]}],"fields": [], "offset": 0, "count": 1000 }

Using the term "joker" you can define the dates (today, yesterday, last_30_days, etc).

Get notes (touchpoints) created after a specific date

optional values for the date term are gt (greater than), gte (greater than or equal to), lg (lower than).

{"terms": [{ "type":"date", "term" : "date", "gte" : 1587859200000},{"type":"event_property","name":"event_type","eq":"note"}], "fields": [], "offset": 0, "count": 1000 }

The date value is a timestamp in Unix time (EPOCH) milliseconds format.