Pipedrive Stages API

openapi: 3.0.1
info:
  title: Pipedrive API v1 Activities Stages 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: Stages
  description: 'Stage is a logical component of a pipeline, and essentially a bucket that can hold a number of deals. In the context of the pipeline a stage belongs to, it has an order number which defines the order of stages in that pipeline.

    '
paths:
  /stages/{id}/deals:
    get:
      summary: Get deals in a stage
      description: Lists deals in a specific stage. If no parameters are provided open deals owned by the authorized user will be returned. <br>This endpoint has been deprecated. Please use <a href="https://developers.pipedrive.com/docs/api/v1/Deals#getDeals" target="_blank" rel="noopener noreferrer">GET /api/v2/deals?stage_id={id}</a> instead.
      x-token-cost: 20
      operationId: getStageDeals
      deprecated: true
      tags:
      - Stages
      security:
      - api_key: []
      - oauth2:
        - deals:read
        - deals:full
      parameters:
      - in: path
        name: id
        description: The ID of the stage
        required: true
        schema:
          type: integer
      - in: query
        name: filter_id
        schema:
          type: integer
        description: If supplied, only deals matching the given filter will be returned
      - in: query
        name: user_id
        schema:
          type: integer
        description: If supplied, `filter_id` will not be considered and only deals owned by the given user will be returned. If omitted, deals owned by the authorized user will be returned.
      - in: query
        name: everyone
        schema:
          title: numberBoolean
          type: number
          enum:
          - 0
          - 1
        description: If supplied, `filter_id` and `user_id` will not be considered – instead, deals owned by everyone will be returned
      - in: query
        name: start
        description: Pagination start
        schema:
          type: integer
          default: 0
      - in: query
        name: limit
        description: Items shown per page
        schema:
          type: integer
      responses:
        '200':
          description: Get deals in a stage
          content:
            application/json:
              schema:
                title: GetStageDealsResponse
                type: object
                properties:
                  success:
                    type: boolean
                    description: If the request was successful or not
                  data:
                    type: array
                    items:
                      title: DealStrict
                      allOf:
                      - type: object
                        properties:
                          id:
                            type: integer
                            description: The ID of the deal
                          creator_user_id:
                            type: integer
                            description: The ID of the deal creator
                          user_id:
                            type: integer
                            description: The ID of the user
                          person_id:
                            type: integer
                            description: The ID of the person associated with the deal
                          org_id:
                            type: integer
                            description: The ID of the organization associated with the deal
                      - title: baseDeal
                        type: object
                        properties:
                          stage_id:
                            type: integer
                            description: The ID of the deal stage
                          title:
                            type: string
                            description: The title of the deal
                          value:
                            type: number
                            description: The value of the deal
                          currency:
                            type: string
                            description: The currency associated with the deal
                          add_time:
                            type: string
                            description: The creation date and time of the deal
                          update_time:
                            type: string
                            description: The last updated date and time of the deal
                          stage_change_time:
                            type: string
                            description: The last updated date and time of the deal stage
                          active:
                            type: boolean
                            description: Whether the deal is active or not
                          deleted:
                            type: boolean
                            description: Whether the deal is deleted or not
                          is_archived:
                            type: boolean
                            description: Whether the deal is archived or not
                          status:
                            type: string
                            description: The status of the deal
                          probability:
                            type: number
                            nullable: true
                            description: The success probability percentage of the deal
                          next_activity_date:
                            type: string
                            description: The date of the next activity associated with the deal
                          next_activity_time:
                            type: string
                            description: The time of the next activity associated with the deal
                          next_activity_id:
                            type: integer
                            nullable: true
                            description: The ID of the next activity associated with the deal
                          last_activity_id:
                            type: integer
                            nullable: true
                            description: The ID of the last activity associated with the deal
                          last_activity_date:
                            type: string
                            nullable: true
                            description: The date of the last activity associated with the deal
                          lost_reason:
                            type: string
                            nullable: true
                            description: The reason for losing the deal
                          visible_to:
                            type: string
                            description: The visibility of the deal
                          close_time:
                            type: string
                            nullable: true
                            description: The date and time of closing the deal
                          pipeline_id:
                            type: integer
                            description: The ID of the pipeline associated with the deal
                          won_time:
                            type: string
                            description: The date and time of changing the deal status as won
                          first_won_time:
                            type: string
                            description: The date and time of the first time changing the deal status as won
                          lost_time:
                            type: string
                            description: The date and time of changing the deal status as lost
                          products_count:
                            type: integer
                            description: The number of products associated with the deal
                          files_count:
                            type: integer
                            description: The number of files associated with the deal
                          notes_count:
                            type: integer
                            description: The number of notes associated with the deal
                          followers_count:
                            type: integer
                            description: The number of followers associated with the deal
                          email_messages_count:
                            type: integer
                            description: The number of emails associated with the deal
                          activities_count:
                            type: integer
                            description: The number of activities associated with the deal
                          done_activities_count:
                            type: integer
                            description: The number of completed activities associated with the deal
                          undone_activities_count:
                            type: integer
                            description: The number of incomplete activities associated with the deal
                          participants_count:
                            type: integer
                            description: The number of participants associated with the deal
                          expected_close_date:
                            type: string
                            format: date
                            description: The expected close date of the deal
                          last_incoming_mail_time:
                            type: string
                            description: The date and time of the last incoming email associated with the deal
                          last_outgoing_mail_time:
                            type: string
                            description: The date and time of the last outgoing email associated with the deal
                          label:
                            type: string
                            description: The label or multiple labels assigned to the deal
                          stage_order_nr:
                            type: integer
                            description: The order number of the deal stage associated with the deal
                          person_name:
                            type: string
                            description: The name of the person associated with the deal
                          org_name:
                            type: string
                            description: The name of the organization associated with the deal
                          next_activity_subject:
                            type: string
                            description: The subject of the next activity associated with the deal
                          next_activity_type:
                            type: string
                            description: The type of the next activity associated with the deal
                          next_activity_duration:
                            type: string
                            description: The duration of the next activity associated with the deal
                          next_activity_note:
                            type: string
                            description: The note of the next activity associated with the deal
                          formatted_value:
                            type: string
                            description: The deal value formatted with selected currency. E.g. US$500
                          weighted_value:
                            type: number
                            description: Probability times deal value. Probability can either be deal probability or if not set, then stage probability.
                          formatted_weighted_value:
                            type: string
                            description: The weighted_value formatted with selected currency. E.g. US$500
                          weighted_value_currency:
                            type: string
                            description: The currency associated with the deal
                          rotten_time:
                            type: string
                            nullable: true
                            description: The date and time of changing the deal status as rotten
                          owner_name:
                            type: string
                            description: The name of the deal owner
                          cc_email:
                            type: string
                            description: The BCC email of the deal
                          org_hidden:
                            type: boolean
                            description: If the organization that is associated with the deal is hidden or not
                          person_hidden:
                            type: boolean
                            description: If the person that is associated with the deal is hidden or not
                          origin:
                            type: string
                            description: The way this Deal was created. `origin` field is set by Pipedrive when Deal is created and cannot be changed.
                          origin_id:
                            type: string
                            nullable: true
                            description: The optional ID to further distinguish the origin of the deal - e.g. Which API integration created this Deal.
                          channel:
                            type: integer
                            nullable: true
                            description: The ID of your Marketing channel this Deal was created from. Recognized Marketing channels can be configured in your <a href="https://app.pipedrive.com/settings/fields" target="_blank" rel="noopener noreferrer">Company settings</a>.
                          channel_id:
                            type: string
                            nullable: true
                            description: The optional ID to further distinguish the Marketing channel.
                          arr:
                            type: number
                            nullable: true
                            description: 'Only available in Growth and above plans


                              The Annual Recurring Revenue of the deal


                              Null if there are no products attached to the deal

                              '
                          mrr:
                            type: number
                            nullable: true
                            description: 'Only available in Growth and above plans


                              The Monthly Recurring Revenue of the deal


                              Null if there are no products attached to the deal

                              '
                          acv:
                            type: number
                            nullable: true
                            description: 'Only available in Growth and above plans


                              The Annual Contract Value of the deal


                              Null if there are no products attached to the deal

                              '
                          arr_currency:
                            type: string
                            nullable: true
                            description: 'Only available in Growth and above plans


                              The Currency for Annual Recurring Revenue of the deal


                              If the `arr` is null, this will also be null

                              '
                          mrr_currency:
                            type: string
                            nullable: true
                            description: 'Only available in Growth and above plans


                              The Currency for Monthly Recurring Revenue of the deal


                              If the `mrr` is null, this will also be null

                              '
                          acv_currency:
                            type: string
                            nullable: true
                            description: 'Only available in Growth and above plans


                              The Currency for Annual Contract Value of the deal


                              If the `acv` is null, this will also be null

                              '
                    description: The array of deals
                  additional_data:
                    description: The additional data of the list
                    type: object
                    properties:
                      start:
                        type: integer
                        description: Pagination start
                      limit:
                        type: integer
                        description: Items shown per page
                      more_items_in_collection:
                        type: boolean
                        description: If there are more list items in the collection than displayed or not
              example:
                success: true
                data:
                - id: 1
                  creator_user_id: 123
                  user_id: 456
                  person_id: 1
                  org_id: 2
                  stage_id: 2
                  title: Deal One
                  value: 5000
                  currency: EUR
                  add_time: '2019-05-29 04:21:51'
                  update_time: '2019-05-29 04:21:51'
                  stage_change_time: '2019-11-28 15:41:22'
                  active: true
                  deleted: false
                  status: open
                  probability: null
                  next_activity_date: '2019-11-29'
                  next_activity_time: '11:30:00'
                  next_activity_id: 128
                  last_activity_id: null
                  last_activity_date: null
                  lost_reason: null
                  visible_to: '1'
                  close_time: null
                  pipeline_id: 1
                  won_time: '2019-11-27 11:40:36'
                  first_won_time: '2019-11-27 11:40:36'
                  lost_time: '2019-11-27 11:40:36'
                  products_count: 0
                  files_count: 0
                  notes_count: 2
                  followers_count: 0
                  email_messages_count: 4
                  activities_count: 1
                  done_activities_count: 0
                  undone_activities_count: 1
                  participants_count: 1
                  expected_close_date: '2019-06-29'
                  last_incoming_mail_time: '2019-05-29 18:21:42'
                  last_outgoing_mail_time: '2019-05-30 03:45:35'
                  label: '11'
                  stage_order_nr: 2
                  person_name: Person
                  org_name: Organization
                  next_activity_subject: Call
                  next_activity_type: call
                  next_activity_duration: 00:30:00
                  next_activity_note: Note content
                  formatted_value: €5,000
                  weighted_value: 5000
                  formatted_weighted_value: €5,000
                  weighted_value_currency: EUR
                  rotten_time: null
                  owner_name: Creator
                  cc_email: company+deal1@pipedrivemail.com
                  org_hidden: false
                  person_hidden: false
                additional_data:
                  pagination:
                    start: 0
                    limit: 100
                    more_items_in_collection: false
  /stages:
    get:
      summary: Get all stages
      description: Returns data about all stages.
      x-token-cost: 5
      operationId: getStages
      tags:
      - Stages
      security:
      - api_key: []
      - oauth2:
        - deals:read
        - deals:full
        - admin
      parameters:
      - in: query
        name: pipeline_id
        schema:
          type: integer
        description: The ID of the pipeline to fetch stages for. If omitted, stages for all pipelines will be fetched.
      - in: query
        name: sort_by
        description: 'The field to sort by. Supported fields: `id`, `update_time`, `add_time`, `order_nr`.'
        schema:
          type: string
          default: id
          enum:
          - id
          - update_time
          - add_time
          - order_nr
      - in: query
        name: sort_direction
        description: 'The sorting direction. Supported values: `asc`, `desc`.'
        schema:
          type: string
          default: asc
          enum:
          - asc
          - desc
      - in: query
        name: limit
        description: For pagination, the limit of entries to be returned. If not provided, 100 items will be returned. Please note that a maximum value of 500 is allowed.
        schema:
          type: integer
          example: 100
      - in: query
        name: cursor
        required: false
        schema:
          type: string
        description: For pagination, the marker (an opaque string value) representing the first item on the next page
      responses:
        '200':
          description: Get all stages
          content:
            application/json:
              schema:
                title: GetStagesResponse
                type: object
                properties:
                  success:
                    type: boolean
                    description: If the response is successful or not
                  data:
                    type: array
                    description: The array of stages
                    items:
                      type: object
                      title: StageItem
                      properties:
                        id:
                          type: integer
                          description: The ID of the stage
                        order_nr:
                          type: integer
                          description: Defines the order of the stage
                        name:
                          type: string
                          description: The name of the stage
                        is_deleted:
                          type: boolean
                          description: Whether the stage is marked as deleted or not
                        deal_probability:
                          type: integer
                          description: The success probability percentage of the deal. Used/shown when the deal weighted values are used.
                        pipeline_id:
                          type: integer
                          description: The ID of the pipeline to add the stage to
                        is_deal_rot_enabled:
                          type: boolean
                          description: Whether deals in this stage can become rotten
                        days_to_rotten:
                          type: integer
                          nullable: true
                          description: The number of days the deals not updated in this stage would become rotten. Applies only if the `is_deal_rot_enabled` is set.
                        add_time:
                          type: string
                          description: The stage creation time
                        update_time:
                          type: string
                          description: The stage update time
                  additional_data:
                    type: object
                    description: The additional data of the list
                    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: 1
                  order_nr: 1
                  name: Stage Name
                  is_deleted: false
                  deal_probability: 100
                  pipeline_id: 1
                  is_deal_rot_enabled: true
                  days_to_rotten: 2
                  add_time: '2024-01-01T00:00:00Z'
                  update_time: '2024-01-01T00:00:00Z'
                additional_data:
                  next_cursor: eyJmaWVsZCI6ImlkIiwiZmllbGRWYWx1ZSI6Nywic29ydERpcmVjdGlvbiI6ImFzYyIsImlkIjo3fQ
    post:
      summary: Add a new stage
      description: Adds a new stage, returns the ID upon success.
      x-token-cost: 5
      operationId: addStage
      tags:
      - Stages
      security:
      - api_key: []
      - oauth2:
        - admin
      requestBody:
        content:
          application/json:
            schema:
              title: addStageRequest
              required:
              - name
              - pipeline_id
              type: object
              properties:
                name:
                  type: string
                  description: The name of the stage
                pipeline_id:
                  type: integer
                  description: The ID of the pipeline to add stage to
                deal_probability:
                  type: integer
                  description: The success probability percentage of the deal. Used/shown when deal weighted values are used.
                is_deal_rot_enabled:
                  type: boolean
                  description: Whether deals in this stage can become rotten
                days_to_rotten:
                  type: integer
                  description: The number of days the deals not updated in this stage would become rotten. Applies only if the `is_deal_rot_enabled` is set.
      responses:
        '200':
          description: Add a new stage
          content:
            application/json:
              schema:
                title: UpsertStageResponse
                type: object
                properties:
                  success:
                    type: boolean
                    description: If the response is successful or not
                  data:
                    type: object
                    title: StageItem
                    properties:
                      id:
                        type: integer
                        description: The ID of the stage
                      order_nr:
                        type: integer
                        description: Defines the order of the stage
                      name:
                        type: string
                        description: The name of the stage
                      is_deleted:
                        type: boolean
                        description: Whether the stage is marked as deleted or not
                      deal_probability:
                        type: integer
                        description: The success probability percentage of the deal. Used/shown when the deal weighted values are used.
                      pipeline_id:
                        type: integer
                        description: The ID of the pipeline to add the stage to
                      is_deal_rot_enabled:
                        type: boolean
                        description: Whether deals in this stage can become rotten
                      days_to_rotten:
                        type: integer
                        nullable: true
                        description: The number of days the deals not updated in this stage would become rotten. Applies only if the `is_deal_rot_enabled` is set.
                      add_time:
                        type: string
                        description: The stage creation time
                      update_time:
                        type: string
                        description: The stage update time
                    description: The stage object
              example:
                success: true
                data:
                  id: 1
                  order_nr: 1
                  name: Stage Name
                  is_deleted: false
                  deal_probability: 100
                  pipeline_id: 1
                  is_deal_rot_enabled: true
                  days_to_rotten: 2
                  add_time: '2024-01-01T00:00:00Z'
                  update_time: '2024-01-01T00:00:00Z'
  /stages/{id}:
    delete:
      summary: Delete a stage
      description: Marks a stage as deleted.
      x-token-cost: 3
      operationId: deleteStage
      tags:
      - Stages
      security:
      - api_key: []
      - oauth2:
        - admin
      parameters:
      - in: path
        name: id
        description: The ID of the stage
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Delete stage
          content:
            application/json:
              schema:
                title: DeleteStageResponse
                type: object
                properties:
                  success:
                    type: boolean
                    description: If the response is successful or not
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                        description: Deleted stage ID
              example:
                success: true
                data:
                  id: 1
    get:
      summary: Get one stage
      description: Returns data about a specific stage.
      x-token-cost: 1
      operationId: getStage
      tags:
      - Stages
      security:
      - api_key: []
      - oauth2:
        - deals:read
        - deals:full
        - admin
      parameters:
      - in: path
        name: id
        description: The ID of the stage
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Get one stages
          content:
            application/json:
              schema:
                title: UpsertStageResponse
                type: object
                properties:
                  success:
                    type: boolean
                    description: If the response is successful or not
                  data:
                    type: object
                    title: StageItem
                    properties:
                      id:
                        type: integer
                        description: The ID of the stage
                      order_nr:
                        type: integer
                        description: Defines the order of the stage
                      name:
                        type: string
                        description: The name of the stage
                      is_deleted:
                        type: boolean
                        description: Whether the stage is marked as deleted or not
                      deal_probability:
                        type: integer
                        description: The success probability percentage of the deal. Used/shown when the deal weighted values are used.
                      pipeline_id:
                        type: integer
                        description: The ID of the pipeline to add the stage to
                      is_deal_rot_enabled:
                        type: boolean
                        description: Whether deals in this stage can become rotten
                      days_to_rotten:
                        type: integer
                        nullable: true
                        description: The number of days the deals not updated in this stage would become rotten. Applies only if the `is_deal_rot_enabled` is set.
                      add_time:
                        type: string
                        description: The stage creation time
                      update_time:
                        type: string
                        description: The stage update time
                    description: The stage object
              example:
                succes

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