Pipedrive entities

class pypipedrive.models.activities.Activities(**fields)

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.

See Activities API reference.

Get all activities (BETA) activities/collection.

• GET[Cost:20] v1/activities DEPRECATED

• GET[Cost:10] api/v2/activities

Returns all activities.

• GET[Cost:10] v1/activities/collection DEPRECATED

Get details of an activity.

• GET[Cost:2] v1/activities/{id} DEPRECATED

• GET[Cost:1] api/v2/activities/{id}

Add an activity.

• POST[Cost:10] v1/activities DEPRECATED

• POST[Cost:5] api/v2/activities

Update an activity.

• PUT[Cost:10] v1/activities/{id} DEPRECATED

• PATCH[Cost:5] api/v2/activities/{id}

Delete multiple activities in bulk.

• DELETE[Cost:10] v1/activities DEPRECATED

Delete an activity.

• DELETE[Cost:6] v1/activities/{id} DEPRECATED

• DELETE[Cost:3] api/v2/activities/{id}

classmethod batch_delete(*args, **kwargs) → Any

Delete multiple activities in bulk.

classmethod fields() → List[ActivityFields]

Returns the list of field names for the Activities model.

classmethod types() → List[ActivityTypes]

Returns the list of field types for the Activities model.

class pypipedrive.models.activity_fields.ActivityFields(**fields)

Activity fields represent different fields that an activity has.

See ActivityFields API reference.

Returns all activity fields.

• GET[Cost:20] v1/activityFields

classmethod batch_delete(*args, **kwargs)

Marks multiple entities as deleted. After 30 days, the entities will be permanently deleted. ids and models are mutually exclusive.

Args:

ids: A list of model IDs to delete. models: A list of model instances to delete.

delete(*args, **kwargs)

Marks the record as deleted. After 30 days, the record will be permanently deleted.

save(*args, **kwargs)

Create/Save the resource into Pipedrive.

If the instance does not exist already, it will be created. Otherwise, the existing record will be updated, using only the fields which have been modified since it was retrieved.

Args:

force: If True, all fields will be saved, even if they have not changed. additional_params: Additional parameters for saving the resource.

class pypipedrive.models.activity_types.ActivityTypes(**fields)

Activity types represent different kinds of activities that can be stored. Each activity type is presented to the user with an icon and a name. Additionally, a color can be defined (not implemented in the Pipedrive app as of today). Activity types are linked to activities via ActivityType.key_string = Activity.type. The key_string will be generated by the API based on the given name of the activity type upon creation, and cannot be changed. Activity types should be presented to the user in an ordered manner, using the ActivityType.order_nr value.

See ActivityTypes API reference.

Returns all activity types.

• GET[Cost:20] v1/activityTypes

Adds a new activity type.

• POST[Cost:10] v1/activityTypes

Updates an activity type.

• PUT[Cost:10] v1/activityTypes/{id}

Marks multiple activity types as deleted.

• DELETE[Cost:10] v1/activityTypes

Marks an activity type as deleted.

• DELETE[Cost:6] v1/activityTypes/{id}

classmethod batch_delete(*args, **kwargs) → Dict

Marks multiple entities as deleted. After 30 days, the entities will be permanently deleted. ids and models are mutually exclusive.

Args:

ids: A list of model IDs to delete. models: A list of model instances to delete.

delete(*args, **kwargs) → bool

Marks the record as deleted. After 30 days, the record will be permanently deleted.

save(*args, **kwargs) → SaveResult

Create/Save the resource into Pipedrive.

If the instance does not exist already, it will be created. Otherwise, the existing record will be updated, using only the fields which have been modified since it was retrieved.

Args:

force: If True, all fields will be saved, even if they have not changed. additional_params: Additional parameters for saving the resource.

class pypipedrive.models.billing.Billing(**fields)

Billing is responsible for handling your subscriptions, payments, plans and add-ons.

See Billing API reference.

Returns the add-ons for a single company.

• GET[Cost:20] v1/billing/subscriptions/addons

classmethod batch_delete(*args, **kwargs)

Marks multiple entities as deleted. After 30 days, the entities will be permanently deleted. ids and models are mutually exclusive.

Args:

ids: A list of model IDs to delete. models: A list of model instances to delete.

delete(*args, **kwargs)

Marks the record as deleted. After 30 days, the record will be permanently deleted.

save(*args, **kwargs)

Create/Save the resource into Pipedrive.

If the instance does not exist already, it will be created. Otherwise, the existing record will be updated, using only the fields which have been modified since it was retrieved.

Args:

force: If True, all fields will be saved, even if they have not changed. additional_params: Additional parameters for saving the resource.

class pypipedrive.models.call_logs.CallLogs(**fields)

Call logs describe the outcome of a phone call managed by an integrated provider. Since these logs are also considered activities, they can be associated with a deal or a lead, a person and/or an organization. Call logs do differ from other activities, as they only receive the information needed to describe the phone call.

See CallLogs API reference.

Returns all call logs assigned to a particular user.

• GET[Cost:20] v1/callLogs

Returns details of a specific call log.

• GET[Cost:2] v1/callLogs/{id}

Adds a new call log.

• POST[Cost:10] v1/callLogs

Attach an audio file to the call log.

• POST[Cost:10] v1/callLogs/{id}/recording

Deletes a call log.

• DELETE[Cost:6] v1/callLogs/{id}

classmethod all(*args, **kwargs) → List[Self]

Returns all call logs assigned to a particular user.

Allowed query parameters:

• start (int): Pagination start. Defaults: 0.

• limit (int): For pagination, the limit of entries to be returned. The upper limit is 50.

Returns:

A list of CallLog instances.

attach_audio_file(data: bytes, file_name: str, content_type: str) → Dict

Adds an audio recording to the call log. That audio can be played by those who have access to the call log object.

Args:

data: The binary data of the audio file. file_name: The name of the audio file. content_type: The MIME type of the audio file.

Returns:

The API response as a dictionary ({success: true}).

classmethod batch_delete(*args, **kwargs)

Marks multiple entities as deleted. After 30 days, the entities will be permanently deleted. ids and models are mutually exclusive.

Args:

ids: A list of model IDs to delete. models: A list of model instances to delete.

delete(*args, **kwargs) → bool

Marks the record as deleted. After 30 days, the record will be permanently deleted.

classmethod get(*args, **kwargs) → Self

Returns details of a specific call log.

save(*args, **kwargs) → SaveResult

Adds a new call log. Mandatory fields:

• outcome (str): Describes the outcome of the call. Values: connected, no_answer, left_message, left_voicemail, wrong_number, busy.

• to_phone_number (str): The number called.

• start_time (str): The date and time of the start of the call in UTC. Format: YYYY-MM-DD HH:MM:SS.

• end_time (str): The date and time of the end of the call in UTC. Format: YYYY-MM-DD HH:MM:SS.

class pypipedrive.models.channels.Channels(**fields)

Channels API allows you to integrate your existing messaging channels into Pipedrive through Messaging app extension. It enables you to manage and interact with the channel’s conversations, participants and messages inside Pipedrive Messaging inbox: get the historical conversation, receive and send new messages. These endpoints are accessible only through Messengers integration OAuth scope together with Messaging manifest in building the Messaging app extension.

See Channels API reference.

Overall, this entity is fully deprecated and will be removed in future.

Adds a new messaging channel, only admins are able to register new channels.

• POST[Cost:10] v1/channels DEPRECATED

Receives an incoming message

• POST[Cost:10] v1/channels/messages/receive DEPRECATED

Deletes an existing messenger’s channel and all related entities.

• DELETE[Cost:6] v1/channels/{id} DEPRECATED

Deletes an existing conversation.

• DELETE[Cost:6] v1/channels/{channel-id}/conversations/{conversation-id} DEPRECATED

classmethod batch_delete(*args, **kwargs)

Marks multiple entities as deleted. After 30 days, the entities will be permanently deleted. ids and models are mutually exclusive.

Args:

ids: A list of model IDs to delete. models: A list of model instances to delete.

delete(*args, **kwargs)

Deletes an existing messenger’s channel and all related entities (conversations and messages). To use the endpoint, you need to have Messengers integration OAuth scope enabled and the Messaging manifest ready for the Messaging app extension.

save(*args, **kwargs)

Adds a new messaging channel, only admins are able to register new channels. It will use the getConversations endpoint to fetch conversations, participants and messages afterward. To use the endpoint, you need to have Messengers integration OAuth scope enabled and the Messaging manifest ready for the Messaging app extension.

class pypipedrive.models.currencies.Currencies(**fields)

Supported currencies which can be used to represent the monetary value of a deal, or a value of any monetary type custom field. The Currency.code field must be used to point to a currency. Currency.code is the ISO-4217 format currency code for non-custom currencies. You can differentiate custom and non-custom currencies using the is_custom_flag property. For custom currencies, it is intended that the formatted sums are displayed in the UI using the following format: [sum][non-breaking space character][currency.symbol], for example: 500 users. Custom currencies cannot be added or removed via the API yet — rather the admin users of the account must configure them from the Pipedrive app.

See Currencies API reference.

Returns all supported currencies in given account.

• GET[Cost:20] v1/currencies

classmethod all(term: str = None) → List[Self]

Returns all supported currencies in given account which should be used when saving monetary values with other objects. The code parameter of the returning objects is the currency code according to ISO 4217 for all non-custom currencies.

Args:

term: Optional search term that is searched for from currency’s name and/or code

Returns:

List of Currency objects

classmethod batch_delete(*args, **kwargs)

Marks multiple entities as deleted. After 30 days, the entities will be permanently deleted. ids and models are mutually exclusive.

Args:

ids: A list of model IDs to delete. models: A list of model instances to delete.

delete(*args, **kwargs)

Marks the record as deleted. After 30 days, the record will be permanently deleted.

save(*args, **kwargs)

Create/Save the resource into Pipedrive.

If the instance does not exist already, it will be created. Otherwise, the existing record will be updated, using only the fields which have been modified since it was retrieved.

Args:

force: If True, all fields will be saved, even if they have not changed. additional_params: Additional parameters for saving the resource.

class pypipedrive.models.deal_fields.DealFields(**fields)

Deal fields represent the near-complete schema for a deal in the context of the company of the authorized user. Each company can have a different schema for their deals, with various custom fields. In the context of using deal fields as a schema for defining the data fields of a deal, it must be kept in mind that some types of custom fields can have additional data fields which are not separate deal fields per se. Such is the case with monetary, daterange and timerange fields - each of these fields will have one additional data field in addition to the one presented in the context of deal fields. For example, if there is a monetary field with the key ffk9s9 stored on the account, ffk9s9 would hold the numeric value of the field, and ffk9s9_currency would hold the ISO currency code that goes along with the numeric value. To find out which data fields are available, fetch one deal and list its keys.

See DealFields API reference.

Returns data about all deal fields.

• GET[Cost:20] v1/dealFields

Returns data about a specific deal field.

• GET[Cost:2] v1/dealFields/{id}

Adds a new deal field. See: adding a new custom field.

• POST[Cost:10] v1/dealFields

Updates a deal field. See: updating custom field value.

• PUT[Cost:10] v1/dealFields/{id}

Marks multiple deal fields as deleted.

• DELETE[Cost:10] v1/dealFields

Marks a field as deleted. See: deleting a custom field.

• DELETE[Cost:6] v1/dealFields/{id}

classmethod all(params: Dict = {}) → List[Self]

Returns data about all deal fields.

Allowed query parameters:

• start (int): Pagination start. Default: 0.

• limit (int): Items shown per page.

Args:

params: Query parameters for filtering and pagination.

Returns:

A list of DealFields instances.

classmethod batch_delete(*args, **kwargs) → Dict

Marks multiple deal fields as deleted.

delete(*args, **kwargs) → bool

Marks a field as deleted. For more information, see the tutorial for deleting a custom field:.

