Objectives API

Who can use this feature?

Global admins
Available on all plans

Totango provides an objectives API for the following:

Create an objective
Upate an objective
Delete an objective
Read objective template IDs
Create objective from the objective template library
Read objective category
Read objective status (legacy)

Before you begin

The user setting up the API must be a Totango admin
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
Objectives API does not support HTML markup/formatting of objectives
JSON format is supported for API calls

Create an objective

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

Replace APP_TOKEN with your authentication token.
Replace account-id with the account id.
See additional fields as required.

Example

curl -X POST https://api.totango.com/api/v3/objectives-collection \
-H "app-token: APP_TOKEN" \
-H "Content-Type: application/json" \
-D '{
    "accountId": "account-id", 
    "objectiveId": "123e4567-e89b-12d3-a456-426614174000",
    "objectiveData": {
      "title": "Improve onboarding",
      "description": "Help customer complete integration",
      "activityTypeId": "activity_type_1",
      "objectiveTemplateId": "550e8400-e29b-41d4-a716-446655440000",
      "completionCriteria": "All milestones complete",
      "owner": "user@company.com",
      "visibility": "internal",
      "status": "Not Started",
      "dueDate": "2025-07-30",
      "dynamicDueDate": {
        "attributeKey": "contract_start_date",
        "days": 14
     },
      "milestones": [
       {
         "id": "milestone_1",
         "description": "Kickoff call completed",
         "dueDate": "2025-07-20",
         "isCompleted": false,
         "isManual": false,
         "attributeFieldName": "kickoff_call_date",
         "attributeQueryTerm": "completed"
       },
       {
         "id": "milestone_2",
         "description": "Integrations complete",
         "dueDate": "2025-07-25",
         "isCompleted": false,
         "isManual": true,
         "startValue": 0,
         "currentValue": 2,
         "targetValue": 3,
         "manualMilestoneType": "count"
       }
      ]
    }
 }'

Field descriptions

Required fields are denoted with an asterisk (*).

Objective fields

*accountId: string | Account identifier. Example: "account_sample_id"
objectiveId: uuid | UUID format, if not sent an objectiveId will be generated. (On update it's required.)
*title: string | Objective title
description: string | Objective description
activityTypeId: string | objective flow
objectiveTemplateId: string | Template identifier
*completionCriteria: string |One of: "Tasks are complete", "Milestones are complete", "Milestones + tasks are complete", "Manually marked as complete"
owner: string | User identifier (uuid/username). Example: "user@totango.com"
*visibility: string | One of: Internal, Customer Facing. Customer Facing is supported only if it is enabled in objective settings
status: string | One of: "Not Started", "In Progress", "Blocked", "On Hold", "Cancelled", "Completed"
dueDate: string | ISO date format
*dynamicDueDate.attributeKey: string | Required if dynamicDueDate provided
*dynamicDueDate.days: number | Required if dynamicDueDate provided

Milestone fields (automatic)

*id: string | Supported only for updating existing milestone
*description: string
dueDate: string, nullable | ISO date
*isCompleted: boolean
isManual: false
*attributeFieldName: string
attributeQueryTerm: string

Milestone fields (manual)

*id: string | Supported only for updating existing milestone
*description: string
dueDate: string, nullable | ISO date
*isCompleted: boolean
isManual: true
startValue: number, nullable
currentValue: number, nullable
targetValue: number, nullable
*manualMilestoneType: string | One of "Numeric", "Currency", "Checkbox"

Update an objective

Update an objective using the following: https://api.totango.com/api/v3/objectives-collection

Replace APP_TOKEN with your authentication token.
Replace account-id with the account id.
Replace objective-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-collection/?accountId={account-id}.
Same fields available as in create, with the addition of the following option:
- milestonesIdsToDelete: string | Array of milestone IDs to delete

curl -X PUT https://api.totango.com/api/v3/objectives-collection/ \
-H "app-token: APP_TOKEN" \
-H "Content-Type: application/json" \
-D '{
    "accountId": "account-id", 
    "objectiveId": "objective-id",
    "objectiveData": {
      // ... same as POST objectiveData
      "milestonesIdsToDelete": ["milestone_3"]
    }
 }'

