Pipedrive Roles API

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:<br> <table class='role-setting'> <caption><b>Light / Growth and Professional plans</b></caption> <tr><th><b>Value</b></th><th><b>Description</b></th></tr> <tr><td>`1`</td><td>Owner & Followers</td></tr> <tr><td>`3`</td><td>Entire company</td></tr> </table> <br> <table class='role-setting'> <caption><b>Premium / Ultimate plan</b></caption> <tr><th><b>Value</b></th><th><b>Description</b></th></tr> <tr><td>`1`</td><td>Owner only</td></tr> <tr><td>`3`</td><td>Owner&#39;s visibility group</td></tr> <tr><td>`5`</td><td>Owner&#39;s visibility group and sub-groups</td></tr> <tr><td>`7`</td><td>Entire company</td></tr> </table> <br> Read more about visibility groups <a href='https://support.pipedrive.com/en/article/visibility-groups'>here</a>.
      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 <a href="https://support.pipedrive.com/en/article/visibility-groups" target="_blank" rel="noopener noreferrer">Visibility groups article</a>.
      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 <a href="https://support.pipedrive.com/en/article/visibility-groups" target="_blank" rel="noopener noreferrer">Visibility groups article</a>.
      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
      reques

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