Goals help your team meet your sales targets. There are three types of goals - company, team and user.
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.
/v1/goals/find
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
OK
Gets the progress of a goal for the specified period.
/v1/goals/{id}/results
id
string
required
The ID of the goal that the results are looked for
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
OK
Adds a new goal. Along with adding a new goal, a report is created to track the progress of your goal.
/v1/goals
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
OK
Updates an existing goal.
/v1/goals/{id}
id
string
required
The ID of the goal
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
OK
Marks a goal as deleted.
/v1/goals/{id}
id
string
required
The ID of the goal
OK