Reopen an objective

Change Objective Status from "Complete" to something else to reopen an objective and make it editable again: https://api.totango.com/api/v3/objectives-collection

Replace APP_TOKEN with your authentication token.
Replace account-id with the account id.
Replace objective-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-collection/?accountId={account-id}.
Visibility “Internal” is capitalized
Below is the minimum required fields to update the Status from "Completed" to "In Progress" to allow edits to the objective.

curl --location 'https://api.totango.com/api/v3/objectives-collection' \
--header 'app-token: APP_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
  "accountId": "account-id",
  "objectiveId": "objective-id",
  "objectiveData": {
    "title": "objectivename",
    "completionCriteria": "Manually marked as complete",
    "visibility": "Internal",
    "status": "In Progress"
  }
}'

Delete an objective

Delete an objective using the following: https://api.totango.com/api/v3/objectives-collection

Replace APP_TOKEN with your authentication token.
Replace account-id with the account id.
Replace objective-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-collection/?accountId={account-id}.
Same fields available as in create, with the addition of the following option:
- *objectiveTasksHandling: string | One of: "deleteAllTasks" - Delete all tasks associated with objective, "assignToOtherObjective" - Move tasks to another objective, "keepOrphaned" - Keep tasks without objective (default)
- *newObjectiveId: uuid | Required only if objectiveTasksHandling is "assignToOtherObjective"

curl -X DELETE https://api.totango.com/api/v3/objectives-collection \
-H "app-token: APP_TOKEN" \
-H "Content-Type: application/json" \
-D '{
    "accountId": "account-id", 
    "objectiveId": "objective-id",
    "objectiveTasksHandling": "keepOrphaned",
    "newObjectiveId": null
    }
 }'

Read objective template ids

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

Replace APP_TOKEN with your authentication token.
Add query parameter extended=true to get milestones and tasks objective.
Add query parameter addCounts=true (and do not use extended parameter) to get milestones and tasks count, without full objects.

curl -X GET "https://api.totango.com/api/v3/objective-templates?objectiveTemplateIds=template1,template2&addCounts=true&extended=true" \
-H "app-token: APP_TOKEN" \

Create objective from template

If the fallback for roles or objective owner does not exist, the owner will be the user that performed the request.

Create objective from a template using the following: https://api.totango.com/api/v3/objectives-collection/create-by-template

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 -X POST https://api.totango.com/api/v3/objectives-collection \ 
-H "app-token: APP_TOKEN" \ 
-H "Content-Type: application/json" \ 
-D '{
    "accountId": "account-id",
    "ObjectiveTemplateId": "objective-template-id"
}'

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 -X GET "https://api.totango.com/api/v3/objective-settings/category" \
-H "app-token: APP_TOKEN" \
-H "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"
}
]

Read objective status

Custom objective status is no longer supported. Any statuses you retrieve are for legacy objectives that have been migrated to the new version.

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

Replace APP_TOKEN with your authentication token.

curl -X GET "https://api.totango.com/api/v3/objective-settings/status" \
-H "app-token: APP_TOKEN" \
-H "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"
}
]

Objectives API

Before you begin

Create an objective

Example

Field descriptions

Objective fields

Milestone fields (automatic)

Milestone fields (manual)

Update an objective

Reopen an objective

Delete an objective

Read objective template ids

Create objective from template

Read objective category

Response

Read objective status

Response

Was this article helpful?

In this article

<%= heading %>

<% if (block.html_url) { %> <%= block.name %> <% } else { %> <%= block.name %> <% } %>

Categories

Toggle navigation menu

<%= category.name %>