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
Copy to clipboard
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
      Copy to clipboard
      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
          Copy to clipboard
          GET

          /v1/roles/{id}/assignments

          Lists assignments for a role.

          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 sub-roles

              Copy link
              Copy to clipboard
              GET

              /v1/roles/{id}/roles

              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
                  Copy to clipboard
                  GET

                  /v1/roles/{id}/settings

                  Path parameters

                  id

                  integer

                  required

                  The ID of the role

                  Response
                  200

                  OK

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

                    Add a role

                    Copy link
                    Copy to clipboard
                    POST

                    /v1/roles

                    Body parameters

                    application/x-www-form-urlencoded

                    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
                      • { ... }

                      Add role assignment

                      Copy link
                      Copy to clipboard
                      POST

                      /v1/roles/{id}/assignments

                      Adds assignment for a role.

                      Path parameters

                      id

                      integer

                      required

                      The ID of the role

                      Body parameters

                      application/x-www-form-urlencoded

                      user_id

                      integer

                      required

                      The ID of the user

                      Response
                      200

                      OK

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

                        Add or update role setting

                        Copy link
                        Copy to clipboard
                        POST

                        /v1/roles/{id}/settings

                        Adds or updates the visibility setting for a role.

                        Path parameters

                        id

                        integer

                        required

                        The ID of the role

                        Body parameters

                        application/x-www-form-urlencoded

                        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
                          Copy to clipboard
                          PUT

                          /v1/roles/{id}

                          Path parameters

                          id

                          integer

                          required

                          The ID of the role

                          Body parameters

                          application/x-www-form-urlencoded

                          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
                            • { ... }

                            Delete a role

                            Copy link
                            Copy to clipboard
                            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
                              Copy to clipboard
                              DELETE

                              /v1/roles/{id}/assignments

                              Deletes assignment from a role.

                              Path parameters

                              id

                              integer

                              required

                              The ID of the role

                              Body parameters

                              application/x-www-form-urlencoded

                              user_id

                              integer

                              required

                              The ID of the user

                              Response
                              200

                              OK

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

                                Subscribe to Pipedrive’s Developer Newsletter