openapi: 3.0.1
info:
title: Pipedrive API v1 Activities ProjectPhases 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: ProjectPhases
description: 'Project phases represent the stages within a project board. Each phase belongs to a board and defines a step in the project workflow.
'
paths:
/projects/phases:
get:
summary: Get project phases
description: Returns all active project phases under a specific board.
x-token-cost: 20
operationId: getProjectsPhases
tags:
- ProjectPhases
security:
- api_key: []
- oauth2:
- projects:read
- projects:full
parameters:
- in: query
name: board_id
required: true
description: ID of the board for which phases are requested
schema:
type: integer
example: 1
responses:
'200':
description: A list of project phases.
content:
application/json:
schema:
title: GetProjectPhasesResponse
type: object
properties:
success:
type: boolean
data:
type: array
items:
type: object
properties:
id:
type: integer
description: The ID of the project phase
name:
description: Name of a project phase
type: string
board_id:
description: The ID of the project board this phase is linked to
type: number
order_nr:
description: The order of a phase
type: number
add_time:
type: string
description: 'The creation date and time of the board in UTC. Format: YYYY-MM-DD HH:MM:SS.'
update_time:
type: string
description: 'The update date and time of the board in UTC. Format: YYYY-MM-DD HH:MM:SS.'
additional_data:
type: object
nullable: true
example: null
example:
success: true
data:
- id: 2
name: Project Phase
board_id: 1
order_nr: 2
add_time: '2023-09-12 11:12:18'
update_time: '2023-09-14 05:45:40'
additional_data: null
/projects/phases/{id}:
get:
summary: Get details of a phase
description: Returns the details of a specific project phase.
x-token-cost: 2
operationId: getProjectsPhase
tags:
- ProjectPhases
security:
- api_key: []
- oauth2:
- projects:read
parameters:
- in: path
name: id
description: The ID of the project phase
required: true
schema:
type: integer
responses:
'200':
description: Get a project phase.
content:
application/json:
schema:
title: GetProjectPhaseResponse
type: object
properties:
success:
type: boolean
data:
type: object
properties:
id:
type: integer
description: The ID of the project phase
name:
description: Name of a project phase
type: string
board_id:
description: The ID of the project board this phase is linked to
type: number
order_nr:
description: The order of a phase
type: number
add_time:
type: string
description: 'The creation date and time of the board in UTC. Format: YYYY-MM-DD HH:MM:SS.'
update_time:
type: string
description: 'The update date and time of the board in UTC. Format: YYYY-MM-DD HH:MM:SS.'
additional_data:
type: object
nullable: true
example: null
example:
success: true
data:
id: 2
name: Project Phase
board_id: 1
order_nr: 2
add_time: '2023-09-12 11:12:18'
update_time: '2023-09-14 05:45:40'
additional_data: null
/phases:
get:
summary: Get project phases
description: Returns all active project phases under a specific board.
x-token-cost: 10
operationId: getProjectsPhases
tags:
- ProjectPhases
security:
- api_key: []
- oauth2:
- projects:read
- projects:full
parameters:
- in: query
name: board_id
required: true
description: The ID of the board for which phases are requested
schema:
type: integer
example: 1
responses:
'200':
description: Get all project phases for a board
content:
application/json:
schema:
title: GetProjectPhasesResponse
type: object
properties:
success:
type: boolean
description: If the response is successful or not
data:
type: array
description: The array of project phases
items:
type: object
properties:
id:
type: integer
description: The ID of the project phase
name:
type: string
description: The name of the project phase
board_id:
type: integer
description: The ID of the project board this phase belongs to
order_nr:
type: integer
description: The order of the phase within its board
add_time:
type: string
description: The creation date and time of the phase in ISO 8601 format
update_time:
type: string
description: The update date and time of the phase in ISO 8601 format
additional_data:
type: object
nullable: true
example:
success: true
data:
- id: 2
name: Project Phase
board_id: 1
order_nr: 1
add_time: '2024-01-01T00:00:00.000Z'
update_time: '2024-01-01T00:00:00.000Z'
additional_data: null
post:
summary: Add a project phase
description: Adds a new project phase to a board.
x-token-cost: 5
operationId: addProjectPhase
tags:
- ProjectPhases
security:
- api_key: []
- oauth2:
- projects:full
requestBody:
required: true
content:
application/json:
schema:
title: addProjectPhaseRequest
required:
- name
- board_id
type: object
properties:
name:
type: string
description: The name of the project phase
board_id:
type: integer
description: The ID of the project board to add the phase to
order_nr:
type: integer
minimum: 1
description: The order of the phase within its board. Must be between 1 and the total number of phases on the board + 1.
responses:
'200':
description: Add a project phase
content:
application/json:
schema:
title: UpsertProjectPhaseResponse
type: object
properties:
success:
type: boolean
description: If the response is successful or not
data:
type: object
properties:
id:
type: integer
description: The ID of the project phase
name:
type: string
description: The name of the project phase
board_id:
type: integer
description: The ID of the project board this phase belongs to
order_nr:
type: integer
description: The order of the phase within its board
add_time:
type: string
description: The creation date and time of the phase in ISO 8601 format
update_time:
type: string
description: The update date and time of the phase in ISO 8601 format
example:
success: true
data:
id: 2
name: Project Phase
board_id: 1
order_nr: 1
add_time: '2024-01-01T00:00:00.000Z'
update_time: '2024-01-01T00:00:00.000Z'
/phases/{id}:
get:
summary: Get details of a project phase
description: Returns the details of a specific project phase.
x-token-cost: 10
operationId: getProjectsPhase
tags:
- ProjectPhases
security:
- api_key: []
- oauth2:
- projects:read
- projects:full
parameters:
- in: path
name: id
description: The ID of the project phase
required: true
schema:
type: integer
responses:
'200':
description: Get a project phase
content:
application/json:
schema:
title: UpsertProjectPhaseResponse
type: object
properties:
success:
type: boolean
description: If the response is successful or not
data:
type: object
properties:
id:
type: integer
description: The ID of the project phase
name:
type: string
description: The name of the project phase
board_id:
type: integer
description: The ID of the project board this phase belongs to
order_nr:
type: integer
description: The order of the phase within its board
add_time:
type: string
description: The creation date and time of the phase in ISO 8601 format
update_time:
type: string
description: The update date and time of the phase in ISO 8601 format
example:
success: true
data:
id: 2
name: Project Phase
board_id: 1
order_nr: 1
add_time: '2024-01-01T00:00:00.000Z'
update_time: '2024-01-01T00:00:00.000Z'
patch:
summary: Update a project phase
description: Updates the properties of a project phase.
x-token-cost: 5
operationId: updateProjectPhase
tags:
- ProjectPhases
security:
- api_key: []
- oauth2:
- projects:full
parameters:
- in: path
name: id
description: The ID of the project phase
required: true
schema:
type: integer
requestBody:
content:
application/json:
schema:
title: updateProjectPhaseRequest
type: object
properties:
name:
type: string
description: The name of the project phase
board_id:
type: integer
description: The ID of the project board to add the phase to
order_nr:
type: integer
minimum: 1
description: The order of the phase within its board. Must be between 1 and the total number of phases on the board + 1.
responses:
'200':
description: Update a project phase
content:
application/json:
schema:
title: UpsertProjectPhaseResponse
type: object
properties:
success:
type: boolean
description: If the response is successful or not
data:
type: object
properties:
id:
type: integer
description: The ID of the project phase
name:
type: string
description: The name of the project phase
board_id:
type: integer
description: The ID of the project board this phase belongs to
order_nr:
type: integer
description: The order of the phase within its board
add_time:
type: string
description: The creation date and time of the phase in ISO 8601 format
update_time:
type: string
description: The update date and time of the phase in ISO 8601 format
example:
success: true
data:
id: 2
name: Project Phase
board_id: 1
order_nr: 1
add_time: '2024-01-01T00:00:00.000Z'
update_time: '2024-01-01T00:00:00.000Z'
delete:
summary: Delete a project phase
description: Marks a project phase as deleted.
x-token-cost: 3
operationId: deleteProjectPhase
tags:
- ProjectPhases
security:
- api_key: []
- oauth2:
- projects:full
parameters:
- in: path
name: id
description: The ID of the project phase
required: true
schema:
type: integer
responses:
'200':
description: Delete a project phase
content:
application/json:
schema:
title: DeleteProjectPhaseResponse
type: object
properties:
success:
type: boolean
description: If the response is successful or not
data:
type: object
properties:
id:
type: integer
description: The ID of the deleted project phase
example:
success: true
data:
id: 2
components:
securitySchemes:
basic_authentication:
type: http
scheme: basic
description: Base 64 encoded string containing the `client_id` and `client_secret` values. The header value should be `Basic <base64(client_id:client_secret)>`.
api_key:
type: apiKey
name: x-api-token
in: header
oauth2:
type: oauth2
description: For more information, see https://pipedrive.readme.io/docs/marketplace-oauth-authorization
flows:
authorizationCode:
authorizationUrl: https://oauth.pipedrive.com/oauth/authorize
tokenUrl: https://oauth.pipedrive.com/oauth/token
refreshUrl: https://oauth.pipedrive.com/oauth/token
scopes:
base: Read settings of the authorized user and currencies in an account
deals:read: Read most of the data about deals and related entities - deal fields, products, followers, participants; all notes, files, filters, pipelines, stages, and statistics. Does not include access to activities (except the last and next activity related to a deal)
deals:full: Create, read, update and delete deals, its participants and followers; all files, notes, and filters. It also includes read access to deal fields, pipelines, stages, and statistics. Does not include access to activities (except the last and next activity related to a deal)
mail:read: Read mail threads and messages
mail:full: Read, update and delete mail threads. Also grants read access to mail messages
activities:read: Read activities, its fields and types; all files and filters
activities:full: Create, read, update and delete activities and all files and filters. Also includes read access to activity fields and types
contacts:read: Read the data about persons and organizations, their related fields and followers; also all notes, files, filters
contacts:full: Create, read, update and delete persons and organizations and their followers; all notes, files, filters. Also grants read access to contacts-related fields
products:read: Read products, its fields, files, followers and products connected to a deal
products:full: Create, read, update and delete products and its fields; add products to deals
deal-fields:full: Create, read, update and delete deal fields
product-fields:full: Create, read, update and delete product fields
contact-fields:full: Create, read, update and delete person and organization fields
projects:read: Read projects and its fields, tasks and project templates
projects:full: Create, read, update and delete projects and its fields; add projects templates and project related tasks
users:read: Read data about users (people with access to a Pipedrive account), their permissions, roles and followers
recents:read: Read all recent changes occurred in an account. Includes data about activities, activity types, deals, files, filters, notes, persons, organizations, pipelines, stages, products and users
search:read: Search across the account for deals, persons, organizations, files and products, and see details about the returned results
admin: Allows to do many things that an administrator can do in a Pipedrive company account - create, read, update and delete pipelines and its stages; deal, person and organization fields; activity types; users and permissions, etc. It also allows the app to create webhooks and fetch and delete webhooks that are created by the app
leads:read: Read data about leads and lead labels
leads:full: Create, read, update and delete leads and lead labels
phone-integration: Enables advanced call integration features like logging call duration and other metadata, and play call recordings inside Pipedrive
goals:read: Read data on all goals
goals:full: Create, read, update and delete goals
video-calls: Allows application to register as a video call integration provider and create conference links
messengers-integration: Allows application to register as a messengers integration provider and allows them to deliver incoming messages and their statuses