Pipedrive Projects API

openapi: 3.0.1
info:
  title: Pipedrive API v1 Activities Projects 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: Projects
  description: 'Projects represent ongoing, completed or canceled projects attached to an organization, person or to deals. Each project has an owner and must be placed in a phase. Each project consists of standard data fields but can also contain a number of custom fields. The custom fields can be recognized by long hashes as keys.

    '
paths:
  /projects:
    get:
      summary: Get all projects
      description: Returns all projects. This is a cursor-paginated endpoint. For more information, please refer to our documentation on <a href="https://pipedrive.readme.io/docs/core-api-concepts-pagination" target="_blank" rel="noopener noreferrer">pagination</a>.
      x-token-cost: 20
      operationId: getProjects
      tags:
      - Projects
      security:
      - api_key: []
      - oauth2:
        - projects:read
        - projects:full
      parameters:
      - in: query
        name: cursor
        required: false
        description: For pagination, the marker (an opaque string value) representing the first item on the next page
        schema:
          type: string
      - in: query
        name: limit
        required: false
        description: For pagination, the limit of entries to be returned. If not provided, 100 items will be returned.
        schema:
          type: integer
          example: 100
      - in: query
        name: filter_id
        required: false
        schema:
          type: integer
        description: The ID of the filter to use
      - in: query
        name: status
        required: false
        description: If supplied, includes only projects with the specified statuses. Possible values are `open`, `completed`, `canceled` and `deleted`. By default `deleted` projects are not returned.
        schema:
          type: string
          example: open,completed
      - in: query
        name: phase_id
        required: false
        schema:
          type: integer
        description: If supplied, only projects in specified phase are returned
      - in: query
        name: include_archived
        required: false
        schema:
          type: boolean
        description: If supplied with `true` then archived projects are also included in the response. By default only not archived projects are returned.
      responses:
        '200':
          description: A list of projects.
          content:
            application/json:
              schema:
                title: GetProjectsResponse
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      title: projectResponseObject
                      allOf:
                      - type: object
                        title: ProjectId
                        properties:
                          id:
                            type: integer
                            description: The ID of the project, generated when the task was created
                      - title: Project
                        type: object
                        allOf:
                        - type: object
                          properties:
                            title:
                              description: The title of the project
                              type: string
                        - type: object
                          properties:
                            board_id:
                              description: The ID of the board this project is associated with
                              type: number
                            phase_id:
                              description: The ID of the phase this project is associated with
                              type: number
                            description:
                              description: The description of the project
                              type: string
                            status:
                              description: The status of the project
                              type: string
                            owner_id:
                              description: The ID of a project owner
                              type: number
                            start_date:
                              description: 'The start date of the project. Format: YYYY-MM-DD.'
                              type: string
                              format: date
                            end_date:
                              description: 'The end date of the project. Format: YYYY-MM-DD.'
                              type: string
                              format: date
                            deal_ids:
                              description: An array of IDs of the deals this project is associated with
                              type: array
                              items:
                                type: integer
                            org_id:
                              description: The ID of the organization this project is associated with
                              type: number
                            person_id:
                              description: The ID of the person this project is associated with
                              type: number
                            labels:
                              description: An array of IDs of the labels this project has
                              type: array
                              items:
                                type: integer
                        - type: object
                          properties:
                            add_time:
                              type: string
                              description: 'The creation date and time of the project in UTC. Format: YYYY-MM-DD HH:MM:SS.'
                            update_time:
                              type: string
                              description: 'The update date and time of the project in UTC. Format: YYYY-MM-DD HH:MM:SS.'
                            status_change_time:
                              type: string
                              description: 'The status changed date and time of the project in UTC. Format: YYYY-MM-DD HH:MM:SS.'
                            archive_time:
                              type: string
                              description: 'The archived date and time of the project in UTC. Format: YYYY-MM-DD HH:MM:SS. If not archived then ''null''.'
                  additional_data:
                    description: The additional data of the list
                    type: object
                    properties:
                      next_cursor:
                        type: string
                        description: The first item on the next page. The value of the `next_cursor` field will be `null` if you have reached the end of the dataset and there’s no more pages to be returned.
              example:
                success: true
                data:
                - id: 8
                  title: Project
                  description: Project Description
                  status: open
                  status_change_time: '2023-09-12 11:12:18.110'
                  start_date: '2023-09-18'
                  end_date: '2024-03-04'
                  owner_id: 19
                  add_time: '2023-09-12 11:12:18.110'
                  update_time: '2023-09-14 05:45:40.084'
                  labels:
                  - 13
                  - 14
                  archive_time: '2023-09-15 11:12:18.110'
                  deal_ids:
                  - 1
                  - 2
                  person_id: 2
                  org_id: 3
                  board_id: 1
                  phase_id: 1
                additional_data:
                  next_cursor: eyJhY3Rpdml0aWVzIjoyN30
    post:
      summary: Add a project
      description: Adds a new project. Note that you can supply additional custom fields along with the request that are not described here. These custom fields are different for each Pipedrive account and can be recognized by long hashes as keys.
      x-token-cost: 10
      operationId: addProject
      tags:
      - Projects
      security:
      - api_key: []
      - oauth2:
        - projects:full
      requestBody:
        content:
          application/json:
            schema:
              title: addProjectRequest
              allOf:
              - title: requiredPostProjectParameters
                type: object
                required:
                - title
                properties:
                  title:
                    description: The title of the project
                    type: string
              - type: object
                properties:
                  board_id:
                    description: The ID of the board this project is associated with
                    type: number
                  phase_id:
                    description: The ID of the phase this project is associated with
                    type: number
                  description:
                    description: The description of the project
                    type: string
                  status:
                    description: The status of the project
                    type: string
                  owner_id:
                    description: The ID of a project owner
                    type: number
                  start_date:
                    description: 'The start date of the project. Format: YYYY-MM-DD.'
                    type: string
                    format: date
                  end_date:
                    description: 'The end date of the project. Format: YYYY-MM-DD.'
                    type: string
                    format: date
                  deal_ids:
                    description: An array of IDs of the deals this project is associated with
                    type: array
                    items:
                      type: integer
                  org_id:
                    description: The ID of the organization this project is associated with
                    type: number
                  person_id:
                    description: The ID of the person this project is associated with
                    type: number
                  labels:
                    description: An array of IDs of the labels this project has
                    type: array
                    items:
                      type: integer
              - type: object
                properties:
                  template_id:
                    description: The ID of the template the project will be based on
                    type: number
      responses:
        '201':
          description: Created project.
          content:
            application/json:
              schema:
                title: AddProjectResponse
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    title: projectResponseObject
                    allOf:
                    - type: object
                      title: ProjectId
                      properties:
                        id:
                          type: integer
                          description: The ID of the project, generated when the task was created
                    - title: Project
                      type: object
                      allOf:
                      - type: object
                        properties:
                          title:
                            description: The title of the project
                            type: string
                      - type: object
                        properties:
                          board_id:
                            description: The ID of the board this project is associated with
                            type: number
                          phase_id:
                            description: The ID of the phase this project is associated with
                            type: number
                          description:
                            description: The description of the project
                            type: string
                          status:
                            description: The status of the project
                            type: string
                          owner_id:
                            description: The ID of a project owner
                            type: number
                          start_date:
                            description: 'The start date of the project. Format: YYYY-MM-DD.'
                            type: string
                            format: date
                          end_date:
                            description: 'The end date of the project. Format: YYYY-MM-DD.'
                            type: string
                            format: date
                          deal_ids:
                            description: An array of IDs of the deals this project is associated with
                            type: array
                            items:
                              type: integer
                          org_id:
                            description: The ID of the organization this project is associated with
                            type: number
                          person_id:
                            description: The ID of the person this project is associated with
                            type: number
                          labels:
                            description: An array of IDs of the labels this project has
                            type: array
                            items:
                              type: integer
                      - type: object
                        properties:
                          add_time:
                            type: string
                            description: 'The creation date and time of the project in UTC. Format: YYYY-MM-DD HH:MM:SS.'
                          update_time:
                            type: string
                            description: 'The update date and time of the project in UTC. Format: YYYY-MM-DD HH:MM:SS.'
                          status_change_time:
                            type: string
                            description: 'The status changed date and time of the project in UTC. Format: YYYY-MM-DD HH:MM:SS.'
                          archive_time:
                            type: string
                            description: 'The archived date and time of the project in UTC. Format: YYYY-MM-DD HH:MM:SS. If not archived then ''null''.'
                  additional_data:
                    type: object
                    nullable: true
                    example: null
              example:
                success: true
                data:
                  id: 8
                  title: Project
                  description: Project Description
                  status: open
                  status_change_time: '2023-09-12 11:12:18.110'
                  start_date: '2023-09-18'
                  end_date: '2024-03-04'
                  owner_id: 19
                  add_time: '2023-09-12 11:12:18.110'
                  update_time: '2023-09-14 05:45:40.084'
                  labels:
                  - 13
                  - 14
                  archive_time: '2023-09-15 11:12:18.110'
                  deal_ids:
                  - 1
                  - 2
                  person_id: 2
                  org_id: 3
                  board_id: 1
                  phase_id: 1
                additional_data: null
  /projects/{id}:
    get:
      summary: Get details of a project
      description: Returns the details of a specific project. Also note that custom fields appear as long hashes in the resulting data. These hashes can be mapped against the `key` value of project fields.
      x-token-cost: 2
      operationId: getProject
      tags:
      - Projects
      security:
      - api_key: []
      - oauth2:
        - projects:read
        - projects:full
      parameters:
      - in: path
        name: id
        description: The ID of the project
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Get a project.
          content:
            application/json:
              schema:
                title: GetProjectResponse
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    title: projectResponseObject
                    allOf:
                    - type: object
                      title: ProjectId
                      properties:
                        id:
                          type: integer
                          description: The ID of the project, generated when the task was created
                    - title: Project
                      type: object
                      allOf:
                      - type: object
                        properties:
                          title:
                            description: The title of the project
                            type: string
                      - type: object
                        properties:
                          board_id:
                            description: The ID of the board this project is associated with
                            type: number
                          phase_id:
                            description: The ID of the phase this project is associated with
                            type: number
                          description:
                            description: The description of the project
                            type: string
                          status:
                            description: The status of the project
                            type: string
                          owner_id:
                            description: The ID of a project owner
                            type: number
                          start_date:
                            description: 'The start date of the project. Format: YYYY-MM-DD.'
                            type: string
                            format: date
                          end_date:
                            description: 'The end date of the project. Format: YYYY-MM-DD.'
                            type: string
                            format: date
                          deal_ids:
                            description: An array of IDs of the deals this project is associated with
                            type: array
                            items:
                              type: integer
                          org_id:
                            description: The ID of the organization this project is associated with
                            type: number
                          person_id:
                            description: The ID of the person this project is associated with
                            type: number
                          labels:
                            description: An array of IDs of the labels this project has
                            type: array
                            items:
                              type: integer
                      - type: object
                        properties:
                          add_time:
                            type: string
                            description: 'The creation date and time of the project in UTC. Format: YYYY-MM-DD HH:MM:SS.'
                          update_time:
                            type: string
                            description: 'The update date and time of the project in UTC. Format: YYYY-MM-DD HH:MM:SS.'
                          status_change_time:
                            type: string
                            description: 'The status changed date and time of the project in UTC. Format: YYYY-MM-DD HH:MM:SS.'
                          archive_time:
                            type: string
                            description: 'The archived date and time of the project in UTC. Format: YYYY-MM-DD HH:MM:SS. If not archived then ''null''.'
                  additional_data:
                    type: object
                    nullable: true
                    example: null
              example:
                success: true
                data:
                  id: 8
                  title: Project
                  description: Project Description
                  status: open
                  status_change_time: '2023-09-12 11:12:18.110'
                  start_date: '2023-09-18'
                  end_date: '2024-03-04'
                  owner_id: 19
                  add_time: '2023-09-12 11:12:18.110'
                  update_time: '2023-09-14 05:45:40.084'
                  labels:
                  - 13
                  - 14
                  archive_time: '2023-09-15 11:12:18.110'
                  deal_ids:
                  - 1
                  - 2
                  person_id: 2
                  org_id: 3
                  board_id: 1
                  phase_id: 1
                additional_data: null
    put:
      summary: Update a project
      description: Updates a project.
      x-token-cost: 10
      operationId: updateProject
      tags:
      - Projects
      security:
      - api_key: []
      - oauth2:
        - projects:full
      parameters:
      - in: path
        name: id
        description: The ID of the project
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              title: updateProjectRequest
              allOf:
              - type: object
                properties:
                  title:
                    description: The title of the project
                    type: string
              - type: object
                properties:
                  board_id:
                    description: The ID of the board this project is associated with
                    type: number
                  phase_id:
                    description: The ID of the phase this project is associated with
                    type: number
                  description:
                    description: The description of the project
                    type: string
                  status:
                    description: The status of the project
                    type: string
                  owner_id:
                    description: The ID of a project owner
                    type: number
                  start_date:
                    description: 'The start date of the project. Format: YYYY-MM-DD.'
                    type: string
                    format: date
                  end_date:
                    description: 'The end date of the project. Format: YYYY-MM-DD.'
                    type: string
                    format: date
                  deal_ids:
                    description: An array of IDs of the deals this project is associated with
                    type: array
                    items:
                      type: integer
                  org_id:
                    description: The ID of the organization this project is associated with
                    type: number
                  person_id:
                    description: The ID of the person this project is associated with
                    type: number
                  labels:
                    description: An array of IDs of the labels this project has
                    type: array
                    items:
                      type: integer
      responses:
        '200':
          description: Updated project.
          content:
            application/json:
              schema:
                title: UpdateProjectResponse
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    title: projectResponseObject
                    allOf:
                    - type: object
                      title: ProjectId
                      properties:
                        id:
                          type: integer
                          description: The ID of the project, generated when the task was created
                    - title: Project
                      type: object
                      allOf:
                      - type: object
                        properties:
                          title:
                            description: The title of the project
                            type: string
                      - type: object
                        properties:
                          board_id:
                            description: The ID of the board this project is associated with
                            type: number
                          phase_id:
                            description: The ID of the phase this project is associated with
                            type: number
                          description:
                            description: The description of the project
                            type: string
                          status:
                            description: The status of the project
                            type: string
                          owner_id:
                            description: The ID of a project owner
                            type: number
                          start_date:
                            description: 'The start date of the project. Format: YYYY-MM-DD.'
                            type: string
                            format: date
                          end_date:
                            description: 'The end date of the project. Format: YYYY-MM-DD.'
                            type: string
                            format: date
                          deal_ids:
                            description: An array of IDs of the deals this project is associated with
                            type: array
                            items:
                              type: integer
                          org_id:
                            description: The ID of the organization this project is associated with
                            type: number
                          person_id:
                            description: The ID of the person this project is associated with
                            type: number
                          labels:
                            description: An array of IDs of the labels this project has
                            type: array
                            items:
                              type: integer
                      - type: object
                        properties:
                          add_time:
                            type: string
                            description: 'The creation date and time of the project in UTC. Format: YYYY-MM-DD HH:MM:SS.'
                          update_time:
                            type: string
                            description: 'The update date and time of the project in UTC. Format: YYYY-MM-DD HH:MM:SS.'
                          status_change_time:
                            type: string
                            description: 'The status changed date and time of the project in UTC. Format: YYYY-MM-DD HH:MM:SS.'
                          archive_time:
                            type: string
                            description: 'The archived date and time of the project in UTC. Format: YYYY-MM-DD HH:MM:SS. If not archived then ''null''.'
                  additional_data:
                    type: object
                    nullable: true
                    example: null
              example:
                success: true
                data:
                  id: 8
                  title: Project
                  description: Project Description
                  status: open
                  status_change_time: '2023-09-12 11:12:18.110'
                  start_date: '2023-09-18'
                  end_date: '2024-03-04'
                  owner_id: 19
                  add_time: '2023-09-12 11:12:18.110'
                  update_time: '2023-09-14 05:45:40.084'
                  labels:
                  - 13
                  - 14
                  archive_time: '2023-09-15 11:12:18.110'
                  deal_ids:
                  - 1
                  - 2
                  person_id: 2
                  org_id: 3
                  board_id: 1
                  phase_id: 1
                additional_data: null
    delete:
      summary: Delete a project
      description: Marks a project as deleted.
      x-token-cost: 6
      operationId: deleteProject
      tags:
      - Projects
      security:
      - api_key: []
      - oauth2:
        - projects:full
      parameters:
      - in: path
        name: id
        description: The ID of the project
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Delete a project.
          content:
            application/json:
              schema:
                title: DeleteProjectResponse
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    title: deleteProject
                    type: object
                    properties:
                      success:
                        type: boolean
                        description: If the request was successful or not
                      data:
                        type: object
                        properties:
                          id:
                            type: integer
                            description: The ID of the project that was deleted
                  additional_data:
                    type: object
                    nullable: true
                    example: null
              example:
                success: true
                data:
                  id: 8
                additional_data: null
    patch:
      summary: Update a project
      description: Updates the properties of a project.
      x-token-cost: 5
      operationId: updateProject
      tags:
      - Projects
      security:
      - api_key: []
      - oauth2:
        - projects:full
      parameters:
      - in: path
        name: id
        description: The ID of the project
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                  description: The title of the project
                description:
                  type: string
                  description: The description of the project
                status:
                  type: string
                  description: The status of the project
                board_id:
                  type: integer
                  description: The ID of the board this project is associated with
                phase_id:
                  type: integer
                  description: The ID of the phase this project is associated with
                owner_id:
                  type: integer
                  description: The ID of the user who owns the project
                start_date:
                  type: string
                  format: date
                  description: 'The start date of the project. Format: YYYY-MM-DD'
                end_date:
                  type: string
                  format: date
                  description: 'The end date of the project. Format: YYYY-MM-DD'
                deal_ids:
                  type: array
                  description: An array of IDs of the d

# --- truncated at 32 KB (95 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/pipedrive/refs/heads/main/openapi/pipedrive-projects-api-openapi.yml