Pipedrive Deals API

openapi: 3.2.0
info:
  title: Pipedrive API v1 Activities Deals 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: Deals
  description: 'Deals represent ongoing, lost or won sales to an organization or to a person. Each deal has a monetary value and must be placed in a stage. Deals can be owned by a user, and followed by one or many users. Each deal 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. These hashes can be mapped against `DealField.key`. The corresponding label for each such custom field can be obtained from `DealField.name`.

    '
paths:
  /deals/archived:
    get:
      summary: Get all archived deals
      description: Returns all archived deals.
      x-token-cost: 40
      operationId: getArchivedDeals
      deprecated: true
      tags:
      - Deals
      security:
      - api_key: []
      - oauth2:
        - deals:read
        - deals:full
      parameters:
      - in: query
        name: user_id
        schema:
          type: integer
        description: If supplied, only deals matching the given user will be returned. However, `filter_id` and `owned_by_you` takes precedence over `user_id` when supplied.
      - in: query
        name: filter_id
        schema:
          type: integer
        description: The ID of the filter to use
      - in: query
        name: person_id
        schema:
          type: integer
        description: If supplied, only deals linked to the specified person are returned. If filter_id is provided, this is ignored.
      - in: query
        name: org_id
        schema:
          type: integer
        description: If supplied, only deals linked to the specified organization are returned. If filter_id is provided, this is ignored.
      - in: query
        name: product_id
        schema:
          type: integer
        description: If supplied, only deals linked to the specified product are returned. If filter_id is provided, this is ignored.
      - in: query
        name: pipeline_id
        schema:
          type: integer
        description: If supplied, only deals in the specified pipeline are returned. If filter_id is provided, this is ignored.
      - in: query
        name: stage_id
        schema:
          type: integer
        description: If supplied, only deals in the specified stage are returned. If filter_id is provided, this is ignored.
      - in: query
        name: status
        schema:
          type: string
          default: all_not_deleted
          enum:
          - open
          - won
          - lost
          - deleted
          - all_not_deleted
        description: Only fetch deals with a specific status. If omitted, all not deleted deals are returned. If set to deleted, deals that have been deleted up to 30 days ago will be included.
      - in: query
        name: start
        description: Pagination start
        schema:
          type: integer
          default: 0
      - in: query
        name: limit
        description: Items shown per page
        schema:
          type: integer
      - in: query
        name: sort
        schema:
          type: string
        description: The field names and sorting mode separated by a comma (`field_name_1 ASC`, `field_name_2 DESC`). Only first-level field keys are supported (no nested keys).
      - in: query
        name: owned_by_you
        description: When supplied, only deals owned by you are returned. However, `filter_id` takes precedence over `owned_by_you` when both are supplied.
        schema:
          title: numberBoolean
          type: number
          enum:
          - 0
          - 1
      responses:
        '200':
          description: Get all archived deals
          content:
            application/json:
              schema:
                title: GetDealsResponse
                type: object
                properties:
                  success:
                    type: boolean
                    description: If the response is successful or not
                  data:
                    type: array
                    items:
                      title: Deal
                      allOf:
                      - type: object
                        properties:
                          id:
                            type: integer
                            description: The ID of the deal
                          creator_user_id:
                            type: object
                            description: The creator of the deal
                            properties:
                              id:
                                type: integer
                                description: The ID of the deal creator
                              name:
                                type: string
                                description: The name of the deal creator
                              email:
                                type: string
                                description: The email of the deal creator
                              has_pic:
                                type: boolean
                                description: If the creator has a picture or not
                              pic_hash:
                                type:
                                - string
                                - 'null'
                                description: The creator picture hash
                              active_flag:
                                type: boolean
                                description: Whether the creator is active or not
                              value:
                                type: integer
                                description: The ID of the deal creator
                          user_id:
                            title: dealUserDataWithId
                            allOf:
                            - description: The user who is associated with the deal
                              type: object
                              properties:
                                id:
                                  type: integer
                                  description: The ID of the user
                                name:
                                  type: string
                                  description: The name of the user
                                email:
                                  type: string
                                  description: The email of the user
                                has_pic:
                                  type: boolean
                                  description: If the user has a picture or not
                                pic_hash:
                                  type:
                                  - string
                                  - 'null'
                                  description: The user picture hash
                                active_flag:
                                  type: boolean
                                  description: Whether the user is active or not
                            - type: object
                              properties:
                                value:
                                  type: integer
                                  description: The ID of the user
                          person_id:
                            title: dealPersonDataWithId
                            allOf:
                            - type: object
                              description: The person who is associated with the deal
                              properties:
                                active_flag:
                                  type: boolean
                                  description: Whether the associated person is active or not
                                name:
                                  type: string
                                  description: The name of the person associated with the deal
                                email:
                                  type: array
                                  description: The emails of the person associated with the deal
                                  items:
                                    type: object
                                    properties:
                                      label:
                                        type: string
                                        description: The type of the email
                                      value:
                                        type: string
                                        description: The email of the associated person
                                      primary:
                                        type: boolean
                                        description: If this is the primary email or not
                                phone:
                                  type: array
                                  description: The phone numbers of the person associated with the deal
                                  items:
                                    type: object
                                    properties:
                                      label:
                                        type: string
                                        description: The type of the phone number
                                      value:
                                        type: string
                                        description: The phone number of the person associated with the deal
                                      primary:
                                        type: boolean
                                        description: If this is the primary phone number or not
                                owner_id:
                                  type: integer
                                  description: The ID of the owner of the person that is associated with the deal
                            - type: object
                              properties:
                                value:
                                  type: integer
                                  description: The ID of the person associated with the deal
                          org_id:
                            title: DealOrganizationDataWithId
                            allOf:
                            - type: object
                              description: The organization which is associated with the deal
                              properties:
                                name:
                                  type: string
                                  description: The name of the organization associated with the deal
                                people_count:
                                  type: integer
                                  description: The number of people connected with the organization that is associated with the deal
                                owner_id:
                                  type: integer
                                  description: The ID of the owner of the organization that is associated with the deal
                                address:
                                  type: string
                                  description: The address of the organization that is associated with the deal
                                active_flag:
                                  type: boolean
                                  description: Whether the associated organization is active or not
                                cc_email:
                                  type: string
                                  description: The BCC email of the organization associated with the deal
                            - type: object
                              properties:
                                value:
                                  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
                            - 'null'
                            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
                            - 'null'
                            description: The ID of the next activity associated with the deal
                          last_activity_id:
                            type:
                            - integer
                            - 'null'
                            description: The ID of the last activity associated with the deal
                          last_activity_date:
                            type:
                            - string
                            - 'null'
                            description: The date of the last activity associated with the deal
                          lost_reason:
                            type:
                            - string
                            - 'null'
                            description: The reason for losing the deal
                          visible_to:
                            type: string
                            description: The visibility of the deal
                          close_time:
                            type:
                            - string
                            - 'null'
                            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
                            - 'null'
                            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
                            - 'null'
                            description: The optional ID to further distinguish the origin of the deal - e.g. Which API integration created this Deal.
                          channel:
                            type:
                            - integer
                            - 'null'
                            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
                            - 'null'
                            description: The optional ID to further distinguish the Marketing channel.
                          arr:
                            type:
                            - number
                            - 'null'
                            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
                            - 'null'
                            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
                            - 'null'
                            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
                            - 'null'
                            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
                            - 'null'
                            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
                            - 'null'
                            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
                  related_objects:
                    type: object
                    properties:
                      user:
                        type: object
                        properties:
                          USER_ID:
                            type: object
                            title: userDataWithId
                            allOf:
                            - properties:
                                id:
                                  type: integer
                                  description: The ID of the user
                                name:
                                  type: string
                                  description: The name of the user
                                email:
                                  type: string
                                  description: The email of the user
                                has_pic:
                                  type: integer
                                  description: Whether the user has picture or not. 0 = No picture, 1 = Has picture.
                                pic_hash:
                                  type:
                                  - string
                                  - 'null'
                                  description: The user picture hash
                                active_flag:
                                  type: boolean
                                  description: Whether the user is active or not
                            - type: object
                              description: The ID of the user
                      organization:
                        type: object
                        title: RelatedOrganizationDataWithActiveFlag
                        properties:
                          ORGANIZATION_ID:
                            type: object
                            title: OrganizationDataWithIdAndActiveFlag
                            description: The ID of the organization associated with the item
                            allOf:
                            - type: object
                              title: OrganizationDataWithIdAndActiveFlagAllOf
                              properties:
                                active_flag:
                                  type: boolean
                                  description: Whether the associated organization is active or not
                            - type: object
                              title: OrganizationDataWithId
                              description: The ID of the organization associated with the item
                              allOf:
                              - type: object
                                properties:
                                  id:
                                    type: integer
                                    description: The ID of the organization associated with the item
                              - type: object
                                properties:
                                  name:
                                    type: string
                                    description: The name of the organization associated with the item
                                  people_count:
                                    type: integer
                                    description: The number of people connected with the organization that is associated with the item
                                  owner_id:
                                    type: integer
                                    description: The ID of the owner of the organization that is associated with the item
                                  address:
                                    type:
                                    - string
                                    - 'null'
                                    description: The address of the organization
                                  cc_email:
                                    type:
                                    - string
                                    - 'null'
                                    description: The BCC email of the organization associated with the item
                      person:
                        type: object
                        properties:
                          PERSON_ID:
                            type: object
                            description: The ID of the person associated with the item
                            title: PersonDataWithActiveFlag
                            allOf:
                            - type: object
                              properties:
                                active_flag:
                                  type: boolean
                                  description: Whether the associated person is active or not
                            - type: object
                              properties:
                                id:
                                  type: integer
                                  description: The ID of the person associated with the item
                                name:
                                  type: string
                                  description: The name of the person associated with the item
                                email:
                                  type: array
                                  description: The emails of the person associated with the item
                                  items:
                                    type: object
                                    properties:
                                      label:
                                        type: string
                                        description: The type of the email
                                      value:
                                        type: string
                                        description: The email of the associated person
                                      primary:
                                        type: boolean
                                        description: Whether this is the primary email or not
                           

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