Get all roles Run in API Explorer

Add MCP server to your AI tool

Allow AI tools and LLMs to interact with the API documentation portal through MCP.

MCP server URL

https://apidocs.plannrcrm.com/mcp

Standard setup for AI tools providing an mcp.json file

mcp.json
{
  "PlannrCRM MCP server": {
    "url": "https://apidocs.plannrcrm.com/mcp"
  }
}

Close
GET /api/v2/roles

Returns all roles for the authenticated firm.

Headers

  • X-PLANNR-ACCOUNT-UUID string

Query parameters

  • include string

    Comma separated list of relationships to include in the response. Valid relationships are [assignees].

  • filter[uuid] string

    Filter by a comma separated list of UUIDs.

  • filter[name] string

    Filter by name (partial match).

  • filter[permission] string

    Comma-separated list (or array) of permissions. Matches roles whose permissions contain any of the values.

  • sort string

    Field to sort by. Valid fields are [name, created_at, updated_at]. Negative sign for DESC.

  • per_page integer

    Number of results per page (Default 15. Max 500).

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • data array[object]
      Hide data attributes Show data attributes object
      • uuid string
      • name string
      • scope string
      • description string
      • permissions array[string]
      • is_protected boolean
      • is_managed boolean
      • assigned_to_authed boolean
      • firm object
        Hide firm attributes Show firm attributes object
        • uuid string
        • created_at string
        • updated_at string
        • name string
        • slug string
        • address_1 string
        • address_2 string
        • town_city string
        • county string
        • postcode string
        • country string
        • regulatory_text string
        • logo_icon string
        • brand_colours object
          Hide brand_colours attributes Show brand_colours attributes object
          • sidebar_background string
          • sidebar_accent string
          • sidebar_text string
          • sidebar_hover string
          • sidebar_active string
          • sidebar_title_background string
          • sidebar_title_primary string
          • sidebar_title_secondary string
          • sidebar_title_secondary_hover string
          • email_background string
          • email_logo_background_panel string
          • email_sub_text string
          • email_button_background string
          • email_button_text string
          • portal_sidebar_button_background string
          • portal_sidebar_button_hover string
          • portal_sidebar_button_active string
          • portal_brand_title string
          • portal_brand_sub_title string
          • portal_sidebar_title string
          • portal_sidebar_text string
          • portal_sidebar_text_hover string
          • portal_sidebar_text_active string
          • portal_sidebar_icon string
          • portal_sidebar_icon_hover string
          • portal_sidebar_icon_active string
          • portal_background string
          • portal_sidebar_account_title string
          • portal_sidebar_account_email string
          • portal_sidebar_divider string
          • portal_dashboard_bg_one string
          • portal_dashboard_bg_two string
          • portal_sidebar_collapse_button string
          • portal_sidebar_collapse_button_hover string
          • portal_sidebar_user_select_background string
          • portal_sidebar_user_select_hover string
          • portal_sidebar_user_select_text string
          • portal_sidebar_user_select_text_hover string
          • portal_sidebar_user_select_border string
          • portal_sidebar_user_select_border_hover string
        • factfind_pdf_header_background string
        • factfind_pdf_header_text string
        • is_subscribed boolean
        • addon_subscriptions object
          Hide addon_subscriptions attributes Show addon_subscriptions attributes object
          • uuid

            The UUID of the resource.

          • created_at

            The timestamp of when the resource was created.

          • updated_at

            The timestamp of when the resource was updated.

          • enabled

            Determines if the addon is enabled

          • trial_ends_at

            If the addon is a paid addon, this is the date the free trial will end for the addon subscription.

          • trial_ends_in_days

            If the addon is a paid addon, this is the number of days left in the free trial for the addon subscription.

          • payment_confirmed_at

            If the addon is a paid addon, this is the date the payment was confirmed for the addon subscription.

        • keep_deleted_files_for integer
        • tax number
        • month_end integer
        • statement_frequency string
        • billing object
          Hide billing attributes Show billing attributes object
          • invoice_address_1 string
          • invoice_address_2 string
          • invoice_town_city string
          • invoice_county string
          • invoice_postcode string
          • invoice_country string
          • invoice_email string
        • task_board_template object
          Hide task_board_template attributes Show task_board_template attributes object
          • uuid

            uuid of the board

          • created_at

            timestamp of when the board was created

          • updated_at

            timestamp of when the board was updated

          • is_template

            returns true if the board is a template

          • name

            the name of the board

          • default_list_uuid

            the default list uuid

          • is_editable

            determines if the user can edit the board (e.g update the board, lists and move tasks around)

          • priorities

            returns the array of priorities that can be set within a task

        • ip_whitelist array[string]
        • welcome_paragraph_html string
        • email_welcome_paragraph_html string
        • show_fact_find_illustrations boolean
        • cc_email_addresses array[string]
        • bcc_email_addresses array[string]
        • reply_to_email_address string
        • mobile_app_support_number string
        • mobile_app_support_email string
      • created_at string
      • updated_at string
      • assignees_count integer
      • assignees array[object]
        Hide assignees attributes Show assignees attributes object
        • uuid string
        • type string
        • name string
        • email string
        • photo_url string
        • role array
        • is_limited boolean
      • legacy_role string
  • 403 application/json

    Missing roles read permission

    Hide response attribute Show response attribute object
    • message string Required

      A human-readable description of the error.

