openapi: 3.0.1 info: title: Pipedrive API v1 Activities Roles 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: Roles description: 'Roles are a part of the Visibility groups’ feature that allow the admin user to categorize other users and dictate what items they will be allowed access to see. ' paths: /roles: get: summary: Get all roles description: Returns all the roles within the company. x-token-cost: 20 operationId: getRoles tags: - Roles security: - api_key: [] - oauth2: - admin parameters: - in: query name: start description: Pagination start schema: type: integer default: 0 - in: query name: limit description: Items shown per page schema: type: integer responses: '200': description: Get all roles content: application/json: schema: title: GetRolesResponse allOf: - title: baseResponse type: object properties: success: type: boolean description: If the response is successful or not - type: object properties: data: type: array items: title: fullRole allOf: - description: The details of the sub-role title: subRole allOf: - title: baseRoleRequest description: The details of the role type: object properties: parent_role_id: type: integer nullable: true description: The ID of the parent role name: type: string description: The name of the role - type: object properties: id: type: integer description: The ID of the role active_flag: type: boolean description: Whether the role is active or not assignment_count: type: string description: The number of users assigned to this role sub_role_count: type: string description: The number of sub-roles - type: object properties: level: type: integer description: The level of role in the role hierarchy description: The array of roles additional_data: description: The additional data in the role list type: object properties: pagination: description: The pagination details in the role 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 example: success: true data: - id: 1 parent_role_id: 1 name: (Unassigned users) active_flag: true assignment_count: '0' sub_role_count: '0' level: 1 - id: 2 parent_role_id: 1 name: Admins active_flag: true assignment_count: '1' sub_role_count: '1' level: 1 - id: 3 parent_role_id: 2 name: Reviewers active_flag: true assignment_count: '1' sub_role_count: '0' level: 2 additional_data: pagination: start: 0 limit: 100 more_items_in_collection: false post: summary: Add a role description: Adds a new role. x-token-cost: 10 operationId: addRole tags: - Roles security: - api_key: [] - oauth2: - admin requestBody: content: application/json: schema: title: addRoleRequest description: The details of the role type: object required: - name properties: name: type: string description: The name of the role parent_role_id: type: integer nullable: true description: The ID of the parent role responses: '200': description: Add a role content: application/json: schema: title: AddRolesResponse allOf: - title: baseResponse type: object properties: success: type: boolean description: If the response is successful or not - type: object properties: data: type: object title: AddRolesResponseData properties: id: allOf: - type: integer description: The ID of the created role description: The response data example: success: true data: id: 2 /roles/{id}: delete: summary: Delete a role description: Marks a role as deleted. x-token-cost: 6 operationId: deleteRole tags: - Roles security: - api_key: [] - oauth2: - admin parameters: - in: path name: id description: The ID of the role required: true schema: type: integer responses: '200': description: Delete a role content: application/json: schema: title: DeleteRoleResponse allOf: - title: baseResponse type: object properties: success: type: boolean description: If the response is successful or not - type: object title: DeleteRoleResponseData properties: data: type: object properties: id: allOf: - type: integer description: The ID of the deleted role description: The response data example: success: true data: id: 2 get: summary: Get one role description: Returns the details of a specific role. x-token-cost: 2 operationId: getRole tags: - Roles security: - api_key: [] - oauth2: - admin parameters: - in: path name: id description: The ID of the role required: true schema: type: integer responses: '200': description: Get one role content: application/json: schema: title: GetRoleResponse allOf: - title: baseResponse type: object properties: success: type: boolean description: If the response is successful or not - type: object title: GetRoleResponseData properties: data: description: The details of the sub-role title: subRole allOf: - title: baseRoleRequest description: The details of the role type: object properties: parent_role_id: type: integer nullable: true description: The ID of the parent role name: type: string description: The name of the role - type: object properties: id: type: integer description: The ID of the role active_flag: type: boolean description: Whether the role is active or not assignment_count: type: string description: The number of users assigned to this role sub_role_count: type: string description: The number of sub-roles additional_data: type: object description: The additional data in the role properties: settings: description: The settings for the role type: object title: RoleSettings properties: deal_default_visibility: type: number description: The default visibility level of the deals for the role lead_default_visibility: type: number description: The default visibility level of the leads for the role org_default_visibility: type: number description: The default visibility level of the organizations for the role person_default_visibility: type: number description: The default visibility level of the people for the role product_default_visibility: type: number description: The default visibility level of the products for the role deal_access_level: type: number description: The access level of the deals for the role (only for default role) org_access_level: type: number description: The access level of the organizations for the role (only for default role) person_access_level: type: number description: The access level of the people for the role (only for default role) product_access_level: type: number description: The access level of the products for the role (only for default role) example: success: true data: id: 2 parent_role_id: 1 name: Admins active_flag: true assignment_count: '1' sub_role_count: '1' additional_data: settings: deal_default_visibility: 1 lead_default_visibility: 1 org_default_visibility: 1 person_default_visibility: 1 product_default_visibility: 1 put: summary: Update role details description: Updates the parent role and/or the name of a specific role. x-token-cost: 10 operationId: updateRole tags: - Roles security: - api_key: [] - oauth2: - admin parameters: - in: path name: id description: The ID of the role required: true schema: type: integer requestBody: content: application/json: schema: title: baseRoleRequest description: The details of the role type: object properties: parent_role_id: type: integer nullable: true description: The ID of the parent role name: type: string description: The name of the role responses: '200': description: Update role details content: application/json: schema: title: UpdateRoleResponse allOf: - title: baseResponse type: object properties: success: type: boolean description: If the response is successful or not - type: object properties: data: type: object title: UpdateRoleResponseData properties: id: allOf: - type: integer description: The ID of the updated role description: The response data example: success: true data: id: 2 /roles/{id}/assignments: delete: summary: Delete a role assignment description: Removes the assigned user from a role and adds to the default role. x-token-cost: 6 operationId: deleteRoleAssignment tags: - Roles security: - api_key: [] - oauth2: - admin parameters: - in: path name: id description: The ID of the role required: true schema: type: integer requestBody: content: application/json: schema: title: deleteRoleAssignmentRequest type: object required: - user_id properties: user_id: type: integer description: The ID of the user responses: '200': description: Delete assignment from a role content: application/json: schema: title: DeleteRoleAssignmentResponse allOf: - title: baseResponse type: object properties: success: type: boolean description: If the response is successful or not - type: object title: DeleteRoleAssignmentResponseData properties: data: type: object description: The response data properties: id: allOf: - type: integer description: The ID of the role the user was removed from example: success: true data: id: 2 get: summary: List role assignments description: Returns all users assigned to a role. x-token-cost: 10 operationId: getRoleAssignments tags: - Roles security: - api_key: [] - oauth2: - admin parameters: - in: path name: id description: The ID of the role 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: List assignments for a role content: application/json: schema: title: GetRoleAssignmentsResponse allOf: - title: baseResponse type: object properties: success: type: boolean description: If the response is successful or not - type: object title: GetRoleAssignmentsResponseData properties: data: type: array items: title: RoleAssignment allOf: - title: baseRoleRequest description: The details of the role type: object properties: parent_role_id: type: integer nullable: true description: The ID of the parent role name: type: string description: The name of the role - type: object title: RoleAssignmentData properties: user_id: type: integer description: The user ID role_id: type: integer description: The role ID active_flag: type: boolean description: Whether the role is active or not type: type: string description: The assignment type description: The assignment data of the role description: The role assignments additional_data: description: The additional data in the role list type: object properties: pagination: description: The pagination details in the role 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 example: success: true data: - user_id: 1234567 role_id: 2 parent_role_id: 1 name: Admins active_flag: true type: '1' additional_data: pagination: start: 0 limit: 100 more_items_in_collection: false post: summary: Add role assignment description: Assigns a user to a role. x-token-cost: 10 operationId: addRoleAssignment tags: - Roles security: - api_key: [] - oauth2: - admin parameters: - in: path name: id description: The ID of the role required: true schema: type: integer requestBody: content: application/json: schema: title: addRoleAssignmentRequest type: object required: - user_id properties: user_id: type: integer description: The ID of the user responses: '200': description: Add assignment for a role content: application/json: schema: title: AddRoleAssignmentResponse allOf: - title: baseResponse type: object properties: success: type: boolean description: If the response is successful or not - type: object title: AddRoleAssignmentResponseData properties: data: type: object properties: user_id: type: integer description: The ID of the user that was added to the role role_id: type: integer description: The ID of the role the user was added to description: The response data example: success: true data: user_id: 1234567 role_id: 2 /roles/{id}/settings: get: summary: List role settings description: Returns the visibility settings of a specific role. x-token-cost: 20 operationId: getRoleSettings tags: - Roles security: - api_key: [] - oauth2: - admin parameters: - in: path name: id description: The ID of the role required: true schema: type: integer responses: '200': description: List role settings content: application/json: schema: title: GetRoleSettingsResponse allOf: - title: baseResponse type: object properties: success: type: boolean description: If the response is successful or not - type: object title: GetRoleSettingsResponseData properties: data: description: The settings for the role type: object title: RoleSettings properties: deal_default_visibility: type: number description: The default visibility level of the deals for the role lead_default_visibility: type: number description: The default visibility level of the leads for the role org_default_visibility: type: number description: The default visibility level of the organizations for the role person_default_visibility: type: number description: The default visibility level of the people for the role product_default_visibility: type: number description: The default visibility level of the products for the role deal_access_level: type: number description: The access level of the deals for the role (only for default role) org_access_level: type: number description: The access level of the organizations for the role (only for default role) person_access_level: type: number description: The access level of the people for the role (only for default role) product_access_level: type: number description: The access level of the products for the role (only for default role) example: success: true data: deal_default_visibility: 1 lead_default_visibility: 1 org_default_visibility: 1 person_default_visibility: 1 product_default_visibility: 1 post: summary: Add or update role setting description: Adds or updates the visibility setting for a role. x-token-cost: 10 operationId: addOrUpdateRoleSetting tags: - Roles security: - api_key: [] - oauth2: - admin parameters: - in: path name: id description: The ID of the role required: true schema: type: integer requestBody: content: application/json: schema: title: addOrUpdateRoleSettingRequest type: object required: - setting_key - value properties: setting_key: type: string enum: - deal_default_visibility - lead_default_visibility - org_default_visibility - person_default_visibility - product_default_visibility value: type: integer enum: - 1 - 3 - 5 - 7 description: Possible values for the `default_visibility` setting depending on the subscription plan:
Light / Growth and Professional plans
ValueDescription
`1`Owner & Followers
`3`Entire company

