Overview

The purpose of this document is to get you familiar with the Totango HTTP API

The Totango HTTP API is used to log user-activity events(and create non existing events) and/or attribute-updates  on accounts (existing or new) and users (existing or new), there is no need to create users/accounts/activities prior to sending them via this API it works on an upsert mechanism if the account/user/activity doesn't exist it will be created. In each case, it involves sending an HTTP:// or HTTPS:// call to the Totango collection gateway. The gateway should respond with an HTTP 200 Success response code and return a 1x1 transparent gif image.  This 200 Success message signifies a valid network connection, it is not a confirmation that the request is correctly formed.   For requests that receive anything other than 200OK you should log those calls and resend at a later point.  You can use HTTP GET or HTTP POST to send events to Totango.

To send data using this API, please use HTTPS, with version 1.2 or above (1.1, 1.0 are no longer supported).

In this article, you can find data regarding:

• Activity Tracking (Usage)
• Account Attributes
• User Attributes
• Combined data
• FAQ

Entry Points

All the examples in this document are using the US data center entry point.

• For services located in the US Data Center, use https://sdr.totango.com
• For services located in the EU Data Center, use https://sdr-eu1.totango.com 

Activity Tracking

Activity tracking is used to log an activity performed by one of your customers. For example, when a user logs-in, or when they complete an important activity. 

The following parameters are mandatory when sending activity:

• sdr_s:  Your Totango Service-id  (ex. SP-0000-11)
• sdr_o: the account’s id (ex. u1235)
• sdr_u: email address for the user (or alternative unique identifier) (ex. someone@somewhere.com)
• sdr_a: User-action name (ex. Login)
• sdr_m Module in which action was taken (ex. Application)

The following parameter is optional:

• sdr_o.account_name: the human friendly account name.  (ex. ACME Inc.)

The following is an example of an activity tracking call using the above sample data:

https://sdr.totango.com/pixel.gif/?sdr_s=SP-0000-11&sdr_o=u1235&sdr_u=someone@somewhere.com&sdr_a=Login&sdr_m=Application 

Account attributes 

Setting an account attribute is done using the format sdr_o.[attribute name]=[attribute value]. The account-id (sdr_o) is mandatory:

The following parameters are mandatory to update an Account attribute:

• sdr_s:  Your Totango Service-id  (ex. SP-0000-11)
• sdr_o: the account’s id (ex. u1235)
• sdr_o.[attribute name]: any account attribute (ex. sdr_o.Account%20Type=Demo)

The following is an example of an account attribute update call using the above sample data plus updating the following attributes with respective values:

Account Type:Demo
account_size:52

https://sdr.totango.com/pixel.gif/?sdr_s=SP-0000-11&sdr_o=u1235&sdr_o.Account%20Type=Demo&sdr_o.account_size=52

User attributes

Setting a user attribute is done using the format sdr_u.[attribute name]=[attribute value]. The account-id (sdr_o) and user-id (sdr_u) are mandatory:

The following paramaters are mandatory to update a user attribute:

• sdr_s:  Your Totango Service-id  (ex. SP-0000-11)
• sdr_o: the account’s id (ex. u1235)
• sdr_u: email address for the user (or alternative unique identifier) (ex. someone@somewhere.com)
• sdr_u.[attribute name]: any user attribute (ex. sdr_u.Role=Admin)

The following is an example of a user attribute update call using the above sample data plus updating the following attributes with respective values:

role:admin

https://sdr.totango.com/pixel.gif/?sdr_s=SP-0000-11&sdr_o=u1235&sdr_u=someone@somewhere.com&sdr_u.role=admin 

Combining event types

You can combine user and account attributes together in a single call.

https://sdr.totango.com/pixel.gif/?sdr_s=SP-xxxx-yy&sdr_o=u12214&sdr_u=joe@example.com&sdr_o.Account%20Type=Demo&sdr_u.role=admin

You can also combine attributes with activity tracking:

https://sdr.totango.com/pixel.gif/?sdr_s=SP-xxxx-yy&sdr_o=u12214&sdr_u=joe@example.com&sdr_o.Account%20Type=Demo&sdr_u.role=admin&sdr_a=Login&sdr_m=Application

cURL Command line syntax for POST

curl 'https://sdr.totango.com/pixel.gif/?sdr_s=SP-<service_id>-01&sdr_o=<account_id>&sdr_o.account_name=[account_display_name]&sdr_o.[attribute_N]=[attribute_N_value]&sdr_u=[user_id]&sdr_o.[user_attribute]=[user_attribute_value]'

• sdr_s:  Your Totango Service-id  (ex. SP-0000-11)
• sdr_o: the account’s id (ex. u1235)
• sdr_u: email address for the user (or alternative unique identifier) (ex. someone@somewhere.com)
• sdr_u.[attribute name]: any user attribute (ex. sdr_u.Name=RedJones)
• sdr_o.[attribute name]: any account attribute (ex. sdr_o.Contract%20Value=20000)

FAQs

Q: Is it possible to update 'tags' using API?

A: No, currently this is not supported. You can update tags using a CSV upload.