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 insert mechanism if the account/user/activity doesn't exist.
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).
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/pixel.gif
- For services located in the EU Data Center, use https://sdr-eu1.totango.com/pixel.gif
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]
.
Refer to API considerations for account hierarchies for additional considerations.
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
Salesforce write-back
For integration with Salesforce on account attributes, you can additionally include a flag to trigger the write-back mechanism: enableWriteback=true
.
Write-back will trigger when all criteria has been met:
- The attribute is mapped as part of an active inbound job
- Write-back is enabled in the data modeler for the attribute
- The account whose attributes are being updated “qualifies” for at least one active inbound job, which is based on the query filter of the job
User attributes
Setting a user attribute is done using the format sdr_u.[attribute name]=[attribute value]
.
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
Special attributes
-
sdr_s
: Your Totango Service-id (ex. SP-00000-11) -
sdr_o
: the account’s id (ex. acc_123) -
sdr_o.account_name
: the account name (Display Name) -
sdr_u
: Your user identifier (ex. sam@someone.com) -
sdr_a
: User-action name (ex. Login) -
sdr_m
: Module in which action was taken (ex. Application) - User as Contact - you can control if the user will be shown as a contact:
-
Contact - Add or remove the user to the contact widget.
-
sdr_u.Contact = yes
(lowercase) will add the user as a contact -
sdr_u.Contact = no
(lowercase) will remove the contact (and keep the user)
-
-
Key Contact - set the user as a key contact on the account
-
sdr_u.Key%20Contact = yes
(lowercase) will add the user as a key contact -
sdr_u.Key%20Contact = no
(lowercase) will set the user as a normal user (not key contact)
-
-
Contact - Add or remove the user to the contact widget.
Named account attributes
-
sdr_o.Create%20Date
: The Account Creation Date (First Purchase date or when the customer becomes your customer). The value should be a valid date (ISO 8601 format) -
sdr_o.Contract%20Renewal%20Date
: The next Contract Renewal Date. The value should be a valid date (ISO 8601 format) -
sdr_o.Contract%20Start%20Date
: The first day of the current contract. The value should be a valid date (ISO 8601 format) -
sdr_o.Contract%20Value
: The Contract Value (MRR or ARR). The value should be a valid number (without comma-seperator and currency sign) -
sdr_o.Success%20Manager
: The name of the Success Manager (you can update any Account Role - please make sure the Role pre-defined in Totango and use the APi Name). -
sdr_o.parent_id
: The parent account Id (this will create the hierarchy between the parent and current accounts). -
sdr_o.product_id
: The product Id (type)
Custom attributes
- Any custom attribute can be updated by the API.
- Use the Attribute API name after the prefix, per the type
-
sdr_o
: Account-level attribute (for example, sdr_o.Plan=Pro) -
sdr_u
: User level attribute (for example, sdr_u.Phone=555-3232
-
Combine 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
Question: Is it possible to update tags using API?
Answer: No, currently this is not supported. You can update tags using a CSV upload.
Question: If I collect events by making HTTP calls to Totango collection gateways, can I also use Totango's JavaScript collector?
Answer: HTTP API method can complement Javascript collection for specific events or as an alternative if you cannot use the Totango Javascript collection library. If you are using NodeJS, you can also use the totango-tracker npm module.