GET /api/v2/roles
curl \
 --request GET 'https://api.plannrcrm.com/api/v2/roles' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "X-PLANNR-ACCOUNT-UUID: {YOUR_PLANNR_ACCOUNT_UUID}"
Response examples (200)
{
  "data": [
    {
      "uuid": "d5c1c83b-5922-4279-b7be-e75d77fa492c",
      "name": "Admin Role",
      "scope": "plannr-crm",
      "description": "Full administrative access",
      "permissions": [
        "cases:read",
        "firms:read"
      ],
      "is_protected": false,
      "is_managed": false,
      "assigned_to_authed": false,
      "firm": {
        "uuid": "e2f8fcf6-49fb-499a-bd62-c986975604df",
        "created_at": "2026-09-07T20:57:23+01:00",
        "updated_at": "2026-09-07T20:57:23+01:00",
        "name": "Codepotato",
        "slug": "codepotato",
        "address_1": "Suite E, 5 The Briars",
        "address_2": "Waterberry Drive",
        "town_city": "Waterlooville",
        "county": "Hampshire",
        "postcode": "PO7 7YH",
        "country": "United Kingdom",
        "regulatory_text": "Regulatory text",
        "logo": "https://api.plannrcrm.com/images/plannr.jpg",
        "logo_icon": "https://api.plannrcrm.com/images/plannr-icon.jpg",
        "brand_colours": {
          "sidebar_background": "#0E0E56",
          "sidebar_accent": "#36367E",
          "sidebar_text": "#FFFFFF",
          "sidebar_hover": "#0A0A42",
          "sidebar_active": "#53DBB8",
          "sidebar_title_background": "#36367E",
          "sidebar_title_primary": "#FFC634",
          "sidebar_title_secondary": "#FFFFFF",
          "sidebar_title_secondary_hover": "#FFFFFF",
          "email_background": "#0E0E56",
          "email_logo_background_panel": "#36367E",
          "email_sub_text": "#FFFFFF",
          "email_button_background": "#36367E",
          "email_button_text": "#FFFFFF",
          "portal_sidebar_button_background": "#F6F6F6",
          "portal_sidebar_button_hover": "#FFFFFF",
          "portal_sidebar_button_active": "#FFFFFF",
          "portal_brand_title": "#323B4B",
          "portal_brand_sub_title": "#828994",
          "portal_sidebar_title": "#11151D",
          "portal_sidebar_text": "#323B4B",
          "portal_sidebar_text_hover": "#323B4B",
          "portal_sidebar_text_active": "#323B4B",
          "portal_sidebar_icon": "#828994",
          "portal_sidebar_icon_hover": "#828994",
          "portal_sidebar_icon_active": "#828994",
          "portal_background": "#F6F6F6",
          "portal_sidebar_account_title": "#11151D",
          "portal_sidebar_account_email": "#828994",
          "portal_sidebar_divider": "#E3E5E9",
          "portal_dashboard_bg_one": "#EF4583",
          "portal_dashboard_bg_two": "#FFC634",
          "portal_sidebar_collapse_button": "#828994",
          "portal_sidebar_collapse_button_hover": "#B3B9C4",
          "portal_sidebar_user_select_background": "#F6F6F6",
          "portal_sidebar_user_select_hover": "#F6F6F6",
          "portal_sidebar_user_select_text": "#323B4B",
          "portal_sidebar_user_select_text_hover": "#323B4B",
          "portal_sidebar_user_select_border": "#EEEEEE",
          "portal_sidebar_user_select_border_hover": "#828994"
        },
        "factfind_pdf_header_background": "#0E0E56",
        "factfind_pdf_header_text": "#ffffff",
        "factfind_pdf_logo": "https://api.plannrcrm.com/images/plannr.jpg",
        "is_subscribed": true,
        "addon_subscriptions": {
          "uuid": "d974e19e-1e85-4934-9baf-f707263eabe7",
          "created_at": "2026-09-07T20:57:28+01:00",
          "updated_at": "2026-09-07T20:57:28+01:00",
          "enabled": "true",
          "trial_ends_at": "2026-09-21",
          "trial_ends_in_days": 14,
          "payment_confirmed_at": "2026-09-25"
        },
        "keep_deleted_files_for": 30,
        "tax": 17.5,
        "month_end": 25,
        "statement_frequency": "monthly",
        "billing": {
          "invoice_address_1": "Suite E, 5 The Briars",
          "invoice_address_2": "Waterberry Drive",
          "invoice_town_city": "Waterlooville",
          "invoice_county": "Hampshire",
          "invoice_postcode": "PO7 7YH",
          "invoice_country": "United Kingdom",
          "invoice_email": "gareth@codepotato.co.uk"
        },
        "task_board_template": {
          "uuid": null,
          "created_at": "2026-09-07T20:57:28+01:00",
          "updated_at": "2026-09-07T20:57:28+01:00",
          "is_template": false,
          "name": "Task Board",
          "default_list_uuid": null,
          "is_editable": true,
          "priorities": [
            {
              "name": "High",
              "value": "high"
            },
            {
              "name": "Low",
              "value": "low"
            }
          ]
        },
        "ip_whitelist": [
          "192.168.0.1",
          "127.0.0.1"
        ],
        "welcome_paragraph_html": "<h1>Welcome.</h1>",
        "email_welcome_paragraph_html": "Welcome to Plannr!",
        "show_fact_find_illustrations": true,
        "cc_email_addresses": [
          "jack@example.com",
          "jill@example.com"
        ],
        "bcc_email_addresses": [
          "jack@example.com",
          "jill@example.com"
        ],
        "reply_to_email_address": "jack@example.com",
        "mobile_app_support_number": "01234 567890",
        "mobile_app_support_email": "support@example.com"
      },
      "created_at": "2026-09-07T20:57:23+01:00",
      "updated_at": "2026-09-07T20:57:23+01:00",
      "assignees_count": 3,
      "assignees": [
        {
          "uuid": "2bb90cc9-95ca-4795-9821-543b8d1e34c1",
          "type": "user",
          "name": "Ron Swanson",
          "email": "ron@example.com",
          "photo_url": "https://eu.ui-avatars.com/api/?name=Ron+Swanson",
          "role": [],
          "is_limited": false
        }
      ],
      "legacy_role": "admin"
    }
  ]
}
Response examples (403)
{
  "message": "This action is unauthorized."
}