classmethod get(id: int, params: Dict = {}) → Self

Returns data about a specific deal field.

Args:

id: The ID of the deal field to retrieve. params: Additional query parameters.

Returns:

An instance of DealFields representing the deal field.

save(force: bool = False) → SaveResult

Adds a new deal field. For more information, see the tutorial for adding a new custom field.

The values for DealFields.field_type are:

• address: Address field

• date: Date (format YYYY-MM-DD)

• daterange: Date-range field (has a start/end date values YYYY-MM-DD)

• double: Numeric value

• enum: Options field with a single possible chosen option

• monetary: Monetary field (has a numeric value and a currency value)

• org: Org field (contains an org ID which is stored on the same account)

• people: Person field (contains a person ID which is stored on the same account)

• phone: Phone field (up to 255 numbers and/or characters)

• set: Options field with a possibility of having multiple chosen options

• text: Long text (up to 65k characters)

• time: Time field (format HH:MM:SS)

• timerange: Time-range field (has a start/end time values HH:MM:SS)

• user: User field (contains a user ID of another Pipedrive user)

• varchar: Text (up to 255 characters)

• varchar_auto: Autocomplete text (up to 255 characters)

• visible_to: System field that keeps item’s visibility setting

To update a deal field, the allowed updatable fields are (they are set at the instance level):

• name: The name of the field.

• options: When field_type is either set or enum, possible options must be supplied as a JSON-encoded sequential array of objects. All active items must be supplied and already existing items must have their ID supplied. New items only require a label. Example: [{"id":123,"label":"Existing Item"},{"label":"New Item"}].

• add_visible_flag: Whether the field is available in ‘add new’ modal or not (both in web and mobile app). Default: True.

Args:

force: Whether to force the save operation.

Returns:

A SaveResult object containing the result of the save operation.

class pypipedrive.models.deals.Deals(**fields)

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.

See Deals API reference.

Returns data about all not archived deals.

• GET[Cost:20] v1/deals DEPRECATED

• GET[Cost:20] v2/deals

Returns data about all archived deals.

• GET[Cost:40] v1/deals/archived DEPRECATED

• GET[Cost:20] v2/deals/archived

Returns all deals collection.

• GET[Cost:10] v1/deals DEPRECATED

Searches all deals by title, notes and/or custom fields.

• GET[Cost:40] v1/deals/search DEPRECATED

• GET[Cost:20] v2/deals/search

Returns a summary of all not archived deals.

• GET[Cost:40] v1/deals/summary

Returns a summary of all not archived deals.

• GET[Cost:80] v1/deals/summary/archived DEPRECATED

Get deals timeline

• GET[Cost:20] v1/deals/timeline

Get archived deals timeline

• GET[Cost:20] v1/deals/timeline/archived DEPRECATED

Returns the details of a specific deal.

• GET[Cost:2] v1/deals/{id} DEPRECATED

• GET[Cost:1] v2/deals/{id}

List activities associated with a deal.

• GET[Cost:20] v1/deals/{id}/activities DEPRECATED

Lists updates about field values of an deal.

• GET[Cost:20] v1/deals/{id}/changelog

Lists files associated with a deal.

• GET[Cost:20] v1/deals/{id}/files

List updates about a deal.

• GET[Cost:40] v1/deals/{id}/flow

List updates about participants of a deal.

• GET[Cost:10] v1/deals/{id}/participantsChangelog

List followers of a deal.

• GET[Cost:20] v1/deals/{id}/followers DEPRECATED

• GET[Cost:10] v2/deals/{id}/followers

List mail messages associated with a deal.

• GET[Cost:20] v1/deals/{id}/mailMessages

List participants of a deal.

• GET[Cost:10] v1/deals/{id}/participants

List permitted users.

• GET[Cost:10] v1/deals/{id}/permittedUsers

List all persons associated with a deal.

• GET[Cost:20] v1/deals/{id}/persons DEPRECATED

List products attached to a deal.

• GET[Cost:20] v1/deals/{id}/products DEPRECATED

• GET[Cost:10] v2/deals/{id}/products

List followers changelog of a deal.

• GET[Cost:10] v2/deals/{id}/followers/changelog

Get deal products of several deals.

• GET[Cost:20] v2/deals/products

List discounts added to a deal.

• GET[Cost:10] v2/deals/{id}/discounts

List installments added to a list of deals (BETA).

• GET[Cost:10] v2/deals/installments

Get Deal conversion status (BETA)

• GET[Cost:10] v2/deals/{id}/convert/status/{conversion_id}

Add a deal.

• POST[Cost:10] v1/deals DEPRECATED

• POST[Cost:5] v2/deals

Duplicate deal.

• POST[Cost:10] v1/deals/{id}/duplicate

Add a follower to a deal.

• POST[Cost:10] v1/deals/{id}/followers DEPRECATED

• POST[Cost:5] v2/deals/{id}/followers

Add a participant to a deal.

• POST[Cost:5] v1/deals/{id}/participants

Add a product to a deal.

• POST[Cost:10] v1/deals/{id}/products DEPRECATED

• POST[Cost:5] v2/deals/{id}/products

Add multiple products to a deal.

• POST[Cost:25] v2/deals/{id}/products/bulk

Add a discount to a deal.

• POST[Cost:5] v2/deals/{id}/discounts

Add an installment to a deal.

• POST[Cost:5] v2/deals/{id}/installments

Convert a deal to a lead (BETA).

• GET[Cost:40] v2/deals/{id}/convert/lead

Update a deal.

• PUT[Cost:10] v1/deals/{id} DEPRECATED

• PATCH[Cost:5] v2/deals/{id}

Merge two deals.

• PUT[Cost:40] v1/deals/{id}/merge (merge_with_id in body)

Update the product attached to a deal.

• PUT[Cost:10] v1/deals/{id}/products/{product_attachment_id} DEPRECATED

• PATCH[Cost:5] v2/deals/{id}/products/{product_attachment_id}

Update a discount added to a deal.

• PATCH[Cost:5] v2/deals/{id}/discounts/{discount_id}

Update an installment added to a deal.

• PATCH[Cost:5] v2/deals/{id}/installments/{installment_id}

Delete multiple deals in bulk

• DELETE[Cost:10] v1/deals DEPRECATED

Delete a deal.

• DELETE[Cost:6] v1/deals/{id} DEPRECATED

• DELETE[Cost:3] v2/deals/{id}

Delete a follower from a deal.

• DELETE[Cost:6] v1/deals/{id}/followers/{follower_id} DEPRECATED

• DELETE[Cost:3] v2/deals/{id}/followers/{follower_id}

Delete a participant from a deal.

• DELETE[Cost:3] v1/deals/{id}/participants/{participant_id}

Delete many products from a deal.

• DELETE[Cost:25] v2/deals/{id}/products

Delete an attached product from a deal

• DELETE[Cost:5] v1/deals/{id}/products/{product_attachment_id} DEPRECATED

• DELETE[Cost:3] v2/deals/{id}/products/{product_attachment_id}

Delete a discount from a deal

• DELETE[Cost:3] v2/deals/{id}/discounts/{discount_id}

Delete an installment from a deal

• DELETE[Cost:3] v2/deals/{id}/installments/{installment_id}

add_discount(description: str = None, amount: int | float = None, type: str = None) → Dict

Adds a discount to a deal.

Args:

description: The description of the discount. amount: The discount amount. Must be a positive number (excl. 0). type: Determines whether the discount is applied as a percentage or a fixed amount.

Returns:

The API response data as a dictionary.

add_follower(user_id: int) → Dict

Add a follower to a deal.

Args:

user_id: The ID of the user to add as a follower.

Returns:

The API response data as a dictionary.

add_installment(description: str = None, amount: int | float = None, billing_date: str = None) → Dict

Adds an installment to a deal.

An installment can only be added if the deal includes at least one one-time product. If the deal contains at least one recurring product, adding installments is not allowed.

Only available in Growth and above plans.

Args:

description: The description of the discount. amount: The discount amount. Must be a positive number (excl. 0). billing_date: The date which the installment will be charged. Must be in the format YYYY-MM-DD.

Returns:

The API response data as a dictionary.

add_participant(person_id: int = None) → Dict

Adds a participant to a deal.

Args:

person_id: The ID of the person/participant to add to the deal.

Returns:

The API response data as a dictionary.

add_product(product_id: int = None, item_price: int | float = None, quantity: int | float = None, params: Dict = {}) → Dict

Add a product to a deal.

Allowed query params:

• product_id (int): The ID of the product.

• item_price (number): The price value of the product.

• quantity (number): The quantity of the product.

• tax (number): The product tax.

• comments (str): The comments of the product.

• discount (number): The value of the discount. The discount_type field can be used to specify whether the value is an amount or a percentage. Default: 0.

• is_enabled (bool): Whether this product is enabled for the deal. Not possible to disable the product if the deal has installments associated and the product is the last one enabled. Not possible to enable the product if the deal has installments associated and the product is recurring. Default: true.

• tax_method (str): The tax option to be applied to the products. When using inclusive, the tax percentage will already be included in the price. When using exclusive, the tax will not be included in the price. When using none, no tax will be added. Use the tax field for defining the tax percentage amount. By default, the user setting value for tax options will be used. Changing this in one product affects the rest of the products attached to the deal.

• discount_type (str): The value of the discount. The discount_type field can be used to specify whether the value is an amount or a percentage. Values: percentage (default), amount.

• product_variation_id (int): The ID of the product variation.

• billing_frequency (str): Only available in Growth and above plans. How often a customer is billed for access to a service or product. To set billing_frequency different than one-time, the deal must not have installments associated. A deal can have up to 20 products attached with billing_frequency different than one-time.

• billing_frequency_cycles (int): Only available in Growth and above plans. The number of times the billing frequency repeats for a product in a deal. When billing_frequency is set to one-time, this field must be null. When billing_frequency is set to weekly, this field cannot be null. For all the other values of billing_frequency, null represents a product billed indefinitely. Must be a positive integer less or equal to 208.

• billing_start_date (str): Only available in Growth and above plans. The billing start date. Must be between 10 years in the past and 10 years in the future. Format: YYYY-MM-DD.

Args:

product_id: The ID of the product to add to the deal. item_price: The price value of the product. quantity: The quantity of the product. params: Query params passed to the API (copied internally).

Returns:

The API response data as a dictionary.

add_product_bulk(data: List[Dict]) → Dict

Add multiple products to a deal in bulk.

Args:

data: List of product dictionaries to add to the deal. See

Deals.add_product() for the structure of each dictionary.

Returns:

The API response data as a dictionary.

classmethod archived(params: Dict = {}) → List[Self]

Returns data about all archived deals.

Args:

params: Query params passed to the API (copied internally).

Returns:

List of archived Deal instances.

classmethod batch_delete(*args, **kwargs) → Any

Marks multiple entities as deleted. After 30 days, the entities will be permanently deleted. ids and models are mutually exclusive.

Args:

ids: A list of model IDs to delete. models: A list of model instances to delete.

changelog(params: Dict = {}) → List[Dict]

Lists updates about field values of an deal. This is a cursor-paginated endpoint. For more information, please refer to our documentation on pagination.

Allowed query params:

• limit (int): Amount of results to return. Default: 100. Max: 500.

• cursor (str): For pagination, the marker (an opaque string value) representing the first item on the next page.

Args:

params: Query params passed to the API (copied internally).

Returns:

Dictionary containing changelog data.

conversion_status(conversion_id: int) → Dict

[BETA] Returns information about the conversion. Status is always present and its value (not_started, running, completed, failed, rejected) represents the current state of the conversion. Lead ID is only present if the conversion was successfully finished. This data is only temporary and removed after a few days.

Args:

conversion_id: The ID of the conversion process (UUID).

Returns:

Dictionary containing conversion status data.

convert_to_lead() → Dict

Initiates a conversion of a deal to a lead.

