openapi: 3.0.1 info: title: Pipedrive API v1 Activities Organizations API version: 1.0.0 description: 'Activities are appointments/tasks/events on a calendar that can be associated with a deal, a lead, a person and an organization. Activities can be of different type (such as call, meeting, lunch or a custom type - see ActivityTypes object) and can be assigned to a particular user. Note that activities can also be created without a specific date/time. ' servers: - url: https://api.pipedrive.com/v1 tags: - name: Organizations description: '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. ' paths: /organizations/{id}/changelog: get: summary: List updates about organization field values description: Lists updates about field values of an organization. x-token-cost: 20 operationId: getOrganizationChangelog tags: - Organizations security: - api_key: [] - oauth2: - recents:read parameters: - in: path name: id description: The ID of the organization required: true schema: type: integer - in: query name: cursor description: For pagination, the marker (an opaque string value) representing the first item on the next page schema: type: string - in: query name: limit description: Items shown per page schema: type: integer responses: '200': description: Get changelog of an organization content: application/json: schema: title: GetChangelogResponse allOf: - title: baseResponse type: object properties: success: type: boolean description: If the response is successful or not - type: object properties: data: type: array items: type: object properties: field_key: type: string description: The key of the field that was changed old_value: type: string nullable: true description: The value of the field before the change new_value: type: string nullable: true description: The value of the field after the change actor_user_id: type: integer description: The ID of the user who made the change time: type: string description: The date and time of the change change_source: type: string nullable: true description: The source of change, for example 'app', 'mobile', 'api', etc. change_source_user_agent: type: string nullable: true description: The user agent from which the change was made is_bulk_update_flag: type: boolean description: Whether the change was made as part of a bulk update additional_data: description: The additional data of the list type: object properties: next_cursor: type: string description: The first item on the next page. The value of the `next_cursor` field will be `null` if you have reached the end of the dataset and there’s no more pages to be returned. example: success: true data: - field_key: name old_value: Org 10 new_value: Org 11 actor_user_id: 26 time: '2024-02-12 09:14:35' change_source: app change_source_user_agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36 is_bulk_update_flag: false - field_key: 51c27e4a19c3bedd91162a9d446707c1f95174ea old_value: '0' new_value: '20' actor_user_id: 26 time: '2024-02-12 09:10:12' change_source: app change_source_user_agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36 is_bulk_update_flag: false additional_data: next_cursor: aWQ6NTQ0 /organizations/{id}/files: get: summary: List files attached to an organization description: Lists files associated with an organization. x-token-cost: 20 operationId: getOrganizationFiles tags: - Organizations security: - api_key: [] - oauth2: - contacts:read - contacts:full parameters: - in: path name: id description: The ID of the organization required: true schema: type: integer - in: query name: start description: Pagination start schema: type: integer default: 0 - in: query name: limit description: Items shown per page. Please note that a maximum value of 100 is allowed. schema: type: integer maximum: 100 - in: query name: sort schema: type: string description: 'Supported fields: `id`, `update_time`' responses: '200': description: Success content: application/json: schema: title: GetAssociatedFilesResponse allOf: - title: baseResponse type: object properties: success: type: boolean description: If the response is successful or not - type: object properties: data: type: array items: type: object description: The file data properties: id: type: integer description: The ID of the file user_id: type: integer description: The ID of the user to associate the file with deal_id: type: integer description: The ID of the deal to associate the file with person_id: type: integer description: The ID of the person to associate the file with org_id: type: integer description: The ID of the organization to associate the file with product_id: type: integer description: The ID of the product to associate the file with activity_id: type: integer description: The ID of the activity to associate the file with lead_id: type: string description: The ID of the lead to associate the file with format: uuid add_time: type: string description: 'The date and time when the file was added/created. Format: YYYY-MM-DD HH:MM:SS' update_time: type: string description: 'The last updated date and time of the file. Format: YYYY-MM-DD HH:MM:SS' file_name: type: string description: The original name of the file file_size: type: integer description: The size of the file active_flag: type: boolean description: Whether the user is active or not. false = Not activated, true = Activated inline_flag: type: boolean description: Whether the file was uploaded as inline or not remote_location: type: string description: The location type to send the file to. Only googledrive is supported at the moment. remote_id: type: string description: The ID of the remote item cid: type: string description: The ID of the inline attachment s3_bucket: type: string description: The location of the cloud storage mail_message_id: type: string description: The ID of the mail message to associate the file with mail_template_id: type: string description: The ID of the mail template to associate the file with deal_name: type: string description: The name of the deal associated with the dile person_name: type: string description: The name of the person associated with the file org_name: type: string description: The name of the organization associated with the file product_name: type: string description: The name of the product associated with the file lead_name: type: string description: The name of the lead associated with the file url: type: string description: The URL of the download file name: type: string description: The visible name of the file description: type: string description: The description of the file description: The array of files additional_data: description: The additional data of the list type: object properties: start: type: integer description: Pagination start limit: type: integer description: Items shown per page more_items_in_collection: type: boolean description: If there are more list items in the collection than displayed or not example: success: true data: - id: 1 user_id: 8877 deal_id: 1 person_id: 1 org_id: 1480 product_id: 1 activity_id: 1 lead_id: adf21080-0e10-11eb-879b-05d71fb426ec log_id: null add_time: '2020-09-16 11:19:36' update_time: '2020-09-16 11:19:36' file_name: 95781006_794143070992462_4330873630616453120_n_60817458877506f9eb74d03e5ef9ba061915b797998.jpg file_type: img file_size: 95116 active_flag: true inline_flag: false remote_location: s3 remote_id: 95781006_794143070992462_4330873630616453120_n.jpg cid: '' s3_bucket: '' mail_message_id: '' mail_template_id: '' deal_name: nice deal person_name: '' people_name: '' org_name: Pipedrive Inc. product_name: '' lead_name: nice lead url: https://app.pipedrive.com/api/v1/files/304/download name: 95781006_794143070992462_4330873630616453120_n.jpg description: '' additional_data: pagination: start: 0 limit: 100 more_items_in_collection: true /organizations/{id}/flow: get: summary: List updates about an organization description: Lists updates about an organization. x-token-cost: 40 operationId: getOrganizationUpdates tags: - Organizations security: - api_key: [] - oauth2: - recents:read parameters: - in: path name: id description: The ID of the organization required: true schema: type: integer - in: query name: start description: Pagination start schema: type: integer default: 0 - in: query name: limit description: Items shown per page schema: type: integer - in: query name: all_changes description: Whether to show custom field updates or not. 1 = Include custom field changes. If omitted, returns changes without custom field updates. schema: type: string - in: query name: items description: A comma-separated string for filtering out item specific updates. (Possible values - activity, plannedActivity, note, file, change, deal, follower, participant, mailMessage, mailMessageWithAttachment, invoice, activityFile, document). schema: type: string responses: '200': description: Get the organization updates content: application/json: schema: title: GetAssociatedOrganizationUpdatesResponse allOf: - title: baseResponse type: object properties: success: type: boolean description: If the response is successful or not - type: object properties: data: type: array items: type: object properties: object: type: string description: The type of the person update. (Possible object types - organizationChange, dealChange, file, activity) timestamp: type: string description: The creation date and time of the update data: type: object description: The data related to the update additional_data: description: The additional data of the list type: object properties: start: type: integer description: Pagination start limit: type: integer description: Items shown per page more_items_in_collection: type: boolean description: If there are more list items in the collection than displayed or not related_objects: type: object properties: organization: type: object title: RelatedOrganizationData properties: ORGANIZATION_ID: type: object title: OrganizationDataWithId description: The ID of the organization associated with the item allOf: - type: object properties: id: type: integer description: The ID of the organization associated with the item - type: object properties: name: type: string description: The name of the organization associated with the item people_count: type: integer description: The number of people connected with the organization that is associated with the item owner_id: type: integer description: The ID of the owner of the organization that is associated with the item address: type: string nullable: true description: The address of the organization cc_email: type: string nullable: true description: The BCC email of the organization associated with the item user: type: object properties: USER_ID: type: object title: userDataWithId allOf: - properties: id: type: integer description: The ID of the user name: type: string description: The name of the user email: type: string description: The email of the user has_pic: type: integer description: Whether the user has picture or not. 0 = No picture, 1 = Has picture. pic_hash: type: string nullable: true description: The user picture hash active_flag: type: boolean description: Whether the user is active or not - type: object description: The ID of the user example: success: true data: - object: organizationChange timestamp: '2020-09-15 11:55:14' data: id: 3694 item_id: 1480 user_id: 9271535 field_key: owner_id old_value: 9271535 new_value: 8877 is_bulk_update_flag: null log_time: '2020-09-15 11:55:14' change_source: app change_source_user_agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6) AppleWebKit/537.36 (KHTML like Gecko) Chrome/84.0.4147.135 Safari/537.36 additional_data: new_value_formatted: Will Smith old_value_formatted: Robert Smith - object: activity timestamp: '2020-08-07 08:15:00' data: id: 8 company_id: 22122 user_id: 1234 done: false type: deadline reference_type: scheduler-service reference_id: 7 conference_meeting_client: 871b8bc88d3a1202 conference_meeting_url: https://pipedrive.zoom.us/link conference_meeting_id: '17058746701' due_date: '2020-06-09' due_time: '10:00' duration: 01:00 busy_flag: true add_time: '2020-06-08 12:37:56' marked_as_done_time: '2020-08-08 08:08:38' last_notification_time: '2020-08-08 12:37:56' last_notification_user_id: 7655 notification_language_id: 1 subject: Deadline public_description: This is a description calendar_sync_include_context: '' location: Mustamäe tee 3, Tallinn, Estonia org_id: 5 person_id: 1101 deal_id: 300 lead_id: 46c3b0e1-db35-59ca-1828-4817378dff71 project_id: null active_flag: true update_time: '2020-08-08 12:37:56' update_user_id: 5596 gcal_event_id: '' google_calendar_id: '' google_calendar_etag: '' source_timezone: '' rec_rule: RRULE:FREQ=WEEKLY;BYDAY=WE rec_rule_extension: '' rec_master_activity_id: 1 series: [] note: A note for the activity created_by_user_id: 1234 location_subpremise: '' location_street_number: '3' location_route: Mustamäe tee location_sublocality: Kristiine location_locality: Tallinn location_admin_area_level_1: Harju maakond location_admin_area_level_2: '' location_country: Estonia location_postal_code: '10616' location_formatted_address: Mustamäe tee 3, 10616 Tallinn, Estonia attendees: - email_address: attendee@pipedrivemail.com is_organizer: 0 name: Attendee person_id: 25312 status: noreply user_id: null participants: - person_id: 17985 primary_flag: false - person_id: 1101 primary_flag: true org_name: Organization person_name: Person deal_title: Deal owner_name: Creator person_dropbox_bcc: company@pipedrivemail.com deal_dropbox_bcc: company+deal300@pipedrivemail.com assigned_to_user_id: 1235 file: id: 376892, clean_name: Audio 10:55:07.m4a url: https://pipedrive-files.s3-eu-west-1.amazonaws.com/Audio-recording.m4a - object: file timestamp: '2020-08-10 11:52:26' data: id: 1 user_id: 8877 deal_id: 1 person_id: 1 org_id: 1480 product_id: 1 activity_id: 1 lead_id: adf21080-0e10-11eb-879b-05d71fb426ec log_id: null add_time: '2020-09-16 11:19:36' update_time: '2020-09-16 11:19:36' file_name: 95781006_794143070992462_4330873630616453120_n_60817458877506f9eb74d03e5ef9ba061915b797998.jpg file_type: img file_size: 95116 active_flag: true inline_flag: false remote_location: s3 remote_id: 95781006_794143070992462_4330873630616453120_n.jpg cid: '' s3_bucket: '' mail_message_id: '' mail_template_id: '' deal_name: nice deal person_name: '' people_name: '' org_name: Pipedrive Inc. product_name: '' lead_name: nice lead url: https://app.pipedrive.com/api/v1/files/304/download name: 95781006_794143070992462_4330873630616453120_n.jpg description: '' additional_data: pagination: start: 0 limit: 100 more_items_in_collection: true related_objects: allOf: - user: '123': id: 123 name: Jane Doe email: jane@pipedrive.com has_pic: 1 pic_hash: 2611ace8ac6a3afe2f69ed56f9e08c6b active_flag: true - organization: '1': id: 1 name: Org Name people_count: 1 owner_id: 123 address: Mustamäe tee 3a, 10615 Tallinn active_flag: true cc_email: org@pipedrivemail.com /organizations/{id}/followers: get: summary: List followers of an organization description: Lists the followers of an organization. x-token-cost: 20 operationId: getOrganizationFollowers tags: - Organizations security: - api_key: [] - oauth2: - contacts:read - contacts:full parameters: - in: path name: id description: The ID of the organization required: true schema: type: integer responses: '200': description: Success content: application/json: schema: title: GetAssociatedFollowersResponse type: object properties: success: type: boolean description: If the request was successful or not data: type: array description: The array of followers items: allOf: - type: object properties: org_id: type: integer description: The ID of the organization - type: object properties: user_id: type: integer description: The user ID of the follower related to the item id: type: integer description: The ID of the follower add_time: type: string format: date-time description: The date and time of adding the follower to the item additional_data: type: object properties: pagination: description: Pagination details of the list type: object properties: start: type: integer description: Pagination start limit: type: integer description: Items shown per page more_items_in_collection: type: boolean description: Whether there are more list items in the collection than displayed next_start: type: integer description: Next pagination start example: success: true data: - user_id: 100 id: 123 org_id: 77 add_time: '2020-09-08 08:17:52' additional_data: pagination: start: 0 limit: 100 more_items_in_collection: false next_start: 100 post: summary: Add a follower to an organization description: Adds a follower to an organization. x-token-cost: 10 operationId: addOrganizationFollower tags: - Organizations security: - api_key: [] - oauth2: - contacts:full parameters: - in: path name: id description: The ID of the organization required: true schema: type: integer requestBody: content: application/json: schema: title: addOrganizationFollowerRequest type: object required: - user_id properties: user_id: type: integer description: The ID of the user responses: '200': description: Success content: application/json: schema: title: AddOrganizationFollowerResponse type: object properties: success: type: boolean description: If the request was successful or not data: allOf: - type: object properties: org_id: type: integer description: The ID of the organization - type: object properties: user_id: type: integer description: The user ID of the follower related to the item id: type: integer description: The ID of the follower add_time: type: string format: date-time description: The date and time of adding the follower to the item example: success: true data: user_id: 100 id: 123 org_id: 77 add_time: '2020-09-08 08:17:52' /organizations/{id}/followers/{follower_id}: delete: summary: Delete a follower from an organization description: Deletes a follower from an organization. You can retrieve the `follower_id` from the List followers of an organization endpoint. x-token-cost: 6 operationId: deleteOrganizationFollower tags: - Organizations security: - api_key: [] - oauth2: - contacts:full parameters: - in: path name: id description: The ID of the organization required: true schema: type: integer - in: path name: follower_id required: true schema: type: integer description: The ID of the relationship between the follower and the organization responses: '200': description: Success content: application/json: schema: title: DeleteOrganizationFollowerResponse type: object properties: success: type: boolean description: If the request was successful or not data: type: object properties: id: type: integer description: The ID of the follower that was deleted from the organization example: success: true data: id: 123 /organizations/{id}/mailMessages: get: summary: List mail messages associated with an organization description: Lists mail messages associated with an organization. x-token-cost: 20 operationId: getOrganizationMailMessages tags: - Organizations security: - api_key: [] - oauth2: - mail:read - mail:full parameters: - in: path name: id description: The ID of the organization required: true schema: type: integer - in: query name: start description: Pagination start schema: type: integer default: 0 - in: query name: limit description: Items shown per page schema: type: integer responses: '200': description: Success content: application/json: schema: title: GetAssociatedMailMessagesResponse allOf: - title: baseResponse type: object properties: success: type: boolean description: If the response is successful or not - type: object properties: data: type: array description: The array of mail messages items: type: object properties: object: type: string description: The type of the data item timestamp: type: string description: The date and time when the item was created data: title: mailMessageItemForList allOf: - type: object title: MailMessageData properties: id: description: ID of the mail message. type: integer from: type: array description: The array of mail message sender (object) items: type: object properties: id: description: ID of the mail participant type: integer email_address: description: Mail address of the mail participant type: string name: description: Name of the mail participant type: string linked_person_id: description: ID of the linked person to the mail message type: integer linked_person_name: description: Name of the linked person to the mail message type: string mail_message_party_id: description: ID of the mail message participant type: integer to: type: array description: The array of mail message receiver (object) items: type: object properties: id: description: ID of the mail participant type: integer email_address: description: Mail address of the mail participant type: string name: description: Name of the mail participant type: string linked_person_id: description: ID of the linked person to the mail message type: integer linked_person_name: description: Name of the linked person to the mail message type: string mail_message_party_id: description: ID of the mail message participant type: integer cc: type: array description: The array of mail message copies (object) items: type: object properties: id: description: ID of the mail participant type: integer email_address: description: Mail address of the mail participant type: string name: description: Name of the mail participant type: string linked_person_id: description: ID of the linked person to the mail message type: integer linked_person_name: description: Name of the linked person to the mail message type: string mail_message_party_id: description: ID of the mail message participant type: integer bcc: type: array description: The array of mail message blind copies (object) items: type: object properties: id: description: ID of the mail participant type: integer email_address: description: Mail address of the mail participant type: string name: description: Name of the mail participant type: string linked_person_id: description: ID of the linked person to the mail message type: integer linked_person_name: description: Name of the linked person to the mail message type: string mail_message_party_id: description: ID of the mail message participant type: integer body_url: type: string description: The mail message body URL account_id: type: string description: The connection account ID user_id: type: integer description: ID of the user whom mail message will be assigned to mail_thread_id: type: integer description: ID of the mail message thread subject: type: string description: The subject of mail message snippet: type: string description: The snippet of mail message. Snippet length is up to 225 characters. mail_tracking_status: type: string nullable: true description: The status of tracking mail message. Value is `null` if tracking is not enabled. enum: - opened - not opened mail_link_tracking_enabled_flag: description: Whether the link tracking in mail message body is enabled. allOf: - title: numberBooleanDefault0 type: number default: 0 enum: - 0 - 1 read_flag: description: Whether the mail message is read or not by the user allOf: - title: numberBooleanDefault0 type: number default: 0 enum: - 0 - 1 draft: type: string description: If the mail message has a draft status then the value is the mail message object as JSON formatted string, otherwise `null`. draft_flag: description: Whether the mail message is a draft or not allOf: - title: numberBooleanDefault0 type: number default: 0 enum: - 0 - 1 synced_flag: description: Whether the mail message is synced with the provider or not allOf: - title: numberBooleanDefault0 type: number default: 0 enum: - 0 - 1 deleted_flag: allOf: - title: numberBooleanDefault0 type: number default: 0 enum: - 0 - 1 description: Whether the mail message is deleted or not has_body_flag: description: Whether the mail message has a body or not allOf: - title: numberBooleanDefault0 type: number default: 0 enum: - 0 - 1 sent_flag: description: Whether the mail message has been sent or not allOf: - title: numberBooleanDefault0 type: number default: 0 enum: - 0 - 1 sent_from_pipedrive_flag: description: Whether the mail message has been sent from Pipedrive app or not allOf: - title: numberBooleanDefault0 type: number default: 0 enum: - 0 - 1 smart_bcc_flag: description: Whether the mail message has been created by Smart Email BCC feature or not allOf: - title: numberBooleanDefault0 type: number default: 0 enum: - 0 - 1 message_time: type: string format: date-time description: Creation or receival time of the mail message add_time: type: string format: date-time description: The insertion into the database time of the mail message update_time: type: string format: date-time description: The updating time in the database of the mail message has_attachments_flag: description: Whether the mail message has an attachment or not allOf: - title: numberBooleanDefault0 type: number default: 0 enum: - 0 - 1 has_inline_attachments_flag: description: Whether the mail message has an inline attachment or not allOf: - title: numberBooleanDefault0 type: number default: 0 enum: - 0 - 1 has_real_attachments_flag: description: Whether the mail message has an attachment (which is not inline) or not allOf: - title: numberBooleanDefault0 type: number default: 0 enum: - 0 - 1 - type: object properties: nylas_id: type: string description: The Mail Message ID assigned by the sync provider s3_bucket: type: string description: The name of the S3 bucket s3_bucket_path: type: string description: The path of the S3 bucket external_deleted_flag: type: boolean description: If the Mail Message has been deleted on the provider side or not mua_message_id: type: string description: The Mail Message ID assigned by the mail user agent template_id: type: integer description: The ID of the mail template timestamp: type: string description: The add date and time of the Mail Message item_type: type: string description: The type of the data item company_id: type: integer description: The ID of the company additional_data: description: The additional data of the list type: object properties: start: type: integer description: Pagination start limit: type: integer description: Items shown per page more_items_in_collection: type: boolean description: If there are more list items in the collection than displayed or not example: success: true data: - object: mailMessage timestamp: '2020-09-16 13:38:17' data: id: 1 from: - id: 1 email_address: mail@example.org name: Test linked_person_id: 1 linked_person_name: '' mail_message_party_id: 1 to: - id: 1 email_address: mail@example.org name: Test linked_person_id: 1 linked_person_name: '' mail_message_party_id: 1 cc: - id: 1 email_address: mail@example.org name: Test linked_person_id: 1 linked_person_name: '' mail_message_party_id: 1 bcc: - id: 1 email_address: mail@example.org name: Test linked_person_id: 1 linked_person_name: '' mail_message_party_id: 1 body_url: https://example.org nylas_id: 8cfw8n7l4iy24xxxxxxxxx account_id: ao5gpry0zykr1xxxxxxxxx user_id: 1 mail_thread_id: 1 subject: test subject snippet: test subject mail_tracking_status: opened mail_link_tracking_enabled_flag: 0 read_flag: 1 draft: '' s3_bucket: pipedrive-mail-live-fr s3_bucket_path: e9cf-6081745/77777/nylas/111/1111/body draft_flag: 0 synced_flag: 1 deleted_flag: 0 external_deleted_flag: false has_body_flag: 1 sent_flag: 0 sent_from_pipedrive_flag: 0 smart_bcc_flag: 0 message_time: '2019-11-14T06:02:06.000Z' add_time: '2019-11-14T06:02:06.000Z' update_time: '2019-11-14T07:15:49.000Z' has_attachments_flag: 1 has_inline_attachments_flag: 0 has_real_attachments_flag: 1 mua_message_id: 8cfw8n7l4iy24lfhnexxxxxx-0@mailer.nylas.com template_id: 1 item_type: mailMessage timestamp: '2020-09-16T13:37:50.000Z' company_id: 6081745 additional_data: pagination: start: 0 limit: 100 more_items_in_collection: true /organizations/{id}/merge: put: summary: Merge two organizations description: Merges an organization with another organization. For more information, see the tutorial for merging two organizations. x-token-cost: 40 operationId: mergeOrganizations tags: - Organizations security: - api_key: [] - oauth2: - contacts:full parameters: - in: path name: id description: The ID of the organization required: true schema: type: integer requestBody: content: application/json: schema: title: mergeOrganizationsRequest type: object required: - merge_with_id properties: merge_with_id: type: integer description: The ID of the organization that the organization will be merged with responses: '200': description: Success content: application/json: schema: title: MergeOrganizationsResponse type: object properties: success: type: boolean description: If the request was successful or not data: type: object properties: id: type: integer description: The ID of the merged organization example: success: true data: id: 123 /organizations/{id}/permittedUsers: get: summary: List permitted users description: List users permitted to access an organization. x-token-cost: 10 operationId: getOrganizationUsers tags: - Organizations security: - api_key: [] - oauth2: - contacts:read - contacts:full parameters: - in: path name: id description: The ID of the organization required: true schema: type: integer responses: '200': description: Success content: application/json: schema: title: GetPermittedUsersResponse allOf: - title: baseResponse type: object properties: success: type: boolean description: If the response is successful or not - type: object properties: data: type: array description: The list of permitted user IDs items: type: number example: success: true data: - 123 - 777 /organizations: get: summary: Get all organizations description: Returns data about all organizations. x-token-cost: 10 operationId: getOrganizations tags: - Organizations security: - api_key: [] - oauth2: - contacts:read - contacts:full parameters: - in: query name: filter_id schema: type: integer description: If supplied, only organizations matching the specified filter are returned - in: query name: ids description: 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. schema: type: string - in: query name: owner_id schema: type: integer description: If supplied, only organizations owned by the specified user are returned. If filter_id is provided, this is ignored. - in: query name: updated_since schema: type: string description: 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. - in: query name: updated_until schema: type: string description: If set, only organizations with an `update_time` earlier than this time are returned. In RFC3339 format, e.g. 2025-01-01T10:20:00Z. - in: query name: sort_by description: 'The field to sort by. Supported fields: `id`, `update_time`, `add_time`.' schema: type: string default: id enum: - id - update_time - add_time - in: query name: sort_direction description: 'The sorting direction. Supported values: `asc`, `desc`.' schema: type: string default: asc enum: - asc - desc - in: query name: include_fields description: Optional comma separated string array of additional fields to include schema: type: string enum: - next_activity_id - last_activity_id - open_deals_count - related_open_deals_count - closed_deals_count - related_closed_deals_count - email_messages_count - people_count - activities_count - done_activities_count - undone_activities_count - files_count - notes_count - followers_count - won_deals_count - related_won_deals_count - lost_deals_count - related_lost_deals_count - smart_bcc_email - in: query name: custom_fields description: 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. schema: type: string - in: query name: include_option_labels description: 'When provided with a ''true'' value, single option and multiple option custom fields values contain objects in the form of ''{ id: number, label: string }'' instead of plain id' schema: type: boolean - in: query name: include_labels description: 'When provided with ''true'' value, response will include an array of label objects in the form of ''{ id: number, label: string }''' schema: type: boolean - in: query name: limit description: For pagination, the limit of entries to be returned. If not provided, 100 items will be returned. Please note that a maximum value of 500 is allowed. schema: type: integer example: 100 - in: query name: cursor required: false schema: type: string description: For pagination, the marker (an opaque string value) representing the first item on the next page responses: '200': description: Get all organizations content: application/json: schema: type: object title: GetOrganizationsResponse allOf: - title: baseResponse type: object properties: success: type: boolean description: If the response is successful or not - type: object properties: data: type: array description: Organizations array items: type: object properties: id: type: integer description: The ID of the organization name: type: string description: The name of the organization owner_id: type: integer description: The ID of the user who owns the organization add_time: type: string description: The creation date and time of the organization update_time: type: string description: The last updated date and time of the organization is_deleted: type: boolean description: Whether the organization is deleted or not visible_to: type: integer description: The visibility of the organization address: description: The address of the organization type: object title: OrganizationItemAddress properties: value: type: string description: The full address of the organization country: type: string description: Country of the organization admin_area_level_1: type: string description: Admin area level 1 (e.g. state) of the organization admin_area_level_2: type: string description: Admin area level 2 (e.g. county) of the organization locality: type: string description: Locality (e.g. city) of the organization sublocality: type: string description: Sublocality (e.g. neighborhood) of the organization route: type: string description: Route (e.g. street) of the organization street_number: type: string description: Street number of the organization subpremise: type: string description: Subpremise (e.g. apartment/suite number) of the organization postal_code: type: string description: Postal code of the organization label_ids: type: array description: The IDs of labels assigned to the organization items: type: integer custom_fields: type: object additionalProperties: true description: An object where each key represents a custom field. All custom fields are referenced as randomly generated 40-character hashes. To clear a custom field value, set it to `null`. For multi-option fields (field type `set`), use `null` to clear the selection — sending an empty array `[]` is not supported and will result in a validation error. additional_data: type: object description: The additional data of the list properties: next_cursor: type: string description: The first item on the next page. The value of the `next_cursor` field will be `null` if you have reached the end of the dataset and there’s no more pages to be returned. example: success: true data: - id: 1 name: Organization Name owner_id: 1 org_id: 1 add_time: '2021-01-01T00:00:00Z' update_time: '2021-01-01T00:00:00Z' address: value: 123 Main St country: USA admin_area_level_1: CA admin_area_level_2: Santa Clara locality: Sunnyvale sublocality: Downtown route: Main St street_number: '123' subpremise: 123A postal_code: '94085' is_deleted: false visible_to: 7 label_ids: - 1 - 2 - 3 custom_fields: {} additional_data: next_cursor: eyJmaWVsZCI6ImlkIiwiZmllbGRWYWx1ZSI6Nywic29ydERpcmVjdGlvbiI6ImFzYyIsImlkIjo3fQ post: summary: Add a new organization description: Adds a new organization. x-token-cost: 5 operationId: addOrganization tags: - Organizations security: - api_key: [] - oauth2: - contacts:full requestBody: content: application/json: schema: required: - title type: object properties: name: type: string description: The name of the organization owner_id: type: integer description: The ID of the user who owns the organization add_time: type: string description: The creation date and time of the organization update_time: type: string description: The last updated date and time of the organization visible_to: type: integer description: The visibility of the organization label_ids: type: array description: The IDs of labels assigned to the organization items: type: integer address: description: The address of the organization type: object title: OrganizationItemAddress properties: value: type: string description: The full address of the organization country: type: string description: Country of the organization admin_area_level_1: type: string description: Admin area level 1 (e.g. state) of the organization admin_area_level_2: type: string description: Admin area level 2 (e.g. county) of the organization locality: type: string description: Locality (e.g. city) of the organization sublocality: type: string description: Sublocality (e.g. neighborhood) of the organization route: type: string description: Route (e.g. street) of the organization street_number: type: string description: Street number of the organization subpremise: type: string description: Subpremise (e.g. apartment/suite number) of the organization postal_code: type: string description: Postal code of the organization custom_fields: type: object additionalProperties: true description: An object where each key represents a custom field. All custom fields are referenced as randomly generated 40-character hashes. To clear a custom field value, set it to `null`. For multi-option fields (field type `set`), use `null` to clear the selection — sending an empty array `[]` is not supported and will result in a validation error. responses: '200': description: Add organization content: application/json: schema: type: object title: UpsertOrganizationResponse allOf: - title: baseResponse type: object properties: success: type: boolean description: If the response is successful or not - type: object title: UpsertOrganizationResponseData properties: data: type: object properties: id: type: integer description: The ID of the organization name: type: string description: The name of the organization owner_id: type: integer description: The ID of the user who owns the organization add_time: type: string description: The creation date and time of the organization update_time: type: string description: The last updated date and time of the organization is_deleted: type: boolean description: Whether the organization is deleted or not visible_to: type: integer description: The visibility of the organization address: description: The address of the organization type: object title: OrganizationItemAddress properties: value: type: string description: The full address of the organization country: type: string description: Country of the organization admin_area_level_1: type: string description: Admin area level 1 (e.g. state) of the organization admin_area_level_2: type: string description: Admin area level 2 (e.g. county) of the organization locality: type: string description: Locality (e.g. city) of the organization sublocality: type: string description: Sublocality (e.g. neighborhood) of the organization route: type: string description: Route (e.g. street) of the organization street_number: type: string description: Street number of the organization subpremise: type: string description: Subpremise (e.g. apartment/suite number) of the organization postal_code: type: string description: Postal code of the organization label_ids: type: array description: The IDs of labels assigned to the organization items: type: integer custom_fields: type: object additionalProperties: true description: An object where each key represents a custom field. All custom fields are referenced as randomly generated 40-character hashes. To clear a custom field value, set it to `null`. For multi-option fields (field type `set`), use `null` to clear the selection — sending an empty array `[]` is not supported and will result in a validation error. example: success: true data: id: 1 name: Organization Name owner_id: 1 org_id: 1 add_time: '2021-01-01T00:00:00Z' update_time: '2021-01-01T00:00:00Z' address: value: 123 Main St country: USA admin_area_level_1: CA admin_area_level_2: Santa Clara locality: Sunnyvale sublocality: Downtown route: Main St street_number: '123' subpremise: 123A postal_code: '94085' is_deleted: false visible_to: 7 label_ids: - 1 - 2 - 3 custom_fields: {} /organizations/{id}: delete: summary: Delete a organization description: Marks a organization as deleted. After 30 days, the organization will be permanently deleted. x-token-cost: 3 operationId: deleteOrganization tags: - Organizations security: - api_key: [] - oauth2: - contacts:full parameters: - in: path name: id description: The ID of the organization required: true schema: type: integer responses: '200': description: Delete organization content: application/json: schema: title: DeleteOrganizationResponse type: object properties: success: type: boolean description: If the response is successful or not data: type: object properties: id: type: integer description: Deleted organization ID example: success: true data: id: 1 get: summary: Get details of a organization description: Returns the details of a specific organization. x-token-cost: 1 operationId: getOrganization tags: - Organizations security: - api_key: [] - oauth2: - contacts:read - contacts:full parameters: - in: path name: id description: The ID of the organization required: true schema: type: integer - in: query name: include_fields description: Optional comma separated string array of additional fields to include schema: type: string enum: - next_activity_id - last_activity_id - open_deals_count - related_open_deals_count - closed_deals_count - related_closed_deals_count - email_messages_count - people_count - activities_count - done_activities_count - undone_activities_count - files_count - notes_count - followers_count - won_deals_count - related_won_deals_count - lost_deals_count - related_lost_deals_count - smart_bcc_email - in: query name: custom_fields description: 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. schema: type: string - in: query name: include_option_labels description: 'When provided with a ''true'' value, single option and multiple option custom fields values contain objects in the form of ''{ id: number, label: string }'' instead of plain id' schema: type: boolean - in: query name: include_labels description: 'When provided with ''true'' value, response will include an array of label objects in the form of ''{ id: number, label: string }''' schema: type: boolean responses: '200': description: Get organization content: application/json: schema: type: object title: UpsertOrganizationResponse allOf: - title: baseResponse type: object properties: success: type: boolean description: If the response is successful or not - type: object title: UpsertOrganizationResponseData properties: data: type: object properties: id: type: integer description: The ID of the organization name: type: string description: The name of the organization owner_id: type: integer description: The ID of the user who owns the organization add_time: type: string description: The creation date and time of the organization update_time: type: string description: The last updated date and time of the organization is_deleted: type: boolean description: Whether the organization is deleted or not visible_to: type: integer description: The visibility of the organization address: description: The address of the organization type: object title: OrganizationItemAddress properties: value: type: string description: The full address of the organization country: type: string description: Country of the organization admin_area_level_1: type: string description: Admin area level 1 (e.g. state) of the organization admin_area_level_2: type: string description: Admin area level 2 (e.g. county) of the organization locality: type: string description: Locality (e.g. city) of the organization sublocality: type: string description: Sublocality (e.g. neighborhood) of the organization route: type: string description: Route (e.g. street) of the organization street_number: type: string description: Street number of the organization subpremise: type: string description: Subpremise (e.g. apartment/suite number) of the organization postal_code: type: string description: Postal code of the organization label_ids: type: array description: The IDs of labels assigned to the organization items: type: integer custom_fields: type: object additionalProperties: true description: An object where each key represents a custom field. All custom fields are referenced as randomly generated 40-character hashes. To clear a custom field value, set it to `null`. For multi-option fields (field type `set`), use `null` to clear the selection — sending an empty array `[]` is not supported and will result in a validation error. example: success: true data: id: 1 name: Organization Name owner_id: 1 org_id: 1 add_time: '2021-01-01T00:00:00Z' update_time: '2021-01-01T00:00:00Z' address: value: 123 Main St country: USA admin_area_level_1: CA admin_area_level_2: Santa Clara locality: Sunnyvale sublocality: Downtown route: Main St street_number: '123' subpremise: 123A postal_code: '94085' is_deleted: false visible_to: 7 label_ids: - 1 - 2 - 3 custom_fields: {} patch: summary: Update a organization description: Updates the properties of a organization. x-token-cost: 5 operationId: updateOrganization tags: - Organizations security: - api_key: [] - oauth2: - contacts:full parameters: - in: path name: id description: The ID of the organization required: true schema: type: integer requestBody: content: application/json: schema: type: object properties: name: type: string description: The name of the organization owner_id: type: integer description: The ID of the user who owns the organization add_time: type: string description: The creation date and time of the organization update_time: type: string description: The last updated date and time of the organization visible_to: type: integer description: The visibility of the organization label_ids: type: array description: The IDs of labels assigned to the organization items: type: integer address: description: The address of the organization type: object title: OrganizationItemAddress properties: value: type: string description: The full address of the organization country: type: string description: Country of the organization admin_area_level_1: type: string description: Admin area level 1 (e.g. state) of the organization admin_area_level_2: type: string description: Admin area level 2 (e.g. county) of the organization locality: type: string description: Locality (e.g. city) of the organization sublocality: type: string description: Sublocality (e.g. neighborhood) of the organization route: type: string description: Route (e.g. street) of the organization street_number: type: string description: Street number of the organization subpremise: type: string description: Subpremise (e.g. apartment/suite number) of the organization postal_code: type: string description: Postal code of the organization custom_fields: type: object additionalProperties: true description: An object where each key represents a custom field. All custom fields are referenced as randomly generated 40-character hashes. To clear a custom field value, set it to `null`. For multi-option fields (field type `set`), use `null` to clear the selection — sending an empty array `[]` is not supported and will result in a validation error. responses: '200': description: Edit organization content: application/json: schema: type: object title: UpsertOrganizationResponse allOf: - title: baseResponse type: object properties: success: type: boolean description: If the response is successful or not - type: object title: UpsertOrganizationResponseData properties: data: type: object properties: id: type: integer description: The ID of the organization name: type: string description: The name of the organization owner_id: type: integer description: The ID of the user who owns the organization add_time: type: string description: The creation date and time of the organization update_time: type: string description: The last updated date and time of the organization is_deleted: type: boolean description: Whether the organization is deleted or not visible_to: type: integer description: The visibility of the organization address: description: The address of the organization type: object title: OrganizationItemAddress properties: value: type: string description: The full address of the organization country: type: string description: Country of the organization admin_area_level_1: type: string description: Admin area level 1 (e.g. state) of the organization admin_area_level_2: type: string description: Admin area level 2 (e.g. county) of the organization locality: type: string description: Locality (e.g. city) of the organization sublocality: type: string description: Sublocality (e.g. neighborhood) of the organization route: type: string description: Route (e.g. street) of the organization street_number: type: string description: Street number of the organization subpremise: type: string description: Subpremise (e.g. apartment/suite number) of the organization postal_code: type: string description: Postal code of the organization label_ids: type: array description: The IDs of labels assigned to the organization items: type: integer custom_fields: type: object additionalProperties: true description: An object where each key represents a custom field. All custom fields are referenced as randomly generated 40-character hashes. To clear a custom field value, set it to `null`. For multi-option fields (field type `set`), use `null` to clear the selection — sending an empty array `[]` is not supported and will result in a validation error. example: success: true data: id: 1 name: Organization Name owner_id: 1 org_id: 1 add_time: '2021-01-01T00:00:00Z' update_time: '2021-01-01T00:00:00Z' address: value: 123 Main St country: USA admin_area_level_1: CA admin_area_level_2: Santa Clara locality: Sunnyvale sublocality: Downtown route: Main St street_number: '123' subpremise: 123A postal_code: '94085' is_deleted: false visible_to: 7 label_ids: - 1 - 2 - 3 custom_fields: {} /organizations/{id}/followers/changelog: get: summary: List followers changelog of an organization description: Lists changelogs about users have followed the organization. x-token-cost: 10 operationId: getOrganizationFollowersChangelog tags: - Organizations security: - api_key: [] - oauth2: - contacts:read - contacts:full parameters: - in: path name: id description: The ID of the organization required: true schema: type: integer - in: query name: limit description: For pagination, the limit of entries to be returned. If not provided, 100 items will be returned. Please note that a maximum value of 500 is allowed. schema: type: integer example: 100 - in: query name: cursor required: false schema: type: string description: For pagination, the marker (an opaque string value) representing the first item on the next page responses: '200': description: List entity followers content: application/json: schema: type: object title: GetFollowerChangelogsResponse allOf: - title: baseResponse type: object properties: success: type: boolean description: If the response is successful or not - type: object properties: data: type: array description: Follower changelogs array items: type: object title: FollowerChangelogItem properties: action: type: string description: The type of change actor_user_id: type: integer description: The ID of the user who did the change follower_user_id: type: integer description: The ID of the user who was following the entity time: type: string description: The time at which the change happened additional_data: type: object description: The additional data of the list properties: next_cursor: type: string description: The first item on the next page. The value of the `next_cursor` field will be `null` if you have reached the end of the dataset and there’s no more pages to be returned. example: success: true data: - action: added actor_user_id: 1 follower_user_id: 1 time: '2024-01-01T00:00:00Z' additional_data: next_cursor: eyJmaWVsZCI6ImlkIiwiZmllbGRWYWx1ZSI6Nywic29ydERpcmVjdGlvbiI6ImFzYyIsImlkIjo3fQ /organizations/search: get: summary: Search organizations description: Searches all organizations by name, address, notes and/or custom fields. This endpoint is a wrapper of /v1/itemSearch with a narrower OAuth scope. x-token-cost: 20 operationId: searchOrganization tags: - Organizations security: - api_key: [] - oauth2: - contacts:read - contacts:full - search:read parameters: - in: query name: term required: true schema: type: string description: 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. - in: query name: fields schema: type: string enum: - address - custom_fields - notes - name description: '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 here.' - in: query name: exact_match schema: type: boolean description: When enabled, only full exact matches against the given term are returned. It is not case sensitive. - in: query name: limit description: For pagination, the limit of entries to be returned. If not provided, 100 items will be returned. Please note that a maximum value of 500 is allowed. schema: type: integer example: 100 - in: query name: cursor required: false schema: type: string description: For pagination, the marker (an opaque string value) representing the first item on the next page responses: '200': description: Success content: application/json: schema: title: GetOrganizationSearchResponse allOf: - title: baseResponse type: object properties: success: type: boolean description: If the response is successful or not - type: object properties: data: type: object properties: items: type: array description: The array of found items items: type: object properties: result_score: type: number description: Search result relevancy item: type: object properties: id: type: integer description: The ID of the organization type: type: string description: The type of the item name: type: string description: The name of the organization address: type: string description: The address of the organization visible_to: type: integer description: The visibility of the organization owner: type: object properties: id: type: integer description: The ID of the owner of the deal custom_fields: type: array items: type: string description: Custom fields notes: type: array description: An array of notes items: type: string additional_data: type: object description: Pagination related data properties: next_cursor: type: string description: The first item on the next page. The value of the `next_cursor` field will be `null` if you have reached the end of the dataset and there’s no more pages to be returned. example: success: true data: items: - result_score: 0.316 item: id: 1 type: organization name: Organization name address: Mustamäe tee 3a, 10615 Tallinn visible_to: 3 owner: id: 1 custom_fields: [] notes: [] additional_data: next_cursor: eyJmaWVsZCI6ImlkIiwiZmllbGRWYWx1ZSI6Nywic29ydERpcmVjdGlvbiI6ImFzYyIsImlkIjo3fQ components: securitySchemes: basic_authentication: type: http scheme: basic description: Base 64 encoded string containing the `client_id` and `client_secret` values. The header value should be `Basic `. api_key: type: apiKey name: x-api-token in: header oauth2: type: oauth2 description: For more information, see https://pipedrive.readme.io/docs/marketplace-oauth-authorization flows: authorizationCode: authorizationUrl: https://oauth.pipedrive.com/oauth/authorize tokenUrl: https://oauth.pipedrive.com/oauth/token refreshUrl: https://oauth.pipedrive.com/oauth/token scopes: base: Read settings of the authorized user and currencies in an account deals:read: Read most of the data about deals and related entities - deal fields, products, followers, participants; all notes, files, filters, pipelines, stages, and statistics. Does not include access to activities (except the last and next activity related to a deal) deals:full: Create, read, update and delete deals, its participants and followers; all files, notes, and filters. It also includes read access to deal fields, pipelines, stages, and statistics. Does not include access to activities (except the last and next activity related to a deal) mail:read: Read mail threads and messages mail:full: Read, update and delete mail threads. Also grants read access to mail messages activities:read: Read activities, its fields and types; all files and filters activities:full: Create, read, update and delete activities and all files and filters. Also includes read access to activity fields and types contacts:read: Read the data about persons and organizations, their related fields and followers; also all notes, files, filters contacts:full: Create, read, update and delete persons and organizations and their followers; all notes, files, filters. Also grants read access to contacts-related fields products:read: Read products, its fields, files, followers and products connected to a deal products:full: Create, read, update and delete products and its fields; add products to deals deal-fields:full: Create, read, update and delete deal fields product-fields:full: Create, read, update and delete product fields contact-fields:full: Create, read, update and delete person and organization fields projects:read: Read projects and its fields, tasks and project templates projects:full: Create, read, update and delete projects and its fields; add projects templates and project related tasks users:read: Read data about users (people with access to a Pipedrive account), their permissions, roles and followers recents:read: Read all recent changes occurred in an account. Includes data about activities, activity types, deals, files, filters, notes, persons, organizations, pipelines, stages, products and users search:read: Search across the account for deals, persons, organizations, files and products, and see details about the returned results admin: Allows to do many things that an administrator can do in a Pipedrive company account - create, read, update and delete pipelines and its stages; deal, person and organization fields; activity types; users and permissions, etc. It also allows the app to create webhooks and fetch and delete webhooks that are created by the app leads:read: Read data about leads and lead labels leads:full: Create, read, update and delete leads and lead labels phone-integration: Enables advanced call integration features like logging call duration and other metadata, and play call recordings inside Pipedrive goals:read: Read data on all goals goals:full: Create, read, update and delete goals video-calls: Allows application to register as a video call integration provider and create conference links messengers-integration: Allows application to register as a messengers integration provider and allows them to deliver incoming messages and their statuses