openapi: 3.0.1
info:
title: Pipedrive API v1 Activities Goals API
version: 1.0.0
description: 'Activities are appointments/tasks/events on a calendar that can be associated with a deal, a lead, a person and an organization. Activities can be of different type (such as call, meeting, lunch or a custom type - see ActivityTypes object) and can be assigned to a particular user. Note that activities can also be created without a specific date/time.
'
servers:
- url: https://api.pipedrive.com/v1
tags:
- name: Goals
description: 'Goals help your team meet your sales targets. There are three types of goals - company, team and user.
'
paths:
/goals:
post:
summary: Add a new goal
description: Adds a new goal. Along with adding a new goal, a report is created to track the progress of your goal.
x-token-cost: 10
operationId: addGoal
tags:
- Goals
security:
- api_key: []
- oauth2:
- goals:full
requestBody:
content:
application/json:
schema:
title: addGoalRequest
type: object
required:
- type
- assignee
- expected_outcome
- duration
- interval
properties:
title:
type: string
description: The title of the goal
assignee:
type: object
description: '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:
type: object
description: '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:
type: object
description: '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:
type: object
description: '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:
type: string
enum:
- weekly
- monthly
- quarterly
- yearly
description: The interval of the goal
responses:
'200':
description: Successful response containing payload in the `data.goal` object
content:
application/json:
schema:
title: UpsertGoalResponse
type: object
properties:
success:
type: boolean
description: If the request was successful or not
data:
type: object
properties:
goal:
type: object
title: Goal
properties:
id:
type: string
description: The ID of the goal
owner_id:
type: integer
description: The ID of the creator of the goal
title:
type: string
description: The title of the goal
type:
type: object
description: The type of the goal
properties:
name:
type: string
description: The name of the goal type
params:
type: object
description: The parameters that accompany the goal type
properties:
pipeline_id:
type: array
description: The IDs of pipelines of the goal
items:
type: integer
activity_type_id:
type: array
description: The IDs of activity types of the goal
items:
type: integer
assignee:
type: object
description: Who the goal is assigned to
properties:
id:
type: integer
description: The ID of the goal assignee
type:
type: string
description: The type of the assignee
interval:
type: string
description: The interval of the goal
duration:
type: object
description: The duration of the goal
properties:
start:
type: string
description: The start date of the goal
end:
type: string
description: The end date of the goal
expected_outcome:
type: object
description: The expected outcome of the goal
properties:
target:
type: integer
description: The numeric target of the goal
tracking_metric:
type: string
description: The tracking metric of the goal
is_active:
type: boolean
description: Whether the goal is currently active or not
report_ids:
type: array
description: The IDs of the reports that belong to the goal
items:
type: string
example:
success: true
statusCode: 20000
statusText: OK
service: statistics-goals-api
data:
goal:
id: 5665cef556ddff22606fc8f6c0004807
owner_id: 987654
title: Some example goal
type:
name: Deals started
params:
pipeline_id:
- 5
- 2
activity_type_id:
- 9
assignee:
type: company
id: 123456
interval: weekly
duration:
start: '2019-11-01'
end: '2020-10-30'
expected_outcome:
target: 100
tracking_metric: quantity
is_active: false
report_ids:
- f37bd66a2ab64d28ff6a9b6d2289813a
/goals/find:
get:
summary: Find goals
description: 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.
x-token-cost: 20
operationId: getGoals
tags:
- Goals
security:
- api_key: []
- oauth2:
- goals:read
- goals:full
parameters:
- in: query
name: type.name
schema:
type: string
enum:
- deals_won
- deals_progressed
- activities_completed
- activities_added
- deals_started
description: The type of the goal. If provided, everyone's goals will be returned.
- in: query
name: title
schema:
type: string
description: The title of the goal
- in: query
name: is_active
schema:
type: boolean
default: true
description: Whether the goal is active or not
- in: query
name: assignee.id
schema:
type: integer
description: The ID of the user who's goal to fetch. When omitted, only your goals will be returned.
- in: query
name: assignee.type
schema:
type: string
enum:
- person
- company
- team
description: The type of the goal's assignee. If provided, everyone's goals will be returned.
- in: query
name: expected_outcome.target
schema:
type: number
description: The numeric value of the outcome. If provided, everyone's goals will be returned.
- in: query
name: expected_outcome.tracking_metric
schema:
type: string
enum:
- quantity
- sum
description: The tracking metric of the expected outcome of the goal. If provided, everyone's goals will be returned.
- in: query
name: expected_outcome.currency_id
schema:
type: integer
description: 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.
- in: query
name: type.params.pipeline_id
schema:
type: array
items:
type: integer
description: An array of pipeline IDs or `null` for all pipelines. If provided, everyone's goals will be returned.
- in: query
name: type.params.stage_id
schema:
type: integer
description: The ID of the stage. Applicable to only `deals_progressed` type of goals. If provided, everyone's goals will be returned.
- in: query
name: type.params.activity_type_id
schema:
type: array
items:
type: integer
description: 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.
- in: query
name: period.start
schema:
type: string
format: date
description: 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.
- in: query
name: period.end
schema:
type: string
format: date
description: The end date of the period for which to find goals. Date in format of YYYY-MM-DD.
responses:
'200':
description: Successful response containing payload in the `data.goal` object
content:
application/json:
schema:
title: GetGoalsResponse
type: object
properties:
success:
type: boolean
description: If the request was successful or not
data:
type: object
properties:
goals:
type: array
items:
type: object
title: Goal
properties:
id:
type: string
description: The ID of the goal
owner_id:
type: integer
description: The ID of the creator of the goal
title:
type: string
description: The title of the goal
type:
type: object
description: The type of the goal
properties:
name:
type: string
description: The name of the goal type
params:
type: object
description: The parameters that accompany the goal type
properties:
pipeline_id:
type: array
description: The IDs of pipelines of the goal
items:
type: integer
activity_type_id:
type: array
description: The IDs of activity types of the goal
items:
type: integer
assignee:
type: object
description: Who the goal is assigned to
properties:
id:
type: integer
description: The ID of the goal assignee
type:
type: string
description: The type of the assignee
interval:
type: string
description: The interval of the goal
duration:
type: object
description: The duration of the goal
properties:
start:
type: string
description: The start date of the goal
end:
type: string
description: The end date of the goal
expected_outcome:
type: object
description: The expected outcome of the goal
properties:
target:
type: integer
description: The numeric target of the goal
tracking_metric:
type: string
description: The tracking metric of the goal
is_active:
type: boolean
description: Whether the goal is currently active or not
report_ids:
type: array
description: The IDs of the reports that belong to the goal
items:
type: string
example:
success: true
statusCode: 20000
statusText: OK
service: statistics-goals-api
data:
goals:
- id: 5665cef556ddff22606fc8f6c0004807
owner_id: 987654
title: Some example goal
type:
name: Deals started
params:
pipeline_id:
- 5
- 2
activity_type_id:
- 9
assignee:
type: company
id: 123456
interval: weekly
duration:
start: '2019-11-01'
end: '2020-10-30'
expected_outcome:
target: 100
tracking_metric: quantity
is_active: false
report_ids:
- f37bd66a2ab64d28ff6a9b6d2289813a
/goals/{id}:
put:
summary: Update existing goal
description: Updates an existing goal.
x-token-cost: 10
operationId: updateGoal
tags:
- Goals
security:
- api_key: []
- oauth2:
- goals:full
parameters:
- in: path
name: id
required: true
schema:
type: string
description: The ID of the goal
requestBody:
content:
application/json:
schema:
title: basicGoalRequest
type: object
properties:
title:
type: string
description: The title of the goal
assignee:
type: object
description: '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:
type: object
description: '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:
type: object
description: '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:
type: object
description: '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:
type: string
enum:
- weekly
- monthly
- quarterly
- yearly
description: The interval of the goal
responses:
'200':
description: Successful response containing payload in the `data.goal` object
content:
application/json:
schema:
title: UpsertGoalResponse
type: object
properties:
success:
type: boolean
description: If the request was successful or not
data:
type: object
properties:
goal:
type: object
title: Goal
properties:
id:
type: string
description: The ID of the goal
owner_id:
type: integer
description: The ID of the creator of the goal
title:
type: string
description: The title of the goal
type:
type: object
description: The type of the goal
properties:
name:
type: string
description: The name of the goal type
params:
type: object
description: The parameters that accompany the goal type
properties:
pipeline_id:
type: array
description: The IDs of pipelines of the goal
items:
type: integer
activity_type_id:
type: array
description: The IDs of activity types of the goal
items:
type: integer
assignee:
type: object
description: Who the goal is assigned to
properties:
id:
type: integer
description: The ID of the goal assignee
type:
type: string
description: The type of the assignee
interval:
type: string
description: The interval of the goal
duration:
type: object
description: The duration of the goal
properties:
start:
type: string
description: The start date of the goal
end:
type: string
description: The end date of the goal
expected_outcome:
type: object
description: The expected outcome of the goal
properties:
target:
type: integer
description: The numeric target of the goal
tracking_metric:
type: string
description: The tracking metric of the goal
is_active:
type: boolean
description: Whether the goal is currently active or not
report_ids:
type: array
description: The IDs of the reports that belong to the goal
items:
type: string
example:
success: true
statusCode: 20000
statusText: OK
service: statistics-goals-api
data:
goal:
id: 5665cef556ddff22606fc8f6c0004807
owner_id: 987654
title: Some example goal
type:
name: Deals started
params:
pipeline_id:
- 5
- 2
activity_type_id:
- 9
assignee:
type: company
id: 123456
interval: weekly
duration:
start: '2019-11-01'
end: '2020-10-30'
expected_outcome:
target: 100
tracking_metric: quantity
is_active: false
report_ids:
- f37bd66a2ab64d28ff6a9b6d2289813a
delete:
summary: Delete existing goal
description: Marks a goal as deleted.
x-token-cost: 6
operationId: deleteGoal
tags:
- Goals
security:
- api_key: []
- oauth2:
- goals:full
parameters:
- in: path
name: id
required: true
schema:
type: string
description: The ID of the goal
responses:
'200':
description: Successful response with id 'success' field only
content:
application/json:
schema:
title: DeleteGoalResponse
type: object
properties:
success:
type: boolean
description: If the request was successful or not
example:
success: true
statusCode: 20000
statusText: OK
service: statistics-goals-api
/goals/{id}/results:
get:
summary: Get result of a goal
description: Gets the progress of a goal for the specified period.
x-token-cost: 20
operationId: getGoalResult
tags:
- Goals
security:
- api_key: []
- oauth2:
- goals:read
- goals:full
parameters:
- in: path
name: id
required: true
schema:
type: string
description: The ID of the goal that the results are looked for
- in: query
name: period.start
required: true
schema:
type: string
format: date
description: '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.
'
- in: query
name: period.end
required: true
schema:
type: string
format: date
description: '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.
'
responses:
'200':
description: Successful response containing payload in the `data.goal` object
content:
application/json:
schema:
title: GetGoalResultResponse
type: object
properties:
success:
type: boolean
description: If the request was successful or not
data:
type: object
properties:
progress:
type: integer
description: The numeric progress of the goal
goal:
type: object
title: Goal
properties:
id:
type: string
description: The ID of the goal
owner_id:
type: integer
description: The ID of the creator of the goal
title:
type: string
description: The title of the goal
type:
type: object
description: The type of the goal
properties:
name:
type: string
description: The name of the goal type
params:
type: object
description: The parameters that accompany the goal type
properties:
pipeline_id:
type: array
description: The IDs of pipelines of the goal
items:
type: integer
activity_type_id:
type: array
description: The IDs of activity types of the goal
items:
type: integer
assignee:
type: object
description: Who the goal is assigned to
properties:
id:
type: integer
description: The ID of the goal assignee
type:
type: string
description: The type of the assignee
interval:
type: string
description: The interval of the goal
duration:
type: object
description: The duration of the goal
properties:
start:
type: string
description: The start date of the goal
end:
type: string
description: The end date of the goal
expected_outcome:
type: object
description: The expected outcome of the goal
properties:
target:
type: integer
description: The numeric target of the goal
tracking_metric:
type: string
description: The tracking metric of the goal
is_active:
type: boolean
description: Whether the goal is currently active or not
report_ids:
type: array
description: The IDs of the
# --- truncated at 32 KB (37 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/pipedrive/refs/heads/main/openapi/pipedrive-goals-api-openapi.yml