Goals
Goals help your team meet your sales targets. There are three types of goals - company, team and user.
Find goals
Returns data about goals based on criteria. For searching, append {searchField}={searchValue} to the URL, where searchField can be any one of the lowest-level fields in dot-notation (e.g. type.params.pipeline_id; title). searchValue should be the value you are looking for on that field. Additionally, is_active=<true|false> can be provided to search for only active/inactive goals. When providing period.start, period.end must also be provided and vice versa.
Request
/v1/goals/find
Query parameters
type.name
string
The type of the goal. If provided, everyone's goals will be returned.
Values
deals_won
deals_progressed
activities_completed
activities_added
deals_started
title
string
The title of the goal
is_active
boolean
Whether the goal is active or not
Default
true
assignee.id
integer
The ID of the user who's goal to fetch. When omitted, only your goals will be returned.
assignee.type
string
The type of the goal's assignee. If provided, everyone's goals will be returned.
Values
person
company
team
expected_outcome.target
number
The numeric value of the outcome. If provided, everyone's goals will be returned.
expected_outcome.tracking_metric
string
The tracking metric of the expected outcome of the goal. If provided, everyone's goals will be returned.
Values
quantity
sum
expected_outcome.currency_id
integer
The numeric ID of the goal's currency. Only applicable to goals with expected_outcome.tracking_metric with value sum. If provided, everyone's goals will be returned.
type.params.pipeline_id
array
An array of pipeline IDs or null for all pipelines. If provided, everyone's goals will be returned.
type.params.stage_id
integer
The ID of the stage. Applicable to only deals_progressed type of goals. If provided, everyone's goals will be returned.
type.params.activity_type_id
array
An array of IDs or null for all activity types. Only applicable for activities_completed and/or activities_added types of goals. If provided, everyone's goals will be returned.
period.start
string
The start date of the period for which to find goals. Date in format of YYYY-MM-DD. When period.start is provided, period.end must be provided too.
Format
date
period.end
string
The end date of the period for which to find goals. Date in format of YYYY-MM-DD.
Format
date
Response
OK
Expand all
Copy code- true
- 20000
- "OK"
- "statistics-goals-api"
- { ... }▶
Get result of a goal
Gets the progress of a goal for the specified period.
Request
/v1/goals/{id}/results
Path parameters
id
string
required
The ID of the goal that the results are looked for
Query parameters
period.start
string
required
The start date of the period for which to find the goal's progress. Format: YYYY-MM-DD. This date must be the same or after the goal duration start date.
Format
date
period.end
string
required
The end date of the period for which to find the goal's progress. Format: YYYY-MM-DD. This date must be the same or before the goal duration end date.
Format
date
Response
OK
Expand allCopy code- true
- 20000
- "OK"
- "statistics-goals-api"
- { ... }▶
Add a new goal
Adds a new goal. Along with adding a new goal, a report is created to track the progress of your goal.
Request
/v1/goals
Body parameters
application/json
title
string
The title of the goal
assignee
object
required
Who this goal is assigned to. It requires the following JSON structure: { "id": "1", "type": "person" }. type can be either person, company or team. ID of the assignee person, company or team.
type
object
required
The type of the goal. It requires the following JSON structure: { "name": "deals_started", "params": { "pipeline_id": [1, 2], "activity_type_id": [9] } }. Type can be one of: deals_won, deals_progressed, activities_completed, activities_added, deals_started or revenue_forecast. params can include pipeline_id, stage_id or activity_type_id. stage_id is related to only deals_progressed type of goals and activity_type_id to activities_completed or activities_added types of goals. The pipeline_id and activity_type_id need to be given as an array of integers. To track the goal in all pipelines, set pipeline_id as null and similarly, to track the goal for all activities, set activity_type_id as null.”
expected_outcome
object
required
The expected outcome of the goal. Expected outcome can be tracked either by quantity or by sum. It requires the following JSON structure: { "target": "50", "tracking_metric": "quantity" } or { "target": "50", "tracking_metric": "sum", "currency_id": 1 }. currency_id should only be added to sum type of goals.
duration
object
required
The date when the goal starts and ends. It requires the following JSON structure: { "start": "2019-01-01", "end": "2022-12-31" }. Date in format of YYYY-MM-DD. "end" can be set to null for an infinite, open-ended goal.
interval
string
required
The interval of the goal
Values
weekly
monthly
quarterly
yearly
Response
OK
Expand allCopy code- true
- 20000
- "OK"
- "statistics-goals-api"
- { ... }▶
Update existing goal
Updates an existing goal.
Request
/v1/goals/{id}
Path parameters
id
string
required
The ID of the goal
Body parameters
application/json
title
string
The title of the goal
assignee
object
Who this goal is assigned to. It requires the following JSON structure: { "id": "1", "type": "person" }. type can be either person, company or team. ID of the assignee person, company or team.
type
object
The type of the goal. It requires the following JSON structure: { "name": "deals_started", "params": { "pipeline_id": [1, 2], "activity_type_id": [9] } }. Type can be one of: deals_won, deals_progressed, activities_completed, activities_added, deals_started or revenue_forecast. params can include pipeline_id, stage_id or activity_type_id. stage_id is related to only deals_progressed type of goals and activity_type_id to activities_completed or activities_added types of goals. The pipeline_id and activity_type_id need to be given as an array of integers. To track the goal in all pipelines, set pipeline_id as null and similarly, to track the goal for all activities, set activity_type_id as null.”
expected_outcome
object
The expected outcome of the goal. Expected outcome can be tracked either by quantity or by sum. It requires the following JSON structure: { "target": "50", "tracking_metric": "quantity" } or { "target": "50", "tracking_metric": "sum", "currency_id": 1 }. currency_id should only be added to sum type of goals.
duration
object
The date when the goal starts and ends. It requires the following JSON structure: { "start": "2019-01-01", "end": "2022-12-31" }. Date in format of YYYY-MM-DD. "end" can be set to null for an infinite, open-ended goal.
interval
string
The interval of the goal
Values
weekly
monthly
quarterly
yearly
Response
OK
Expand allCopy code- true
- 20000
- "OK"
- "statistics-goals-api"
- { ... }▶
Delete existing goal
Marks a goal as deleted.
Request
/v1/goals/{id}
Path parameters
id
string
required
The ID of the goal
Response
OK
Expand allCopy code- true
- 20000
- "OK"
- "statistics-goals-api"