The return value is an ID of a job that was assigned to perform the conversion. Related entities (notes, files, emails, activities, …) are transferred during the process to the target entity. There are exceptions for entities like invoices or history that are not transferred and remain linked to the original deal. If the conversion is successful, the deal is marked as deleted.

To retrieve the created entity ID and the result of the conversion, use /api/v2/deals/{deal_id}/convert/status/{conversion_id} endpoint.

Returns:

The API response data as a dictionary.

classmethod deals_products(deal_ids: List[int] = None, params: Dict = {}) → List[Products]

Returns data about products attached to deals.

Allowed query params:

• deal_ids (array): An array of integers with the IDs of the deals for which the attached products will be returned. A maximum of 100 deal IDs can be provided.

• cursor (str): For pagination, the marker (an opaque string value) representing the first item on the next page.

• limit (int): Amount of results to return. Default: 100. Max: 500.

• sort_by (str): The field to sort by. Supported fields: “id” (default), “deal_id”, “add_time”, “update_time”, “order_nr”.

• sort_direction (str): The sort direction. Possible values: “asc” (default), “desc”.

Args:

params: Query params passed to the API (copied internally).

Returns:

List of deal products data.

delete_attached_product(product_attachment_id: int) → Dict

Deletes a product attached to a deal using product_attachment_id.

Args:

product_attachment_id: The ID of the deal-product (the ID of the product attached to the deal).

Returns:

The API response data as a dictionary.

delete_discount(discount_id: str) → Dict

Deletes a discount added to a deal.

Args:

discount_id: The ID of the discount. Format UUID.

Returns:

The API response data as a dictionary.

delete_follower(follower_id: int) → Dict

Deletes a user follower from the deal.

Args:

follower_id: The ID of the follower to delete.

Returns:

The API response data as a dictionary.

delete_installment(installment_id: int) → Dict

Deletes an installment added to a deal.

Only available in Growth and above plans.

Args:

installment_id: The ID of the installment.

Returns:

The API response data as a dictionary.

delete_participant(deal_participant_id: int) → Dict

Deletes a user participant from the deal.

Args:

deal_participant_id: The ID of the participant of the deal.

Returns:

The API response data as a dictionary.

delete_products(ids: List[int]) → Dict

Deletes multiple products from a deal. If no product IDs are specified, up to 100 products will be removed from the deal. A maximum of 100 product IDs can be provided per request.

Args:

ids: Comma-separated list of deal product IDs to delete. If not provided, all deal products will be deleted up to 100 items. Maximum 100 IDs allowed.

Returns:

The API response data as a dictionary.

discounts() → Dict

Lists discounts attached to a deal.

Returns:

Dictionary containing discounts data.

duplicate() → Self

Duplicate a deal.

Returns:

The newly created Deal instance.

classmethod fields() → List[DealFields]

Returns the list of field names for the Deals model.

files(params: Dict = {}) → List[Files]

Lists files associated with a deal.

Allowed query params:

• start (int): Pagination start. Default: 0.

• limit (int): Amount of results to return. Max: 100.

• sort (str): Sort order. Possible values: “id”, “update_time”.

Args:

params: Query params passed to the API (copied internally).

Returns:

List of files data.

flow(params: Dict = {}) → Dict

Lists updates about a deal.

Allowed query params:

• start (int): Pagination start. Default: 0.

• limit (int): Amount of results to return. Default: 100. Max: 500.

• all_changes (str): Whether to show custom field updates or not. 1 = Include custom field changes. If omitted returns changes without custom field updates.

• items (str): A comma-separated string for filtering out item specific updates. Possible values: call, activity, plannedActivity, change, note, deal, file, dealChange, personChange, organizationChange, follower, dealFollower, personFollower, organizationFollower, participant, comment, mailMessage, mailMessageWithAttachment, invoice, document, marketing_campaign_stat, marketing_status_change.

Args:

params: Query params passed to the API (copied internally).

Returns:

Dictionary containing flow data.

followers(params: Dict = {}) → List[Dict]

List followers of a deal.

Allowed query params:

• limit (int): Amount of results to return. Default: 100. Max: 500.

• cursor (str): For pagination, the marker (an opaque string value) representing the first item on the next page.

Args:

params: Query params passed to the API (copied internally).

Returns:

List of followers data.

followers_changelog(params: Dict = {}) → Dict

Lists changelogs about users have followed the deal.

Allowed query params:

• limit (int): Amount of results to return. Default: 100. Max: 500.

• cursor (str): For pagination, the marker (an opaque string value) representing the first item on the next page.

Args:

params: Query params passed to the API (copied internally).

Returns:

Dictionary containing changelog data.

classmethod installments(deal_ids: List[int] = None, params: Dict = {}) → Dict

[BETA] Lists installments attached to a deal. Only available in Growth and above plans.

Allowed query params:

• deal_ids (array): An array of integers with the IDs of the deals for which the attached products will be returned. A maximum of 100 deal IDs can be provided.

• cursor (str): For pagination, the marker (an opaque string value) representing the first item on the next page.

• limit (int): Amount of results to return. Default: 100. Max: 500.

• sort_by (str): The field to sort by. Supported fields: “id” (default), “billing_date”, “deal_id”.

• sort_direction (str): The sort direction. Possible values: “asc” (default), “desc”.

Args:

deal_ids: List of deal IDs to filter installments. params: Query params passed to the API (copied internally).

Returns:

List of installments data.

mail_messages(params: Dict = {}) → List[Dict]

List mail messages associated with a deal.

Allowed query params:

• start (int): Pagination start. Default: 0.

• limit (int): Items shown per page.

Args:

params: Query params passed to the API (copied internally).

Returns:

List of mail messages data.

merge(merge_with_id: int) → Dict

Merges a deal with another deal.

Args:

merge_with_id: The ID of the deal to merge into this deal.

Returns:

The API response data as a dictionary.

participants(params: Dict = {}) → List[Dict]

Lists the participants associated with a deal. If a company uses the Campaigns product, then this endpoint will also return the data.marketing_status field.

Allowed query params:

• start (int): Pagination start. Default: 0.

• limit (int): Items shown per page.

Args:

params: Query params passed to the API (copied internally).

Returns:

List of participants data.

participants_changelog(params: Dict = {}) → Dict

List updates about participants of a deal. This is a cursor-paginated endpoint. For more information, please refer to our documentation on pagination.

Allowed query params:

• limit (int): Amount of results to return. Default: 100. Max: 500.

• cursor (str): For pagination, the marker (an opaque string value) representing the first item on the next page.

Args:

params: Query params passed to the API (copied internally).

Returns:

Dictionary containing participants changelog data.

permitted_users() → List[Dict]

Lists the users permitted to access a deal.

Returns:

List of permitted users data.

products(params: Dict = {}) → List[Products]

List products attached to a deal.

Allowed query params:

• limit (int): Amount of results to return. Default: 100. Max: 500.

• cursor (str): For pagination, the marker (an opaque string value) representing the first item on the next page.

• sort_by (str): Field to sort by. Default “id”. Values: “id”, “add_time”, “update_time”, “order_nr”.

• sort_direction (str): Sort direction. Default “asc”.

Args:

params: Query params passed to the API (copied internally).

Returns:

List of products data.

classmethod search(term: str = None, params: Dict = {}) → List[ItemSearch]

Searches all deals by title, notes and/or custom fields. This endpoint is a wrapper of /v2/itemSearch with a narrower OAuth scope. Found deals can be filtered by the person ID and the organization ID.

Args:

term: The search term to look for. Minimum 2 characters (or 1 if using exact_match). Please note that the search term has to be URL encoded. params: Query params passed to the API (copied internally).

Returns:

List of ItemSearch objects.

classmethod summary(params: Dict = {}) → Dict

Returns a summary of all not archived deals.

Allowed query params:

• status (str): Filter by deal status. Possible values: “open”, “won”, “lost”.

• currency (str): Filter by currency code (e.g. “USD”, “EUR”).

• filter_id (int): Filter by predefined filter ID.

• user_id (int): Filter by owner user ID.

• pipeline_id (int): Filter by pipeline ID.

• stage_id (int): Filter by stage ID.

Args:

params: Query params passed to the API (copied internally).

Returns:

Dictionary containing summary data.

classmethod timeline(start_date: date, interval: str, amount: int, field_key: str, params: Dict = {}) → Dict

Returns not archived open and won deals, grouped by a defined interval of time set in a date-type dealField (field_key) — e.g. when month is the chosen interval, and 3 months are asked starting from January 1st, 2012, deals are returned grouped into 3 groups — January, February and March — based on the value of the given field_key.

NB: Api also returns custom fields (uuid). Returning as dict for now because of the complexity of the data structure.

Args:

start_date: The start date for the timeline (YYYY-MM-DD). interval: The interval for grouping. Possible values: “day”, “week”, “month”, “quarter”. amount: The number of intervals to return. field_key: The deal field key to group by (must be date-type). params: Query params passed to the API (copied internally).

Returns:

List of Deal instances.

update_attached_product(product_attachment_id: int, params: Dict = {}) → Dict

Updates the details of the product that has been attached to a deal.

Args:

product_attachment_id: The ID of the deal-product (the ID of the product attached to the deal). params: Query params passed to the API (copied internally).

Returns:

The API response data as a dictionary.

update_discount(discount_id: str, params: Dict = {}) → Dict

Edits a discount added to a deal, changing the deal value if the deal has one-time products attached.

Args:

discount_id: The ID of the discount. Format UUID. params: Query params passed to the API (copied internally).

Returns:

The API response data as a dictionary.

update_installment(installment_id: int, params: Dict = {}) → Dict

Edits an installment added to a deal.

Only available in Growth and above plans.

Args:

installment_id: The ID of the installment. params: Query params passed to the API (copied internally).

Returns:

The API response data as a dictionary.

class pypipedrive.models.files.Files(**fields)

Files are documents of any kind (images, spreadsheets, text files, etc.) that are uploaded to Pipedrive, and usually associated with a particular deal, person, organization, product, note or activity. Remote files can only be associated with a particular deal, person or organization. Note that the API currently does not support downloading files although it lets you retrieve a file’s meta-info along with a URL which can be used to download the file by using a standard HTTP GET request.

See Files API reference.

Returns data about all files.

• GET[Cost:20] v1/files

Returns data about a specific file.

• GET[Cost:2] v1/files/{id}

Download one file.

• GET[Cost:20] v1/files/{id}/download

Add file. See adding files via Pipedrive API.

• POST[Cost:10] v1/files

Create a remote file and link it to an item (Google Drive access required).

• POST[Cost:10] v1/files/remote

Link a remote file to an item (Google Drive access required).

• POST[Cost:10] v1/files/remoteLink

Update file details

• PUT[Cost:10] v1/files/{id}

Marks a file as deleted.

• DELETE[Cost:6] v1/files/{id}

classmethod all(params: Dict = {}) → List[Self]

Returns data about all files.

Allowed query parameters:

• start (int): Pagination start. Default: 0.

• limit (int): Items shown per page. Please note that a maximum value of 100 is allowed.

• sort (str): Supported fields: id, update_time.

Args:

params: Dict: Query parameters as a dictionary.

Returns:

List of File objects.

classmethod batch_delete(*args, **kwargs)

Marks multiple entities as deleted. After 30 days, the entities will be permanently deleted. ids and models are mutually exclusive.

Args:

ids: A list of model IDs to delete. models: A list of model instances to delete.

delete() → bool

Marks a file as deleted. After 30 days, the file will be permanently deleted.

download() → bytes

Initializes a file download (attaches the content to the content instance field).

Returns:

The binary content of the file.

classmethod get(id: int) → Self

Returns data about a specific file.

Args:

id: int: The ID of the file to retrieve.

Returns:

File object.

classmethod remote_create(file_type: str, title: str, item_type: str, item_id: int, remote_location: str = 'googledrive') → Self

