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

Returns all the roles within the company.

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}

      Returns the details of a specific role.

      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

          Returns all users assigned to 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 settings

              Copy link
              Copy to clipboard
              GET

              /v1/roles/{id}/settings

              Returns the visibility settings of a specific role.

              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

                Adds a new role.

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

                  /v1/roles/{id}/assignments

                  Assigns a user to a role.

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

                      /v1/roles/{id}

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

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

                        Delete a role

                        Copy link
                        Copy to clipboard
                        DELETE

                        /v1/roles/{id}

                        Marks a role as deleted.

                        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

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

                          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