Objectives API

Who can use this feature?

  • Global admins
  • Available on all plans

Totango provides an objectives API for the following:

Before you begin

  • The user setting up the API must be a Totango admin
  • You need your Totango API token key 
  • Like all APIs, there is a global rate limit of 100 calls/minute for each token
  • Objectives API does not support HTML markup/formatting of objectives
  • JSON format is supported for API calls

Read objective status

Read objective status using the following: https://api.totango.com/api/v3/objective-settings/status

  • Replace APP_TOKEN with your authentication token.
curl --location 'https://api.totango.com/api/v3/objective-settings/status' \
--header 'app-token: APP_TOKEN' \
--header 'Content-Type: application/json'

Response

[
{
 "id": "7ee010f0-1228-222-974e-89b5d2cf2152",
 "displayName": "On Hold",
 "createdBy": "user@tot.com",
 "updatedBy": "",
 "createdAt": "2023-11-27T18:35:07.000Z",
 "updatedAt": "2023-11-27T18:35:07.000Z"
},
{
 "id": "b4556225-a73e-47d7-b9f4-5e9c6d72ad98",
 "displayName": "Completed",
 "createdBy": "user@tot.com",
 "updatedBy": "",
 "createdAt": "2023-11-27T18:35:18.000Z",
 "updatedAt": "2023-11-27T18:35:18.000Z"
},
{
 "id": "c12123be-24cd-4a9a-96f4-1ac05703f814",
 "displayName": "In Progress",
 "createdBy": "user@tot.com",
 "updatedBy": "",
 "createdAt": "2023-11-27T18:35:02.000Z",
 "updatedAt": "2023-11-27T18:35:02.000Z"
}
]

Read objective category

Read objective category using the following: https://api.totango.com/api/v3/objective-settings/category.

  • Replace APP_TOKEN with your authentication token.
curl --location 'https://api.totango.com/api/v3/objective-settings/category' \
--header 'app-token: APP_TOKEN' \
--header 'Content-Type: application/json'

Response

[
{
 "id": "38kky9b3-4c85-487a-a26f-d13d0485da34",
 "displayName": "Churn Prevention",
 "createdBy": "user@tot.com",
 "updatedBy": "user@tot.com",
 "createdAt": "2023-11-27T18:36:01.000Z",
 "updatedAt": "2023-11-27T18:36:07.000Z"
},
{
 "id": "b6d0a419-bab9-4fcf-ppp-2ea9b425ff19",
 "displayName": "Upsale",
 "createdBy": "user@tot.com",
 "updatedBy": "",
 "createdAt": "2023-11-27T18:35:40.000Z",
 "updatedAt": "2023-11-27T18:35:40.000Z"
},
{
 "id": "fd639075-qqqq-4390-afb5-6c21b268515d",
 "displayName": "Churn detection",
 "createdBy": "user@tot.com",
 "updatedBy": "",
 "createdAt": "2023-11-27T18:35:48.000Z",
 "updatedAt": "2023-11-27T18:35:48.000Z"
}
]

Create an objective

Create an objective using the following: https://api.totango.com/api/v3/objectives

  • Replace APP_TOKEN with your authentication token.
  • Replace account-id with the account id.
  • Replace objective-status-id and objective-category-id with the ids obtained from the methods above (read objective status and read objective category).
  • If you provide the successPlays property and it is empty, the system will delete all the links to the SuccessPlays. If you don't want to change linked SuccessPlays, don't include successPlays property in the request. The SuccessPlays that choose to include in the "successPlays" property will be the ones to link to the objective instance. 

Example with empty "successPlays" value (no links)

curl --location 'https://api.totango.com/api/v3/objectives/' \
--header 'app-token: APP_TOKEN \
--header 'Content-Type: application/json' \
--data '{
    "accountId": "account-id",
    "startDate": "2024-02-08T20:10:00.000Z",
    "endDate": "2024-02-28T20:10:00.000Z",
    "categoryId": "objective-category-id",
    "statusId": "objective-status-id",
    "title": "Drive more promoters on G2",
    "description": "Launch customer advocacy program with G2 requests",
    "owner": "george@example.demo",
    "successPlays": []
}'

Example with "successPlays" value (add links)

curl --location 'https://api.totango.com/api/v3/objectives/' \
--header 'app-token: APP_TOKEN \
--header 'Content-Type: application/json' \
--data '{
    "accountId": "account-id",
    "startDate": "2024-02-08T20:10:00.000Z",
    "endDate": "2024-02-28T20:10:00.000Z",
    "categoryId": "objective-category-id",
    "statusId": "objective-status-id",
    "title": "objective title",
    "description": "objective description",
    "owner": "george@example.demo",
    "successPlays": ["successplay-id"]
}'

Update an objective

Update an objective using the following: https://api.totango.com/api/v3/objectives/{objective-instance-id}

  • Replace {objective-instance-id} with the id of the objective as it exists on an account. You can get this value from a tasks segment or from this API: https://api.totango.com/api/v3/objectives/?accountId={account-id}.
  • Replace APP_TOKEN with your authentication token.
  • Replace account-id with the account id.
curl --location --request PUT 'https://api.totango.com/api/v3/objectives/{objective-instance-id}' \
--header 'app-token: APP_TOKEN \
--header 'Content-Type: application/json' \
--data '{
"accountId": "account-id",
"startDate": "2024-02-08T20:10:00.000Z",
"endDate": "2024-02-28T20:10:00.000Z",
"categoryId": "objective-category-id",
"statusId": "objective-status-id",
"title": "Drive more promoters on G2", 
"description": "Launch customer advocacy program with G2 requests"

Delete an objective

Delete an objective using the following: https://api.totango.com/api/v3/objectives/{objective-instance-id}

  • Replace {objective-instance-id} with the id of the objective as it exists on an account.
  • Replace APP_TOKEN with your authentication token.
curl --location --request DELETE 'https://api.totango.com/api/v3/objectives/{objective-instance-id}' \
--header 'app-token: APP_TOKEN'

Read objective template ids

Read team detail using the following: https://api.totango.com/api/v2/objective-templates

  • Replace APP_TOKEN with your authentication token.
curl --location 'https://api.totango.com/api/v2/objective-templates' \
--header 'app-token: APP_TOKEN'

Create objective from the objective template library

Read team detail using the following: https://api.totango.com/api/v2/objective-templates/run

  • Replace APP_TOKEN with your authentication token.
  • Replace objective-template-id with the objective template id obtained from the method above (read objective template id).
  • Replace account-id with the account id.
curl --location --request POST 'https://api.totango.com/api/v2/objective-templates/run' \
--header 'app-token: APP_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"objectiveTemplateId": "objective-template-id",
"accountId": "account-id"
}'

Response

If successful, the response is returned: Success

If validation does not pass, one of the following responses is returned:
- Status 400, message “Objective must contain at least one SuccessPlay"
- Status 404, message “Account not found"
- Status 404, message “Objective template not found"

Was this article helpful?

0 out of 0 found this helpful

Have more questions? Submit a request