Creates a new empty file in the remote location (googledrive) that will be linked to the item you supply. For more information, see the tutorial for adding a remote file.

NB: The user needs to have an activated Google Account in Pipedrive for the files to be added successfully. See https://{company-name}.pipedrive.com/settings/files.

Args:

file_type: The file type. Values gdoc, gslides, gsheet, gform, gdraw. title: The title of the file. item_type: The item type. Values: Values: deal, organisation, person. item_id: The ID of the item to associate the file with. remote_location: The location type to send the file to. Only googledrive is supported at the moment.

Returns:

The created and linked File object.

classmethod remote_link(item_type: str, item_id: int, remote_id: str, remote_location: str = 'googledrive') → Self

Links an existing remote file (googledrive) to the item you supply. For more information, see the tutorial for adding a remote file. See adding a remote file.

NB: The user needs to have an activated Google Account in Pipedrive for the files to be added successfully. See https://{company-name}.pipedrive.com/settings/files.

Args:

item_type: The item type. Values: Values: deal, organisation, person. item_id: The ID of the item to associate the file with. remote_id: The remote item ID. remote_location: The location type to send the file to. Only googledrive is supported at the moment.

Returns:

The linked File object.

classmethod save(data: bytes, file_name: str, content_type: str, params: Dict = {}) → Self

Lets you upload a file and associate it with a deal, person, organization, activity, product or lead. For more information, see the tutorial for adding a file.

Args:

data: The binary content of the file to upload. file_name: The name of the file to upload. content_type: The MIME type of the file to upload. params: Additional parameters for the file upload.

Returns:

The uploaded File object (with content attached).

update() → SaveResult

Updates the properties of a file. Only name (The visible name of the file) and description (the description of the file) can be updated.

NB: an update method is required (no usage of the Model.save) to modify an existing instance because of the application/x-www-form-urlencoded required by the Pipedrive endpoint.

Returns:

The SaveResult of the update operation.

class pypipedrive.models.filters.Filters(**fields)

Each filter is essentially a set of data validation conditions. A filter of the same kind can be applied when fetching a list of deals, leads, persons, organizations or products in the context of a pipeline. Filters are limited to a maximum of 16 conditions. When applied, only items matching the conditions of the filter are returned. Detailed definitions of filter conditions and additional functionality is not yet available.

See Filters API reference.

Get all filters.

• GET[Cost:20] v1/filters

Get all filter helpers.

• GET[Cost:20] v1/filters/helpers

Get one filter.

• GET[Cost:2] v1/filters/{id}

Add a new filter.

• POST[Cost:10] v1/filters

Update filter.

• PUT[Cost:10] v1/filters/{id}

Delete multiple filters in bulk.

• DELETE[Cost:10] v1/filters

Delete a filter.

• DELETE[Cost:6] v1/filters/{id}

classmethod helpers() → Dict

Returns all supported filter helpers. It helps to know what conditions and helpers are available when you want to add or update filters. For more information, see the tutorial for adding a filter.

Returns:

A dictionary containing filter helpers (operators, deprecated_operators, relative_dates, address_field_components).

class pypipedrive.models.goals.Goals(**fields)

Goals help your team meet your sales targets. There are three types of goals - company, team and user.

See Goals API reference.

Find goals.

• GET[Cost:20] v1/goals/find

Get result of a goal.

• GET[Cost:20] v1/goals/{id}/results

Add a new goal.

• POST[Cost:10] v1/goals

Update an existing goal.

• PUT[Cost:10] v1/goals/{id}

Delete existing goal.

• DELETE[Cost:6] v1/goals/{id}

classmethod batch_delete(*args, **kwargs) → any

Marks multiple entities as deleted. After 30 days, the entities will be permanently deleted. ids and models are mutually exclusive.

Args:

ids: A list of model IDs to delete. models: A list of model instances to delete.

classmethod find(params: Dict = {}) → List[Self]

Returns data about goals based on criteria. For searching, append {searchField}={searchValue} to the URL, where searchField can be any one of the lowest-level fields in dot-notation (e.g. type.params.pipeline_id; title). searchValue should be the value you are looking for on that field. Additionally, is_active=<true|false> can be provided to search for only active/inactive goals. When providing period.start, period.end must also be provided and vice versa.

Allowed query parameters:

• type.name (str): The type of the goal. If provided, everyone’s goals will be returned. Values: deals_won, deals_progressed, activities_completed, activities_added, deals_started.

• title (str): The title of the goal.

• is_active (bool): Whether the goal is active or not. Default: true.

• assignee.id (int): The ID of the user who’s goal to fetch. When omitted, only your goals will be returned.

• assignee.type (str): The type of the goal’s assignee. If provided, everyone’s goals will be returned. Values: person, company, team.

• expected_outcome.target (number): The numeric value of the outcome. If provided, everyone’s goals will be returned.

• expected_outcome.tracking_metric (str): The tracking metric of the expected outcome of the goal. If provided, everyone’s goals will be returned. Values: quantity, sum.

• expected_outcome.currency_id (int): The numeric ID of the goal’s currency. Only applicable to goals with expected_outcome.tracking_metric with value sum. If provided, everyone’s goals will be returned.

• type.params.pipeline_id (int): An array of pipeline IDs or null for all pipelines. If provided, everyone’s goals will be returned.

• type.params.stage_id (int): The ID of the stage. Applicable to only deals_progressed type of goals. If provided, everyone’s goals will be returned.

• type.params.activity_type_id (int): An array of IDs or null for all activity types. Only applicable for activities_completed and/or activities_added types of goals. If provided, everyone’s goals will be returned.

• period.start (str): The start date of the period for which to find the goal’s progress. Format: YYYY-MM-DD. This date must be the same or after the goal duration start date.

• period.end (str): The end date of the period for which to find the goal’s progress. Format: YYYY-MM-DD. This date must be the same or before the goal duration end date.

Args:

params: Additional search parameters.

Returns:

A dictionary containing the goals found.

results(period_start: str | date, period_end: str | date) → Self | None

Gets the progress of a goal for the specified period.

Mandatory query parameters:

• period.start (str): The start date of the period for which to find the goal’s progress. Format: YYYY-MM-DD. This date must be the same or after the goal duration start date.

• period.end (str): The end date of the period for which to find the goal’s progress. Format: YYYY-MM-DD. This date must be the same or before the goal duration end date.

Returns:

A dictionary containing the goals found.

save(*args, **kwargs) → SaveResult

Adds a new goal. Along with adding a new goal, a report is created to track the progress of your goal.

Fields to create a Goal:

• title (str): The title of the goal.

• assignee (object): Who this goal is assigned to. It requires the following JSON structure: { "id": "1", "type": "person" }. type can be either person, company or team. ID of the assignee person, company or team.

• type (object): The type of the goal. It requires the following JSON structure: { "name": "deals_started", "params": { "pipeline_id": [1, 2], "activity_type_id": [9] } }. Type can be one of: deals_won, deals_progressed, activities_completed, activities_added, deals_started or revenue_forecast. params can include pipeline_id, stage_id or activity_type_id. stage_id is related to only deals_progressed type of goals and activity_type_id to activities_completed or activities_added types of goals. The pipeline_id and activity_type_id need to be given as an array of integers. To track the goal in all pipelines, set pipeline_id as null and similarly, to track the goal for all activities, set activity_type_id as null.

• expected_outcome (object): The expected outcome of the goal. Expected outcome can be tracked either by quantity or by sum. It requires the following JSON structure: { "target": "50", "tracking_metric": "quantity" } or { "target": "50", "tracking_metric": "sum", "currency_id": 1 }. currency_id should only be added to sum type of goals.

• duration (object): The date when the goal starts and ends. It requires the following JSON structure: { "start": "2019-01-01", "end": "2022-12-31" }. Date in format of YYYY-MM-DD. “end” can be set to null for an infinite, open-ended goal.

• interval (str): The interval of the goal. Values: weekly, monthly, quarterly, yearly.

Returns:

A SaveResult object containing the created Goal.

class pypipedrive.models.item_search.ItemSearch(**fields)

Ordered reference objects, pointing to either deals, persons, organizations, leads, products, files or mail attachments.

See ItemSearch API reference.

Performs a search from your choice of item types and fields.

• GET[Cost:40] v1/itemSearch DEPRECATED

• GET[Cost:20] v2/itemSearch

Performs a search from the values of a specific field.

• GET[Cost:40] v1/itemSearch/field DEPRECATED

• GET[Cost:20] v2/itemSearch/field

classmethod batch_delete(*args, **kwargs)

Marks multiple entities as deleted. After 30 days, the entities will be permanently deleted. ids and models are mutually exclusive.

Args:

ids: A list of model IDs to delete. models: A list of model instances to delete.

delete(*args, **kwargs)

Marks the record as deleted. After 30 days, the record will be permanently deleted.

save(*args, **kwargs)

Create/Save the resource into Pipedrive.

If the instance does not exist already, it will be created. Otherwise, the existing record will be updated, using only the fields which have been modified since it was retrieved.

Args:

force: If True, all fields will be saved, even if they have not changed. additional_params: Additional parameters for saving the resource.

classmethod search(term: str, item_types: List[str] = [], params: Dict = {}) → List[Self] | None

Performs a search from your choice of item types and fields.

Allowed query parameters:

• item_types (str): A comma-separated string array. The type of items to perform the search from. Defaults to all. Values: deal, person, organization, product, lead, file, mail_attachment, project.

• fields (str): A comma-separated string array. The fields to perform the search from. Defaults to all.

• search_for_related_items (bool): When enabled, the response will include up to 100 newest related leads and 100 newest related deals for each found person and organization and up to 100 newest related persons for each found organization.

• exact_match (bool): When enabled, only full exact matches against the given term are returned. It is not case sensitive.

• include_fields (str): A comma-separated string array. Supports including optional fields in the results which are not provided by default. Values: deal.cc_email, person.picture, product.price.

• limit (int): For pagination, the limit of entries to be returned. If not provided, 100 items will be returned. Please note that a maximum value of 100 is allowed.

• cursor (str): For pagination, the marker (an opaque string value) representing the first item on the next page.

Args:

term: The search term. item_types: The types of items to search for (ex: ‘persons’, ‘deals’). params: Additional search parameters.

Returns:

A list of ItemSearchPersonDict or ItemSearchDealDict objects.

classmethod search_field(term: str, entity_type: str, field: str, params: Dict = {}) → List[Dict] | None

Performs a search from the values of a specific field. Results can either be the distinct values of the field (useful for searching autocomplete field values), or the IDs of actual items (deals, leads, persons, organizations or products).

Allowed query parameters:

• match (str): The type of match used against the term. The search is case sensitive. E.g. in case of searching for a value monkey. With exact match, you will only find it if term is monkey. With beginning match, you will only find it if the term matches the beginning or the whole string, e.g. monk and monkey. With middle match, you will find it if the term matches any substring of the value, e.g. onk and ke. Default: exact. Values: exact, beginning, middle.

• limit (int): 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.

• cursor (str): For pagination, the marker (an opaque string value) representing the first item on the next page.

Args:

term: The search term. entity_type: The type of entity to search for (ex: ‘persons’, ‘deals’). field: The key of the field to search from. params: Additional search parameters.

Returns:

A list of dictionaries representing the search results.

class pypipedrive.models.lead_fields.LeadFields(**fields)

Lead fields represent the near-complete schema for a lead in the context of the company of the authorized user. Each company can have a different schema for their leads, with various custom fields. In the context of using lead fields as a schema for defining the data fields of a lead, it must be kept in mind that some types of custom fields can have additional data fields which are not separate lead fields per se. Such is the case with monetary, daterange and timerange fields - each of these fields will have one additional data field in addition to the one presented in the context of lead fields. For example, if there is a monetary field with the key ffk9s9 stored on the account, ffk9s9 would hold the numeric value of the field, and ffk9s9_currency would hold the ISO currency code that goes along with the numeric value. To find out which data fields are available, fetch one lead and list its keys.

