Roles

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.

Get all roles

Copy link

Returns all the roles within the company.

API v1
Cost

20

Request
GET

/v1/roles

Query parameters

start

integer

Pagination start

Default

0

limit

integer

Items shown per page

Response
200

OK

Expand all
Copy code
    • true
    • [ ... ]
      • { ... }

      Get one role

      Copy link

      Returns the details of a specific role.

      API v1
      Cost

      2

      Request
      GET

      /v1/roles/{id}

      Path parameters

      id

      integer

      required

      The ID of the role

      Response
      200

      OK

      Expand all
      Copy code
        • true
        • { ... }
          • { ... }

          List role assignments

          Copy link

          Returns all users assigned to a role.

          API v1
          Cost

          10

          Request
          GET

          /v1/roles/{id}/assignments

          Path parameters

          id

          integer

          required

          The ID of the role

          Query parameters

          start

          integer

          Pagination start

          Default

          0

          limit

          integer

          Items shown per page

          Response
          200

          OK

          Expand all
          Copy code
            • true
            • [ ... ]
              • { ... }

              List role settings

              Copy link

              Returns the visibility settings of a specific role.

              API v1
              Cost

              20

              Request
              GET

              /v1/roles/{id}/settings

              Path parameters

              id

              integer

              required

              The ID of the role

              Response
              200

              OK

              Expand all
              Copy code
                • true
                • { ... }

                List pipeline visibility for a role

                Copy link

                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.

                API v1
                Cost

                20

                Request
                GET

                /v1/roles/{id}/pipelines

                Path parameters

                id

                integer

                required

                The ID of the role

                Query parameters

                visible

                boolean

                Whether to return the visible or hidden pipelines for the role

                Default

                true

                Response
                200

                OK

                Expand all
                Copy code
                  • true
                  • { ... }

                  Add a role

                  Copy link

                  Adds a new role.

                  API v1
                  Cost

                  10

                  Request
                  POST

                  /v1/roles

                  Body parameters

                  application/json

                  name

                  string

                  required

                  The name of the role

                  parent_role_id

                  integer

                  The ID of the parent role

                  Response
                  200

                  OK

                  Expand all
                  Copy code
                    • true
                    • { ... }

                    Add role assignment

                    Copy link

                    Assigns a user to a role.

                    API v1
                    Cost

                    10

                    Request
                    POST

                    /v1/roles/{id}/assignments

                    Path parameters

                    id

                    integer

                    required

                    The ID of the role

                    Body parameters

                    application/json

                    user_id

                    integer

                    required

                    The ID of the user

                    Response
                    200

                    OK

                    Expand all
                    Copy code
                      • true
                      • { ... }

                      Add or update role setting

                      Copy link

                      Adds or updates the visibility setting for a role.

                      API v1
                      Cost

                      10

                      Request
                      POST

                      /v1/roles/{id}/settings

                      Path parameters

                      id

                      integer

                      required

                      The ID of the role

                      Body parameters

                      application/json

                      setting_key

                      string

                      required

                      Values

                      deal_default_visibility

                      lead_default_visibility

                      org_default_visibility

                      person_default_visibility

                      product_default_visibility

                      value

                      integer

                      required

                      Possible values for the default_visibility setting depending on the subscription plan:

                      Essential / Advanced plan
                      ValueDescription
                      1Owner & Followers
                      3Entire company

                      Professional / Enterprise plan
                      ValueDescription
                      1Owner only
                      3Owner's visibility group
                      5Owner's visibility group and sub-groups
                      7Entire company

                      Read more about visibility groups here.

                      Values

                      1

                      3

                      5

                      7

                      Response
                      200

                      OK

                      Expand all
                      Copy code
                        • true
                        • { ... }

                        Update role details

                        Copy link

                        Updates the parent role and/or the name of a specific role.

                        API v1
                        Cost

                        10

                        Request
                        PUT

                        /v1/roles/{id}

                        Path parameters

                        id

                        integer

                        required

                        The ID of the role

                        Body parameters

                        application/json

                        parent_role_id

                        integer

                        The ID of the parent role

                        name

                        string

                        The name of the role

                        Response
                        200

                        OK

                        Expand all
                        Copy code
                          • true
                          • { ... }

                          Update pipeline visibility for a role

                          Copy link

                          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.

                          API v1
                          Cost

                          10

                          Request
                          PUT

                          /v1/roles/{id}/pipelines

                          Path parameters

                          id

                          integer

                          required

                          The ID of the role

                          Body parameters

                          application/json

                          visible_pipeline_ids

                          object

                          required

                          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]" }.

                          Response
                          200

                          OK

                          Expand all
                          Copy code
                            • true
                            • { ... }

                            Delete a role

                            Copy link

                            Marks a role as deleted.

                            API v1
                            Cost

                            6

                            Request
                            DELETE

                            /v1/roles/{id}

                            Path parameters

                            id

                            integer

                            required

                            The ID of the role

                            Response
                            200

                            OK

                            Expand all
                            Copy code
                              • true
                              • { ... }

                              Delete a role assignment

                              Copy link

                              Removes the assigned user from a role and adds to the default role.

                              API v1
                              Cost

                              6

                              Request
                              DELETE

                              /v1/roles/{id}/assignments

                              Path parameters

                              id

                              integer

                              required

                              The ID of the role

                              Body parameters

                              application/json

                              user_id

                              integer

                              required

                              The ID of the user

                              Response
                              200

                              OK

                              Expand all
                              Copy code
                                • true
                                • { ... }

                                Subscribe to Pipedrive’s Developer Newsletter