Premium / Ultimate plan
ValueDescription
`1`Owner only
`3`Owner's visibility group
`5`Owner's visibility group and sub-groups
`7`Entire company

Read more about visibility groups here. responses: '200': description: List role settings content: application/json: schema: title: UpsertRoleSettingsResponse allOf: - title: baseResponse type: object properties: success: type: boolean description: If the response is successful or not - type: object title: UpsertRoleSettingsResponseData properties: data: type: object properties: id: type: integer description: The ID of the role deal_default_visibility: type: number enum: - 1 - 3 - 5 - 7 description: The setting description: The response data example: success: true data: id: 2 deal_default_visibility: 1 /roles/{id}/pipelines: get: summary: List pipeline visibility for a role description: Returns the list of either visible or hidden pipeline IDs for a specific role. For more information on pipeline visibility, please refer to the Visibility groups article. x-token-cost: 20 operationId: getRolePipelines tags: - Roles security: - api_key: [] - oauth2: - admin parameters: - in: path name: id description: The ID of the role required: true schema: type: integer - in: query name: visible schema: type: boolean default: true description: Whether to return the visible or hidden pipelines for the role responses: '200': description: Get either visible or hidden pipeline ids for a role content: application/json: schema: title: GetRolePipelinesResponse allOf: - title: baseResponse type: object properties: success: type: boolean description: If the response is successful or not - type: object properties: data: type: object title: GetRolePipelinesResponseData properties: pipeline_ids: type: array items: type: number description: The ID of the pipeline description: Either visible or hidden pipeline ids visible: type: boolean description: Whether visible or hidden pipeline ids were returned description: The response data example: success: true data: pipeline_ids: - 2 visible: true put: summary: Update pipeline visibility for a role description: Updates the specified pipelines to be visible and/or hidden for a specific role. For more information on pipeline visibility, please refer to the Visibility groups article. x-token-cost: 10 operationId: updateRolePipelines tags: - Roles security: - api_key: [] - oauth2: - admin parameters: - in: path name: id description: The ID of the role required: true schema: type: integer requestBody: content: application/json: schema: title: PutRolePipelinesBody type: object required: - visible_pipeline_ids properties: visible_pipeline_ids: type: object description: 'The pipeline IDs to make the pipelines visible (add) and/or hidden (remove) for the specified role. It requires the following JSON structure: `{ "add": "[1]", "remove": "[3, 4]" }`.' responses: '200': description: Update pipeline visibility for a role content: application/json: schema: title: GetRolePipelinesResponse allOf: - title: baseResponse type: object properties: success: type: boolean description: If the response is successful or not - type: object properties: data: type: object title: GetRolePipelinesResponseData properties: pipeline_ids: type: array items: type: number description: The ID of the pipeline description: Either visible or hidden pipeline ids visible: type: boolean description: Whether visible or hidden pipeline ids were returned description: The response data example: success: true data: pipeline_ids: - 1 - 2 visible: true 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