Get all lead fields.

• GET[Cost:20] v1/leadFields

classmethod batch_delete(*args, **kwargs) → Any

Marks multiple entities as deleted. After 30 days, the entities will be permanently deleted. ids and models are mutually exclusive.

Args:

ids: A list of model IDs to delete. models: A list of model instances to delete.

classmethod delete(*args, **kwargs) → Any

Marks the record as deleted. After 30 days, the record will be permanently deleted.

save(*args, **kwargs) → Any

Create/Save the resource into Pipedrive.

If the instance does not exist already, it will be created. Otherwise, the existing record will be updated, using only the fields which have been modified since it was retrieved.

Args:

force: If True, all fields will be saved, even if they have not changed. additional_params: Additional parameters for saving the resource.

class pypipedrive.models.lead_labels.LeadLabels(**fields)

Lead labels allow you to visually categorize your leads. There are three default lead labels: hot, cold, and warm, but you can add as many new custom labels as you want.

Get all lead labels.

• GET[Cost:10] v1/leadLabels

Add a lead label.

• POST[Cost:10] v1/leadLabels

Update a lead label.

• PATCH[Cost:10] v1/leadLabels/{id}

Delete a lead label.

• DELETE[Cost:6] v1/leadLabels/{id}

classmethod batch_delete(*args, **kwargs) → Any

Marks multiple entities as deleted. After 30 days, the entities will be permanently deleted. ids and models are mutually exclusive.

Args:

ids: A list of model IDs to delete. models: A list of model instances to delete.

class pypipedrive.models.lead_sources.LeadSources(**fields)

A lead source indicates where your lead came from. Currently, these are the possible lead sources: Manually created, Deal, Web forms, Prospector, Leadbooster, Live chat, Import, Website visitors, Workflow automation, and API. Lead sources are pre-defined and cannot be edited. Please note that leads sourced from the Chatbot feature are assigned the value Leadbooster. Please also note that this list is not final and new sources may be added as needed.

Get all lead sources.

• GET[Cost:2] v1/leadSources

classmethod batch_delete(*args, **kwargs) → Any

Marks multiple entities as deleted. After 30 days, the entities will be permanently deleted. ids and models are mutually exclusive.

Args:

ids: A list of model IDs to delete. models: A list of model instances to delete.

classmethod delete(*args, **kwargs) → Any

Marks the record as deleted. After 30 days, the record will be permanently deleted.

save(*args, **kwargs) → Any

Create/Save the resource into Pipedrive.

If the instance does not exist already, it will be created. Otherwise, the existing record will be updated, using only the fields which have been modified since it was retrieved.

Args:

force: If True, all fields will be saved, even if they have not changed. additional_params: Additional parameters for saving the resource.

class pypipedrive.models.leads.Leads(**fields)

Leads are potential deals stored in Leads Inbox before they are archived or converted to a deal. Each lead needs to be named (using the title field) and be linked to a person or an organization. In addition to that, a lead can contain most of the fields a deal can (such as value or expected_close_date).

See Leads API reference.

Get all leads.

• GET[Cost:20] v1/leads

Get all archived leads.

• GET[Cost:40] v1/leads/archived

Get one lead.

• GET[Cost:2] v1/leads/{id}

List permitted users.

• GET[Cost:10] v1/leads/permittedUsers

Search leads.

• GET[Cost:40] v1/leads/search

• GET[Cost:20] v2/leads/search

Get Lead conversion status (BETA).

• GET[Cost:1] v2/leads/{id}/convert/status/{conversion_id}

Add a lead.

• POST[Cost:10] v1/leads

Convert a lead to a deal (BETA).

• POST[Cost:40] v2/leads/{id}/convert/deal

Update a lead.

• PATCH[Cost:10] v1/leads/{id}

Delete a lead.

• DELETE[Cost:6] v1/leads/{id}

classmethod archived(params: Dict = {}) → List[Self]

Returns multiple archived leads. Leads are sorted by the time they were created, from oldest to newest. Pagination can be controlled using limit and start query parameters. If a lead contains custom fields, the fields’ values will be included in the response in the same format as with the Deals endpoints. If a custom field’s value hasn’t been set for the lead, it won’t appear in the response. Please note that leads do not have a separate set of custom fields, instead they inherit the custom fields’ structure from deals.

Allowed query parameters:

• limit (int): For pagination, the limit of entries to be returned. If not provided, 100 items will be returned.

• start (int): For pagination, the position that represents the first result for the page.

• owner_id (int): If supplied, only leads matching the given user will be returned. However, filter_id takes precedence over owner_id when supplied.

• person_id (int): If supplied, only leads matching the given person will be returned. However, filter_id takes precedence over person_id when supplied.

• organization_id (int): If supplied, only leads matching the given organization will be returned. However, filter_id takes precedence over organization_id when supplied.

• filter_id (int): The ID of the filter to use.

• sort (str): 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). Values: id, title, owner_id, creator_id, was_seen, expected_close_date, next_activity_id, add_time, update_time.

Args:

params: Additional query parameters.

Returns:

A list of Lead instances.

classmethod batch_delete(*args, **kwargs) → any

Marks multiple entities as deleted. After 30 days, the entities will be permanently deleted. ids and models are mutually exclusive.

Args:

ids: A list of model IDs to delete. models: A list of model instances to delete.

conversion_status(conversion_id: str) → Dict

Returns data about the conversion. Status is always present and its value (not_started, running, completed, failed, rejected) represents the current state of the conversion. Deal ID is only present if the conversion was successfully finished. This data is only temporary and removed after a few days.

Args:

conversion_id: The ID of the conversion process (UUID).

Returns:

Dictionary containing conversion status data.

convert_to_deal() → Dict

Initiates a conversion of a lead to a deal.

The return value is an ID of a job that was assigned to perform the conversion. Related entities (notes, files, emails, activities, …) are transferred during the process to the target entity. If the conversion is successful, the lead is marked as deleted.

To retrieve the created entity ID and the result of the conversion, use /api/v2/leads/{lead_id}/convert/status/{conversion_id} endpoint.

Allowed query parameters:

• stage_id (int): The ID of a stage the created deal will be added to. Please note that a pipeline will be assigned automatically based on the stage_id. If omitted, the deal will be placed in the first stage of the default pipeline.

• pipeline_id (int): The ID of a pipeline the created deal will be added to. By default, the deal will be added to the first stage of the specified pipeline. Please note that pipeline_id and stage_id should not be used together as pipeline_id will be ignored.

Returns:

The API response data as a dictionary containing the conversion_id.

permitted_users() → List[Dict]

Lists the users permitted to access a lead.

Returns:

List of permitted users data.

classmethod search(term: str = None, params: Dict = {}) → List[ItemSearch]

Searches all leads by title, notes and/or custom fields. This endpoint is a wrapper of /v1/itemSearch with a narrower OAuth scope. Found leads can be filtered by the person ID and the organization ID.

Args:

term: The search term to look for. Minimum 2 characters (or 1 if using exact_match). Please note that the search term has to be URL encoded. params: Query params passed to the API (copied internally).

Returns:

List of ItemSearch objects.

class pypipedrive.models.mail_threads.MailThreads(**fields)

Mailbox was designed to be the email control hub inside Pipedrive. Pipedrive supports all major providers (including Gmail, Outlook and also custom IMAP/SMTP). There are 2 options for syncing user emails: 2-way sync: Mail Connection is established with the mail provider (example Gmail). There can be only 1 active Mail Connection per user in company. 1-way sync: SmartBCC feature which stores the copies of email messages to Pipedrive by adding the SmartBCC specific address to mail recipients.

The Mailbox represents the MailThreads. Therefore, querying MailThreads.get will return a specific mail thread whereas MailThreads.all will return a list of mail threads.

See Mailbox API reference.

Get one mail thread.

• GET[Cost:20] /v1/mailbox/mailThreads/{id}

Get mail threads.

• GET[Cost:20] /v1/mailbox/mailThreads

Get all mail messages of mail thread.

• GET[Cost:20] /v1/mailbox/mailThreads/{id}/mailMessages

Get one mail message.

• GET[Cost:2] /v1/mailbox/mailMessages/{id}

Update mail thread details.

• PUT[Cost:10] /v1/mailbox/mailThreads/{id}

Delete mail thread.

• DELETE[Cost:6] /v1/mailbox/mailThreads/{id}

classmethod all(folder: str, params: Dict = {}) → List[Self]

Returns mail threads in a specified folder ordered by the most recent message within.

Allowed query params:

• start (int): Pagination start. Default is 0.

• limit (int): Items shown per page.

Args:

folder: The folder to get mail threads from. Possible values are: inbox, drafts, sent, archive.

classmethod batch_delete(*args, **kwargs) → Any

Marks multiple entities as deleted. After 30 days, the entities will be permanently deleted. ids and models are mutually exclusive.

Args:

ids: A list of model IDs to delete. models: A list of model instances to delete.

classmethod mail_message(message_id: int, params: Dict = {}) → Dict | None

Returns data about a specific mail message.

Allowed query params:

• include_body (number): Whether to include the full message body or not. 0 = Don’t include, 1 = Include.

Args:

message_id: The ID of the mail message to fetch.

mail_messages() → List[Dict]

Returns all the mail messages inside a specified mail thread.

Returns:

A list of mail messages.

save(*args, **kwargs) → Any

Create/Save the resource into Pipedrive.

If the instance does not exist already, it will be created. Otherwise, the existing record will be updated, using only the fields which have been modified since it was retrieved.

Args:

force: If True, all fields will be saved, even if they have not changed. additional_params: Additional parameters for saving the resource.

update() → SaveResult

Updates the properties of a mail thread. Only the update method is allowed. Hence, the id field must be set.

Allowed fields to update:

• deal_id (int): The deal ID this thread is associated with.

• lead_id (str): The lead ID (UUID) this thread is associated with.

• shared_flag (int): Whether this thread is shared with other users in your company. Values: 0, 1.

• read_flag (int): Whether this thread is read or unread. Values: 0, 1.

• archived_flag (int): Whether this thread is archived or not. You can only archive threads that belong to Inbox folder. Archived threads will disappear from Inbox. Values: 0, 1.

Returns:

The result of the save operation.

class pypipedrive.models.organization_fields.OrganizationFields(**fields)

Organization fields represent the near-complete schema for an organization in the context of the company of the authorized user. Each company can have a different schema for their organizations, with various custom fields. In the context of using organization fields as a schema for defining the data fields of an organization, it must be kept in mind that some types of custom fields can have additional data fields which are not separate organization fields per se. Such is the case with monetary, daterange and timerange fields - each of these fields will have one additional data field in addition to the one presented in the context of organization fields. For example, if there is a monetary field with the key ffk9s9 stored on the account, ffk9s9 would hold the numeric value of the field, and ffk9s9_currency would hold the ISO currency code that goes along with the numeric value. To find out which data fields are available, fetch one organization and list its keys.

See OrganizationFields API reference.

Get all organization fields.

• GET[Cost:20] v1/organizationFields

Get one organization field.

• GET[Cost:2] v1/organizationFields/{id}

Add a new organization field. See: adding a new custom field.

• POST[Cost:10] v1/organizationFields

Updates an organization field. See: updating a custom field value.

• PUT[Cost:10] v1/organizationFields/{id}

Delete multiple organization fields in bulk.

• DELETE[Cost:10] v1/organizationFields

Delete an organization field. See: deleting a custom field.

• DELETE[Cost:6] v1/organizationFields/{id}

classmethod all(params: Dict = {}) → List[Self]

Returns data about all deal fields.

Allowed query parameters:

• start (int): Pagination start. Default: 0.

• limit (int): Items shown per page.

Args:

params: Query parameters for filtering and pagination.

