Projects

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.

Get all projects

Copy link

Returns all projects. This is a cursor-paginated endpoint. For more information, please refer to our documentation on pagination.

API v1
Request
GET

/v1/projects

Query parameters

cursor

string

For pagination, the marker (an opaque string value) representing the first item on the next page

limit

integer

For pagination, the limit of entries to be returned. If not provided, 100 items will be returned.

filter_id

integer

The ID of the filter to use

status

string

If supplied, includes only projects with the specified statuses. Possible values are open, completed, canceled and deleted. By default deleted projects are not returned.

phase_id

integer

If supplied, only projects in specified phase are returned

include_archived

boolean

If supplied with true then archived projects are also included in the response. By default only not archived projects are returned.

Response
200

OK

Expand all
Copy code
    • true
    • [ ... ]
      • { ... }

      Get details of a project

      Copy link

      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.

      API v1
      Request
      GET

      /v1/projects/{id}

      Path parameters

      id

      integer

      required

      The ID of the project

      Response
      200

      OK

      Expand all
      Copy code
        • true
        • { ... }
          • null

        Returns project plan

        Copy link

        Returns information about items in a project plan. Items consists of tasks and activities and are linked to specific project phase and group.

        API v1
        Request
        GET

        /v1/projects/{id}/plan

        Path parameters

        id

        integer

        required

        The ID of the project

        Response
        200

        OK

        Expand all
        Copy code
          • true
          • [ ... ]
            • null

          Returns project groups

          Copy link

          Returns all active groups under a specific project.

          API v1
          Request
          GET

          /v1/projects/{id}/groups

          Path parameters

          id

          integer

          required

          The ID of the project

          Response
          200

          OK

          Expand all
          Copy code
            • true
            • [ ... ]
              • null

            Returns project tasks

            Copy link

            Returns tasks linked to a specific project.

            API v1
            Request
            GET

            /v1/projects/{id}/tasks

            Path parameters

            id

            integer

            required

            The ID of the project

            Response
            200

            OK

            Expand all
            Copy code
              • true
              • [ ... ]
                • { ... }

                Returns project activities

                Copy link

                Returns activities linked to a specific project.

                API v1
                Request
                GET

                /v1/projects/{id}/activities

                Path parameters

                id

                integer

                required

                The ID of the project

                Response
                200

                OK

                Expand all
                Copy code
                  • true
                  • [ ... ]
                    • { ... }

                    Get all project boards

                    Copy link

                    Returns all projects boards that are not deleted.

                    API v1
                    Request
                    GET

                    /v1/projects/boards

                    Response
                    200

                    OK

                    Expand all
                    Copy code
                      • true
                      • [ ... ]
                        • null

                      Get details of a board

                      Copy link

                      Returns the details of a specific project board.

                      API v1
                      Request
                      GET

                      /v1/projects/boards/{id}

                      Path parameters

                      id

                      integer

                      required

                      The ID of the project board

                      Response
                      200

                      OK

                      Expand all
                      Copy code
                        • true
                        • { ... }
                          • null

                        Get project phases

                        Copy link

                        Returns all active project phases under a specific board.

                        API v1
                        Request
                        GET

                        /v1/projects/phases

                        Query parameters

                        board_id

                        integer

                        required

                        ID of the board for which phases are requested

                        Response
                        200

                        OK

                        Expand all
                        Copy code
                          • true
                          • [ ... ]
                            • null

                          Get details of a phase

                          Copy link

                          Returns the details of a specific project phase.

                          API v1
                          Request
                          GET

                          /v1/projects/phases/{id}

                          Path parameters

                          id

                          integer

                          required

                          The ID of the project phase

                          Response
                          200

                          OK

                          Expand all
                          Copy code
                            • true
                            • { ... }
                              • null

                            Add a project

                            Copy link

                            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.

                            API v1
                            Request
                            POST

                            /v1/projects

                            Body parameters

                            application/json

                            title

                            string

                            required

                            The title of the project

                            board_id

                            number

                            required

                            The ID of a project board

                            phase_id

                            number

                            required

                            The ID of a phase on a project board

                            description

                            string

                            The description of the project

                            status

                            string

                            The status of the project

                            owner_id

                            number

                            The ID of a project owner

                            start_date

                            string

                            The start date of the project. Format: YYYY-MM-DD.

                            Format

                            date

                            end_date

                            string

                            The end date of the project. Format: YYYY-MM-DD.

                            Format

                            date

                            deal_ids

                            array

                            An array of IDs of the deals this project is associated with

                            org_id

                            number

                            The ID of the organization this project is associated with

                            person_id

                            number

                            The ID of the person this project is associated with

                            labels

                            array

                            An array of IDs of the labels this project has

                            template_id

                            number

                            The ID of the template the project will be based on

                            Response
                            201

                            Created

                            Expand all
                            Copy code
                              • true
                              • { ... }
                                • null

                              Archive a project

                              Copy link

                              Archives a project.

                              API v1
                              Request
                              POST

                              /v1/projects/{id}/archive

                              Path parameters

                              id

                              integer

                              required

                              The ID of the project

                              Response
                              200

                              OK

                              Expand all
                              Copy code
                                • true
                                • { ... }
                                  • null

                                Update a project

                                Copy link

                                Updates a project.

                                API v1
                                Request
                                PUT

                                /v1/projects/{id}

                                Path parameters

                                id

                                integer

                                required

                                The ID of the project

                                Body parameters

                                application/json

                                title

                                string

                                The title of the project

                                board_id

                                number

                                The ID of the board this project is associated with

                                phase_id

                                number

                                The ID of the phase this project is associated with

                                description

                                string

                                The description of the project

                                status

                                string

                                The status of the project

                                owner_id

                                number

                                The ID of a project owner

                                start_date

                                string

                                The start date of the project. Format: YYYY-MM-DD.

                                Format

                                date

                                end_date

                                string

                                The end date of the project. Format: YYYY-MM-DD.

                                Format

                                date

                                deal_ids

                                array

                                An array of IDs of the deals this project is associated with

                                org_id

                                number

                                The ID of the organization this project is associated with

                                person_id

                                number

                                The ID of the person this project is associated with

                                labels

                                array

                                An array of IDs of the labels this project has

                                Response
                                200

                                OK

                                Expand all
                                Copy code
                                  • true
                                  • { ... }
                                    • null

                                  Update activity in project plan

                                  Copy link

                                  Updates an activity phase or group in a project.

                                  API v1
                                  Request
                                  PUT

                                  /v1/projects/{id}/plan/activities/{activityId}

                                  Path parameters

                                  id

                                  integer

                                  required

                                  The ID of the project

                                  activityId

                                  integer

                                  required

                                  The ID of the activity

                                  Body parameters

                                  application/json

                                  phase_id

                                  number

                                  The ID of a phase on a project board

                                  group_id

                                  number

                                  The ID of a group on a project board

                                  Response
                                  200

                                  OK

                                  Expand all
                                  Copy code
                                    • true
                                    • { ... }
                                      • null

                                    Update task in project plan

                                    Copy link

                                    Updates a task phase or group in a project.

                                    API v1
                                    Request
                                    PUT

                                    /v1/projects/{id}/plan/tasks/{taskId}

                                    Path parameters

                                    id

                                    integer

                                    required

                                    The ID of the project

                                    taskId

                                    integer

                                    required

                                    The ID of the task

                                    Body parameters

                                    application/json

                                    phase_id

                                    number

                                    The ID of a phase on a project board

                                    group_id

                                    number

                                    The ID of a group on a project board

                                    Response
                                    200

                                    OK

                                    Expand all
                                    Copy code
                                      • true
                                      • { ... }
                                        • null

                                      Delete a project

                                      Copy link

                                      Marks a project as deleted.

                                      API v1
                                      Request
                                      DELETE

                                      /v1/projects/{id}

                                      Path parameters

                                      id

                                      integer

                                      required

                                      The ID of the project

                                      Response
                                      200

                                      OK

                                      Expand all
                                      Copy code
                                        • true
                                        • { ... }
                                          • null

                                        Subscribe to Pipedrive’s Developer Newsletter