Returns:

A list of DealFields instances.

classmethod batch_delete(*args, **kwargs) → Dict

Marks multiple deal fields as deleted.

delete(*args, **kwargs) → bool

Marks a field as deleted. For more information, see the tutorial for deleting a custom field.

classmethod get(id: int, params: Dict = {}) → Self

Returns data about a specific organization field.

Args:

id: The ID of the organization field to retrieve. params: Additional query parameters.

Returns:

An instance of OrganizationFields representing the organization field.

save(force: bool = False) → SaveResult

Adds a new deal field. For more information, see the tutorial for adding a new custom field.

The values for DealFields.field_type are:

• address: Address field

• date: Date (format YYYY-MM-DD)

• daterange: Date-range field (has a start/end date values YYYY-MM-DD)

• double: Numeric value

• enum: Options field with a single possible chosen option

• monetary: Monetary field (has a numeric value and a currency value)

• org: Org field (contains an org ID which is stored on the same account)

• people: Person field (contains a person ID which is stored on the same account)

• phone: Phone field (up to 255 numbers and/or characters)

• set: Options field with a possibility of having multiple chosen options

• text: Long text (up to 65k characters)

• time: Time field (format HH:MM:SS)

• timerange: Time-range field (has a start/end time values HH:MM:SS)

• user: User field (contains a user ID of another Pipedrive user)

• varchar: Text (up to 255 characters)

• varchar_auto: Autocomplete text (up to 255 characters)

• visible_to: System field that keeps item’s visibility setting

To update a deal field, the allowed updatable fields are (they are set at the instance level):

• name: The name of the field.

• options: When field_type is either set or enum, possible options must be supplied as a JSON-encoded sequential array of objects. All active items must be supplied and already existing items must have their ID supplied. New items only require a label. Example: [{“id”:123,”label”:”Existing Item”},{“label”:”New Item”}].

• add_visible_flag: Whether the field is available in ‘add new’ modal or not (both in web and mobile app). Default: True.

Args:

force: Whether to force the save operation.

Returns:

A SaveResult object containing the result of the save operation.

class pypipedrive.models.organization_relationships.OrganizationRelationships(**fields)

Organization relationships represent how different organizations are related to each other. The relationship can be hierarchical (parent-child companies) or lateral as defined by the type field - either parent or related.

See OrganizationRelationships API reference.

Get all relationships for organization.

• GET[Cost:20] v1/organizationRelationships

Get one organization relationship.

• GET[Cost:2] v1/organizationRelationships/{id}

Create an organization relationship.

• POST[Cost:10] v1/organizationRelationships

Update an organization relationship.

• PUT[Cost:10] v1/organizationRelationships/{id}

Delete an organization relationship.

• DELETE[Cost:6] v1/organizationRelationships/{id}

classmethod all(org_id: int) → List[Self]

Gets all of the relationships for a supplied organization ID.

Args:

org_id: The ID of the organization to get relationships for.

Returns:

A list of OrganizationRelationships instances.

classmethod batch_delete(*args, **kwargs)

Marks multiple entities as deleted. After 30 days, the entities will be permanently deleted. ids and models are mutually exclusive.

Args:

ids: A list of model IDs to delete. models: A list of model instances to delete.

delete(*args, **kwargs) → bool

Deletes an organization relationship and returns the deleted ID.

Returns:

A boolean indicating whether the deletion was successful.

classmethod get(id: int, org_id: int = None) → Self

Finds and returns an organization relationship from its ID.

Args:

id: The ID of the organization relationship. org_id: The ID of the base org for the returned calculated values.

Returns:

An OrganizationRelationships instance.

save(force: bool = False) → SaveResult

Updates and returns an organization relationship.

Allowed query parameters:

• org_id (int): The ID of the base organization for the returned calculated values.

• type (str): The type of relationship (parent or related).

• rel_owner_org_id (int): The owner of this relationship. If type is parent, then the owner is the parent and the linked organization is the daughter.

• rel_linked_org_id (int): The linked organization in this relationship. If type is parent, then the linked organization is the daughter.

To create a new organization relationship, type, rel_owner_org_id and rel_linked_org_id must be provided.

Args:

force: Whether to force the save operation.

Returns:

A SaveResult object containing the result of the save operation.

class pypipedrive.models.organizations.Organizations(**fields)

Organizations are companies and other kinds of organizations you are making deals with. Persons can be associated with organizations so that each organization can contain one or more persons.

See Organizations API reference.

Returns all organizations.

• GET[Cost:20] v1/organizations DEPRECATED

• GET[Cost:10] v2/organizations

Returns all organizations.

• GET[Cost:10] v1/organizations/collection DEPRECATED

Searches all organizations by name, address, notes and/or custom fields.

• GET[Cost:40] v1/organizations/search DEPRECATED

• GET[Cost:20] v2/organizations/search

Returns the details of a specific organization.

• GET[Cost:2] v1/organizations/{id} DEPRECATED

• GET[Cost:1] v2/organizations/{id}

Lists activities associated with an organization.

• GET[Cost:20] v1/organizations/{id}/activities DEPRECATED

Lists updates about field values of an organization.

• GET[Cost:20] v1/organizations/{id}/changelog

Lists deals associated with an organization.

• GET[Cost:20] v1/organizations/{id}/deals DEPRECATED

Lists files associated with an organization.

• GET[Cost:20] v1/organizations/{id}/files

List updates about an organization.

• GET[Cost:40] v1/organizations/{id}/flow

List followers of an organization.

• GET[Cost:10] v2/organizations/{id}/followers

List mail messages associated with an organization.

• GET[Cost:20] v1/organizations/{id}/mailMessages

List permitted users.

• GET[Cost:10] v1/organizations/{id}/permittedUsers

List persons of an organization.

• GET[Cost:20] v1/organizations/{id}/persons DEPRECATED

List followers changelog of an organization.

• GET[Cost:10] v2/organizations/{id}/followers/changelog

Add an organization.

• POST[Cost:5] v1/organizations DEPRECATED

• POST[Cost:5] v2/organizations

Add a follower to an organization.

• POST[Cost:10] v1/organizations/{id}/followers DEPRECATED

• POST[Cost:5] v2/organizations/{id}/followers

Update an organization.

• PUT[Cost:10] v1/organizations/{id} DEPRECATED

• PATCH[Cost:5] v2/organizations/{id}

Merge two organizations

• PUT[Cost:40] v1/organizations/{id}/merge

Delete multiple organizations in bulk.

• DELETE[Cost:10] v1/organizations DEPRECATED

Delete an organization.

• DELETE[Cost:6] v1/organizations/{id} DEPRECATED

• DELETE[Cost:3] v2/organizations/{id}

Delete a follower from an organization.

• DELETE[Cost:6] v1/organizations/{id}/followers/{follower_id} DEPRECATED

• DELETE[Cost:3] v2/organizations/{id}/followers/{follower_id}

add_follower(user_id: int) → Dict

Adds a user as a follower to the organization.

Args:

user_id: The ID of the user to add as a follower.

Returns:

The API response data as a dictionary.

classmethod all(*args, **kwargs) → List[Self]

Returns all organizations.

Allowed query parameters:

• filter_id (int): If supplied, only organizations matching the specified filter are returned.

• ids (str): Optional comma separated string array of up to 100 entity ids to fetch. If filter_id is provided, this is ignored. If any of the requested entities do not exist or are not visible, they are not included in the response.

• owner_id (int): If supplied, only organization owned by the specified user are returned. If filter_id is provided, this is ignored.

• updated_since (str): If set, only organizations with an update_time later than or equal to this time are returned. In RFC3339 format, e.g. 2025-01-01T10:20:00Z.

• updated_till (str): If set, only organizations with an update_time earlier than this time are returned. In RFC3339 format, e.g. 2025-01-01T10:20:00Z.

• sort_by (str): The field to sort by. Supported fields: id, update_time, add_time. Default: id.

• sort_direction (str): The sorting direction. Supported values: asc, desc. Default: asc.

• include_fields (str): Optional comma separated string array of additional fields to include.

• custom_fields (str): Optional comma separated string array of custom fields keys to include. If you are only interested in a particular set of custom fields, please use this parameter for faster results and smaller response. A maximum of 15 keys is allowed.

• limit (int): 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.

• cursor (str): For pagination, the marker (an opaque string value) representing the first item on the next page.

Returns:

List of Organization instances.

changelog(params: Dict = {}) → List[Dict]

V1 endpoint. Lists updates about field values of an organization.

Allowed query params:

• limit (int): Items shown per page.

• cursor (str): For pagination, the marker (an opaque string value) representing the first item on the next page.

Args:

params: Query params passed to the API (copied internally).

Returns:

Dictionary containing changelog data.

delete_follower(follower_id: int) → Dict

Deletes a user follower from the organization.

Args:

follower_id: The ID of the follower to delete.

Returns:

The API response data as a dictionary.

files(params: Dict = {}) → List[Files]

Lists files associated with an organization.

Allowed query params:

• start (int): Pagination start. Default: 0.

• limit (int): Amount of results to return. Max: 100.

• sort (str): Sort order. Possible values: “id”, “update_time”.

Args:

params: Query params passed to the API (copied internally).

Returns:

List of files data.

flow(params: Dict = {}) → Dict

Lists updates about an organization.

Allowed query params:

• start (int): Pagination start. Default: 0.

• limit (int): Amount of results to return. Default: 100. Max: 500.

• all_changes (str): Whether to show custom field updates or not. 1 = Include custom field changes. If omitted returns changes without custom field updates.

• items (str): A comma-separated string for filtering out item specific updates. Possible values: call, activity, plannedActivity, change, note, deal, file, dealChange, personChange, organizationChange, follower, dealFollower, personFollower, organizationFollower, participant, comment, mailMessage, mailMessageWithAttachment, invoice, document, marketing_campaign_stat, marketing_status_change.

Args:

params: Query params passed to the API (copied internally).

Returns:

Dictionary containing flow data.

followers(params: Dict = {}) → List[Dict]

Lists users who are following the organization.

Allowed query params:

• limit (int): Amount of results to return. Default: 100. Max: 500.

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

Args:

params: Query params passed to the API (copied internally).

Returns:

List of followers data.

followers_changelog(params: Dict = {}) → Dict

Lists changelogs about users have followed the organization.

Allowed query params:

• limit (int): Amount of results to return. Default: 100. Max: 500.

• cursor (str): For pagination, the marker (an opaque string value) representing the first item on the next page.

Args:

params: Query params passed to the API (copied internally).

Returns:

Dictionary containing changelog data.

mail_messages(params: Dict = {}) → List[Dict]

List mail messages associated with an organization.

Allowed query params:

• start (int): Pagination start. Default: 0.

• limit (int): Items shown per page.

Args:

params: Query params passed to the API (copied internally).

Returns:

List of mail messages data.

merge(merge_with_id: int) → Dict

Merges an organization with another organization. For more information, see the tutorial for merging two organizations.

Args:

merge_with_id: The ID of the orgnization to merge into this organization.

Returns:

The API response data as a dictionary.

permitted_users() → List[Dict]

List users permitted to access an organization.

Returns:

List of permitted users data.

classmethod search(term: str = None, params: Dict = {}) → List[ItemSearch]

Searches all organizations by name, address, notes and/or custom fields. This endpoint is a wrapper of /v1/itemSearch with a narrower OAuth scope.

Args:

term: The search term to look for. Minimum 2 characters (or 1 if using exact_match). Please note that the search term has to be URL encoded. params: Query params passed to the API (copied internally).

Returns:

List of ItemSearch objects.

class pypipedrive.models.person_fields.PersonFields(**fields)

Person fields represent the near-complete schema for a person in the context of the company of the authorized user. Each company can have a different schema for their persons, with various custom fields. In the context of using person fields as a schema for defining the data fields of a person, it must be kept in mind that some types of custom fields can have additional data fields which are not separate person fields per se. Such is the case with monetary, daterange and timerange fields - each of these fields will have one additional data field in addition to the one presented in the context of person fields. For example, if there is a monetary field with the key ffk9s9 stored on the account, ffk9s9 would hold the numeric value of the field, and ffk9s9_currency would hold the ISO currency code that goes along with the numeric value. To find out which data fields are available, fetch one person and list its keys.

See PersonFields API reference.

Get all person fields.

• GET[Cost:20] v1/personFields DEPRECATED

• GET[Cost:10] v2/personFields

Get one person field.

• GET[Cost:2] v1/personFields/{id} DEPRECATED

• GET[Cost:1] v2/personFields/{field_code}

Add a new person field.

• POST[Cost:10] v1/personFields DEPRECATED

• POST[Cost:5] v2/personFields

Add person field options in bulk.

• POST[Cost:5] v2/personFields/{field_code}/options

Update a person field.

• PUT[Cost:10] v1/personFields/{id} DEPRECATED

• PATCH[Cost:5] v2/personFields/{field_code}

Update person field options in bulk.

• PATCH[Cost:5] v2/personFields/{field_code}/options

Delete multiple person fields in bulk.

• DELETE[Cost:10] v1/personFields

Delete a person field.

• DELETE[Cost:6] v1/personFields/{id} DEPRECATED

• DELETE[Cost:3] v2/personFields/{field_code}

Delete person field options in bulk.

• DELETE[Cost:3] v2/personFields/{field_code}/options

add_options(option_labels: List[Dict[str, str]]) → Dict

Adds new options to a person custom field that supports options (enum or set field types). This operation is atomic - all options are added or none are added. Returns only the newly added options.

Args:

option_labels: A list of option dictionaries to add. Each item must contain a label. At least one option is required.

Returns:

A dictionary containing the newly added options.

classmethod batch_delete(ids: List[str]) → Dict

Marks multiple fields as deleted.

Args:

ids: A list of field codes to delete.

Returns:

A dictionary containing the result of the batch delete operation.

delete_options(option_ids: List[str]) → Dict

Removes existing options from a person custom field. This operation is atomic and fails if any of the specified option IDs do not exist. Returns only the deleted options.

Args:

option_ids: A list of option IDs to delete.

Returns:

A dictionary containing the deleted options.

classmethod get(id: str, params: Dict = {}) → Self

Returns metadata about a specific person field.

Allowed query params:

• include_fields (str): Optional comma separated string array of additional data namespaces to include in response. Values: ui_visibility, important_fields, required_fields.

Args:

id: The code of the person field to retrieve. params: Additional query parameters.

Returns:

An instance of PersonFields representing the person field.

update_options(options: List[Dict]) → Dict

Updates existing options for a person custom field. This operation is atomic and fails if any of the specified option IDs do not exist. Returns only the updated options.

Args:

options: A list of option dictionaries to update. Each item must contain an id and label.

Returns:

A dictionary containing the updated options.

class pypipedrive.models.persons.Persons(**fields)

Persons are your contacts, the customers you are doing deals with. Each person can belong to an organization. Persons should not be confused with users.

See Persons API reference.

Get all persons.

• GET[Cost:20] v1/persons DEPRECATED

• GET[Cost:10] v2/persons

Get all persons collection.

• GET[Cost:10] v1/persons/collection DEPRECATED

Search persons.

• GET[Cost:40] v1/persons/search DEPRECATED

• GET[Cost:20] v2/persons/search

Get details of a person.

• GET[Cost:2] v1/persons/{id} DEPRECATED

• GET[Cost:1] v2/persons/{id}

List activities associated with a person.

• GET[Cost:20] v1/persons/{id}/activities DEPRECATED

List updates about person field values.

• GET[Cost:20] v1/persons/{id}/changelog

List deals associated with a person.

• GET[Cost:20] v1/persons/{id}/deals DEPRECATED

List files attached to a person.

• GET[Cost:20] v1/persons/{id}/files

List updates about a person.

• GET[Cost:40] v1/persons/{id}/flow

List followers of a person.

• GET[Cost:20] v1/persons/{id}/followers DEPRECATED

• GET[Cost:10] v2/persons/{id}/followers

List mail messages associated with a person.

• GET[Cost:20] v1/persons/{id}/mailMessages

List permitted users.

• GET[Cost:10] v1/persons/{id}/permittedUsers

List products associated with a person.

• GET[Cost:20] v1/persons/{id}/products

List followers changelog of a person.

• GET[Cost:10] v2/persons/{id}/followers/changelog

Add a person.

• POST[Cost:10] v1/persons DEPRECATED

• POST[Cost:5] v2/persons

Add a follower to a person.

• POST[Cost:10] v1/persons/{id}/followers DEPRECATED

• POST[Cost:5] v2/persons/{id}/followers

Add person picture.

• POST[Cost:10] v1/persons/{id}/picture

Update a person.

• PUT[Cost:10] v1/persons/{id} DEPRECATED

• PATCH[Cost:5] v2/persons/{id}

Merge two persons.

• PUT[Cost:40] v1/persons/merge

Delete multiple persons in bulk.

• DELETE[Cost:10] v1/persons DEPRECATED

Delete a person.

• DELETE[Cost:6] v1/persons/{id} DEPRECATED

• DELETE[Cost:3] v2/persons/{id}

Delete a follower from a person.

• DELETE[Cost:6] v1/persons/{id}/followers/{follower_id} DEPRECATED

• DELETE[Cost:3] v2/persons/{id}/followers/{follower_id}

Delete person picture.

• DELETE[Cost:6] v1/persons/{id}/picture

add_follower(user_id: int) → Dict

Add a follower to a deal.

Args:

user_id: The ID of the user to add as a follower.

Returns:

The API response data as a dictionary.

add_picture(data: bytes, file_name: str, content_type: str, params: Dict = {}) → Dict

Adds a picture to a person. If a picture is already set, the old picture will be replaced. Added image (or the cropping parameters supplied with the request) should have an equal width and height and should be at least 128 pixels. GIF, JPG and PNG are accepted. All added images will be resized to 128 and 512 pixel wide squares.

Allowed query params:

• file (binary): One image supplied in the multipart/form-data encoding.

• crop_x (int): X coordinate to where start cropping form (in px).

• crop_y (int): Y coordinate to where start cropping form (in px).

• crop_width (int): The width of the cropping area (in pixels).

• crop_height (int): The height of the cropping area (in pixels).

Args:

data: The binary data of the image file. file_name: The name of the image file. content_type: The MIME type of the image file. params: Additional query parameters.

Returns:

The API response data as a dictionary.

classmethod batch_delete(*args, **kwargs) → Any

Marks multiple entities as deleted. After 30 days, the entities will be permanently deleted. ids and models are mutually exclusive.

Args:

ids: A list of model IDs to delete. models: A list of model instances to delete.

changelog(params: Dict = {}) → List[Dict]

V1 endpoint. Lists updates about field values of a person.

Allowed query params:

• limit (int): Amount of results to return. Default: 100. Max: 500.

• cursor (str): For pagination, the marker (an opaque string value) representing the first item on the next page.

Args:

params: Query params passed to the API (copied internally).

Returns:

Dictionary containing changelog data.

delete_follower(follower_id: int) → Dict

Deletes a user follower from the person.

Args:

follower_id: The ID of the follower to delete.

Returns:

The API response data as a dictionary.

delete_picture() → Dict

Deletes the picture of a person.

Returns:

The API response data as a dictionary.

files(params: Dict = {}) → List[Files]

Lists files associated with a person.

Allowed query params:

• start (int): Pagination start. Default: 0.

• limit (int): Amount of results to return. Max: 100.

• sort (str): Sort order. Possible values: “id”, “update_time”.

Args:

params: Query params passed to the API (copied internally).

Returns:

List of files data.

flow(params: Dict = {}) → Dict

Lists updates about a person. If a company uses the Campaigns product, then this endpoint’s response will also include updates for the marketing_status field.

See campaigns in Pipedrive API.

Allowed query params:

• start (int): Pagination start. Default: 0.

• limit (int): Amount of results to return. Default: 100. Max: 500.

• all_changes (str): Whether to show custom field updates or not. 1 = Include custom field changes. If omitted returns changes without custom field updates.

• items (str): A comma-separated string for filtering out item specific updates. Possible values: call, activity, plannedActivity, change, note, deal, file, dealChange, personChange, organizationChange, follower, dealFollower, personFollower, organizationFollower, participant, comment, mailMessage, mailMessageWithAttachment, invoice, document, marketing_campaign_stat, marketing_status_change.

Args:

params: Query params passed to the API (copied internally).

Returns:

Dictionary containing flow data.

followers(params: Dict = {}) → List[Dict]

Lists users who are following the person.

Allowed query params:

• limit (int): Amount of results to return. Default: 100. Max: 500.

• cursor (str): For pagination, the marker (an opaque string value) representing the first item on the next page.

Args:

params: Query params passed to the API (copied internally).

Returns:

List of followers data.

followers_changelog(params: Dict = {}) → Dict

Lists changelogs about users have followed the person.

Allowed query params:

• limit (int): Amount of results to return. Default: 100. Max: 500.

• cursor (str): For pagination, the marker (an opaque string value) representing the first item on the next page.

Args:

params: Query params passed to the API (copied internally).

Returns:

Dictionary containing changelog data.

mail_messages(params: Dict = {}) → List[Dict]

List mail messages associated with a person.

Allowed query params:

• start (int): Pagination start. Default: 0.

• limit (int): Items shown per page.

Args:

params: Query params passed to the API (copied internally).

Returns:

List of mail messages data.

merge(merge_with_id: int) → Dict

Merges a person with another person. For more information, see the tutorial for merging two persons.

If the person doesn’t exist defined in merge_with_id, a 403 error code is returned.

Args:

merge_with_id: The ID of the person to merge into this person.

Returns:

The API response data as a dictionary.

permitted_users() → List[Dict]

Lists the users permitted to access a person.

Returns:

List of permitted users data.

products(params: Dict = {}) → List[Dict]

List products attached to a deal.

Allowed query params:

• limit (int): Amount of results to return. Default: 100. Max: 500.

• cursor (str): For pagination, the marker (an opaque string value) representing the first item on the next page.

• sort_by (str): Field to sort by. Default “id”. Values: “id”, “add_time”, “update_time”, “order_nr”.

• sort_direction (str): Sort direction. Default “asc”.

Args:

params: Query params passed to the API (copied internally).

Returns:

List of products data.

classmethod search(term: str = None, params: Dict = {}) → List[ItemSearch]

Searches all persons by name, email, phone, notes and/or custom fields. This endpoint is a wrapper of /v2/itemSearch with a narrower OAuth scope. Found persons can be filtered by organization ID.

Allowed query parameters:

• fields (str): A comma-separated string array. The fields to perform the search from. Defaults to all of them. Only the following custom field types are searchable: address, varchar, text, varchar_auto, double, monetary and phone. Read more about searching by custom fields.

• exact_match (bool): When enabled, only full exact matches against the given term are returned. It is not case sensitive.

• organization_id (int): Will filter persons by the provided organization ID. The upper limit of found persons associated with the organization is 2000.

• include_fields (str): Supports including optional fields in the results which are not provided by default. Values: person.picture.

• limit (int): 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.

• cursor (str): For pagination, the marker (an opaque string value) representing the first item on the next page.

Args:

term: The search term to look for. Minimum 2 characters (or 1 if using exact_match). Please note that the search term has to be URL encoded. params: Query params passed to the API (copied internally).

Returns:

List of ItemSearch objects.

class pypipedrive.models.pipelines.Pipelines(**fields)

Pipelines are essentially ordered collections of stages.

See Pipelines API reference.

Get all pipelines.

• GET[Cost:10] v1/pipelines DEPRECATED

• GET[Cost:5] v2/pipelines

Get one pipeline.

• GET[Cost:2] v1/pipelines/{id} DEPRECATED

• GET[Cost:1] v2/pipelines/{id}

Get deals conversion rates in pipeline.

• GET[Cost:40] v1/pipelines/{id}/conversion_statistics

Get deals in a pipeline.

• GET[Cost:20] v1/pipelines/{id}/deals DEPRECATED

Get deals movements in pipeline.

• GET[Cost:40] v1/pipelines/{id}/movement_statistics

Add a new pipeline.

• POST[Cost:10] v1/pipelines DEPRECATED

• POST[Cost:5] v2/pipelines

Update a pipeline.

• PUT[Cost:10] v1/pipelines/{id} DEPRECATED

• PATCH[Cost:5] v2/pipelines/{id}

Delete a pipeline.

• DELETE[Cost:6] v1/pipelines/{id} DEPRECATED

• DELETE[Cost:3] v2/pipelines/{id}

classmethod batch_delete(*args, **kwargs)

Marks multiple entities as deleted. After 30 days, the entities will be permanently deleted. ids and models are mutually exclusive.

Args:

ids: A list of model IDs to delete. models: A list of model instances to delete.

conversion_statistics(start_date: str | date, end_date: str | date, user_id: int = None) → Dict

Returns all stage-to-stage conversion and pipeline-to-close rates for the given time period.

Args:

start_date: Start date in format YYYY-MM-DD. end_date: End date in format YYYY-MM-DD. user_id: Optional user ID to filter statistics.

Returns:

A dictionary with conversion statistics.

movement_statistics(start_date: str | date, end_date: str | date, user_id: int = None) → Dict

Returns statistics for deals movements for the given time period.

Args:

start_date: Start date in format YYYY-MM-DD. end_date: End date in format YYYY-MM-DD. user_id: Optional user ID to filter statistics.

Returns:

A dictionary with movement statistics.

class pypipedrive.models.product_fields.ProductFields(**fields)

Product fields represent the near-complete schema for a product in the context of the company of the authorized user. Each company can have a different schema for their products, with various custom fields. In the context of using product fields as a schema for defining the data fields of a product, it must be kept in mind that some types of custom fields can have additional data fields which are not separate product fields per se. Such is the case with monetary, daterange and timerange fields - each of these fields will have one additional data field in addition to the one presented in the context of product fields. For example, if there is a monetary field with the key ffk9s9 stored on the account, ffk9s9 would hold the numeric value of the field, and ffk9s9_currency would hold the ISO currency code that goes along with the numeric value. To find out which data fields are available, fetch one product and list its keys.

See ProductFields API reference.

Get all product fields.

• GET[Cost:10] v1/productFields

• GET[Cost:20] v2/productFields

Get one product field.

• GET[Cost:2] v1/productFields/{id}

• GET[Cost:1] v2/productFields/{field_code}

Add a new product field.

• POST[Cost:10] v1/productFields

• POST[Cost:5] v2/productFields

Update a product field

• PUT[Cost:10] v1/productFields/{id}

Delete multiple product fields in bulk

• DELETE[Cost:10] v1/productFields

Delete a product field

• DELETE[Cost:6] v1/productFields/{id}

class pypipedrive.models.products.Products(**fields)

Products are the goods or services you are dealing with. Each product can have N different price points - firstly, each product can have a price in N different currencies, and secondly, each product can have N variations of itself, each having N prices in different currencies. Note that only one price per variation per currency is supported. Products can be instantiated to deals. In the context of instatiation, a custom price, quantity, duration and discount can be applied.

See Products API reference.

Get all products.

• GET[Cost:20] v1/products DEPRECATED

• GET[Cost:10] v2/products

Search products.

• GET[Cost:40] v1/products/search DEPRECATED

• GET[Cost:20] v2/products/search

Get one product.

• GET[Cost:20] v1/products/{id} DEPRECATED

• GET[Cost:10] v2/products/{id}

Get deals where a product is attached to.

• GET[Cost:20] v1/products/{id}/deals

List files attached to a product

• GET[Cost:20] v1/products/{id}/files

List followers of a product

• GET[Cost:20] v1/products/{id}/followers DEPRECATED

• GET[Cost:10] v2/products/{id}/followers

List permitted users.

• GET[Cost:20] v1/products/{id}/permittedUsers

List followers changelog of a product.

• GET[Cost:10] v2/products/{id}/followers/changelog

Get all product variations.

• GET[Cost:10] v2/products/{id}/variations

Get image of a product [BETA].

• GET[Cost:10] v2/products/{id}/images

Add a product.

• POST[Cost:10] v1/products DEPRECATED

• POST[Cost:5] v2/products

Add a follower to a product.

• POST[Cost:10] v1/products/{id}/followers DEPRECATED

• POST[Cost:5] v2/products/{id}/followers

Duplicate a product.

• POST[Cost:5] v2/products/{id}/duplicate

Add a product variation.

• POST[Cost:5] v2/products/{id}/variations

Upload an image for a product [BETA].

• POST[Cost:5] v2/products/{id}/images

Update a product.

• PUT[Cost:10] v1/products/{id} DEPRECATED

• PATCH[Cost:5] v2/products/{id}

Update an image for a product [BETA].

• PUT[Cost:20] v2/products/{id}/images

Delete a product.

• DELETE[Cost:6] v1/products/{id} DEPRECATED

• DELETE[Cost:3] v2/products/{id}

Delete a follower from a product.

• DELETE[Cost:6] v1/products/{id}/followers/{follower_id} DEPRECATED

• DELETE[Cost:3] v2/products/{id}/followers/{follower_id}

Delete a product variation.

• DELETE[Cost:3] v2/products/{id}/variations/{product_variation_id}

Delete the image of a product.

• DELETE[Cost:6] v2/products/{id}/images

add_follower(user_id: int = None) → Dict

Add a follower to a product.

Args:

user_id: The ID of the user to add as a follower.

Returns:

The API response data as a dictionary.

add_image(data: bytes = None, file_name: str = None, content_type: str = None) → Dict

[BETA] Upload an image for a product.

Args:

data: One image supplied in the multipart/form-data encoding.

Returns:

The API response data as a dictionary.

add_variation(name: str = None, prices: List[Dict | PriceDict] = []) → Dict

Add a product variation.

Args:

name: The name of the product variation. prices: A list of price dictionaries/instances for the variation.

classmethod batch_delete(*args, **kwargs) → Any

Marks multiple entities as deleted. After 30 days, the entities will be permanently deleted. ids and models are mutually exclusive.

Args:

ids: A list of model IDs to delete. models: A list of model instances to delete.

deals(status: str = None, params: Dict = {}) → List[Dict]

List deals attached to a product.

Allowed query params:

• limit (int): Amount of results to return. Default: 100. Max: 500.

• cursor (str): For pagination, the marker (an opaque string value) representing the first item on the next page.

• status (str): 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. Default all_not_deleted. Values: open, won, lost, deleted, all_not_deleted.

Args:

status (str): Filter deals by status. params: Query params passed to the API (copied internally).

Returns:

List of deals data.

delete_follower(follower_id: int = None) → Dict

Delete a follower from a product.

Args:

follower_id: The ID of the follower to delete.

Returns:

The API response as a dictionary.

delete_image() → Dict

[BETA] Delete an image for a product.

Returns:

The API response data as a dictionary.

delete_variation(product_variation_id: int = None) → Dict

Delete a product variation.

Args:

product_variation_id: The ID of the product variation to delete.

Returns:

The API response as a dictionary.

duplicate() → Self

Duplicate a product.

Returns:

The newly created Product instance.

files(params: Dict = {}) → List[Files]

List files attached to a product.

Allowed query params:

• start (int): The starting offset of the page.

• limit (int): Amount of results to return. Default: 100. Max: 500.

• sort (str): Supported fields: id, update_time

Args:

params: Query params passed to the API (copied internally).

Returns:

A list of file objects.

followers(params: Dict = {}) → List[Dict]

List followers of a product.

Allowed query params:

• limit (int): Amount of results to return. Default: 100. Max: 500.

• cursor (str): For pagination, the marker (an opaque string value) representing the first item on the next page.

Args:

params: Query params passed to the API (copied internally).

Returns:

A list of follower dictionaries.

followers_changelog(params: Dict = {}) → List[Dict]

List followers changelog of a product.

Allowed query params:

• limit (int): Amount of results to return. Default: 100. Max: 500.

• cursor (str): For pagination, the marker (an opaque string value) representing the first item on the next page.

Args:

params: Query params passed to the API (copied internally).

Returns:

A list of follower changelog dictionaries.

images() → List[Dict]

Get image of a product [BETA].

Returns:

A list of product image dictionaries.

permitted_users() → List[Dict]

List permitted users of a product.

Returns:

A list of permitted user dictionaries.

classmethod search(term: str = None, params: Dict = {}) → List[ItemSearch]

Searches all products by name, code and/or custom fields. This endpoint is a wrapper of /v1/itemSearch with a narrower OAuth scope.

Allowed query params:

• term (str): The search term to look for.

• fields (str): Comma-separated list of fields to search in.

• exact_match (bool): full exact matches against the given term returned?

• include_fields (str): optional fields to include (comma-separated).

• limit (int): number of results to return (default: 10, max: 100).

• cursor (str): cursor for pagination.

Args:

term: The search term to look for. Minimum 2 characters (or 1 if using exact_match). Please note that the search term has to be URL encoded. params: Query params passed to the API (copied internally).

Returns:

List of ItemSearch objects.

update_image(data: bytes = None, file_name: str = None, content_type: str = None) → Dict

[BETA] Update an image for a product.

Args:

data: One image supplied in the multipart/form-data encoding. file_name: The name of the file. content_type: The MIME type of the file.

Returns:

The API response data as a dictionary.

variations(params: Dict = {}) → List[Dict]

Get all product variations.

Allowed query params:

• limit (int): Amount of results to return. Default: 100. Max: 500.

• cursor (str): For pagination, the marker (an opaque string value) representing the first item on the next page.

Args:

params: Query params passed to the API (copied internally).

Returns:

A list of product variation dictionaries.

class pypipedrive.models.stages.Stages(**fields)

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.

See Stages API reference.

Get all stages.

• GET[Cost:10] v1/stages DEPRECATED

• GET[Cost:5] v2/stages

Get one stage.

• GET[Cost:2] v1/stages/{id} DEPRECATED

• GET[Cost:1] v2/stages/{id}

Get deals in a stage.

• GET[Cost:20] v1/stages/{id}/deals DEPRECATED

Add a new stage.

• POST[Cost:10] v1/stages DEPRECATED

• POST[Cost:5] v2/stages

Update stage details.

• PUT[Cost:10] v1/stages/{id} DEPRECATED

• PATCH[Cost:5] v2/stages/{id}

Delete multiple stages in bulk.

• DELETE[Cost:10] v1/stages DEPRECATED

Delete a stage.

• DELETE[Cost:6] v1/stages/{id} DEPRECATED

• DELETE[Cost:3] v2/stages/{id}

classmethod all(params: Dict = {}) → List[Self]

Returns data about all stages.

Allowed query parameters:

• pipeline_id (int): The ID of the pipeline to fetch stages for. If omitted, stages for all pipelines will be fetched.

• sort_by (str): The field to sort by. Supported fields: id (default), update_time, add_time, order_nr.

• sort_direction (str): The sorting direction. Supported values: asc (default), desc.

• limit (int): 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.

• cursor (str): For pagination, the marker (an opaque string value) representing the first item on the next page.

Args:

params: Additional query parameters.

Returns:

A list of Stages instances.

classmethod batch_delete(*args, **kwargs)

Marks multiple entities as deleted. After 30 days, the entities will be permanently deleted. ids and models are mutually exclusive.

Args:

ids: A list of model IDs to delete. models: A list of model instances to delete.