Create a New Policy

Creates a new policy for a specified organization. For more info on filter types and scheduling, see Policy and Device Filters, and Scheduling.

SecuritybearerAuth
Request
query Parameters
o
required
integer

Organization ID for the specified policy.

Request Body schema: application/json
required
id
integer <int64>

Policy ID

organization_id
required
integer <int64>

Organization ID for the specified policy

name
required
string

The name of the policy

policy_type_name
required
string

The name of the type of policy you are creating. Optional when updating an existing policy.

required
any

The policy configuration. This varies depending on the type of policy being used.

auto_patch
required
boolean

Enable or disable Auto Patch.

auto_reboot
required
boolean

Enable or disable Auto Reboot.

notify_user
required
boolean
missed_patch_window
boolean
install_deferral_enabled
boolean
pending_reboot_deferral_enabled
boolean
patch_rule
required
string

Use only with Patch policy.

filter_type
string or null

The type of filter being used. Use only with patch_rule = filter

Enum Value Description
exclude

Patch All Except

include

Patch Only

severity

Patch by Severity

device_filters_enabled
boolean
Default: false

Enable or disable Device Targeting Filters.

Array of objects (DeviceFilters)

Device Targeting Filters. See Device Filter Parameters for more information.

Array
field
string
Enum: "tag" "hostname" "ip_addr" "os_family" "os_version_id" "organizational_unit"
op
string
Enum Value Description
in

Field value in result. Corresponds to is on the console UI.

not_in

Field value not in result. Corresponds to is not on the console UI.

like_any

Field contains value. Corresponds to contains on the console UI.

not_like_any

Field does not contain value. Corresponds to does not contain on the console UI.

Array of strings or booleans or (Array of strings or integers) or numbers
Array
One of:
string
object

This object can optionally contain multiple objects containing information about secrets associated with the policy.

pattern property
object
id
string <uuid>
organizationId
string <uuid>
name
string
description
string
numPolicies
integer
createdAt
string <date-time>
include_optional
boolean
Default: false

Enable or disable inclusion of optional Windows patches for this policy NOTE: Will default to false if not included.

notify_reboot_user
boolean

Display modified notification 15 minutes before patching. This message should inform the user that a reboot will follow patching actions.

notify_deferred_reboot_user
boolean or null

If true, this shows a post-install reboot notification message, if notify_reboot_deferred is also true. If notify_reboot_deferred is false or null, this will sync with the existing notify_reboot_user parameter.

custom_notification_patch_message
string <= 125 characters

Message to display before a non-rebooting patch policy executes on a Windows device. Maximum 125 characters

custom_notification_patch_message_mac
string <= 70 characters

Message to display before a non-rebooting patch policy executes on a macOS device. Maximum 70 characters

custom_notification_reboot_message
string <= 125 characters

Message to display before a rebooting patch policy executes on a Windows device. Reboot will follow patching actions. Maximum 125 characters

custom_notification_reboot_message_mac
string <= 70 characters

Message to display before a rebooting patch policy executes on a macOS device. Reboot will follow patching actions. Maximum 70 characters

custom_notification_max_delays
integer <int64>
Default: 0

Maximum number of times a user is allowed to defer the reboot. The default is 0.

custom_notification_deferment_periods
Array of integers <int64>
Default: [1,4,8]

Integer array: Deferral time periods (hours) that users can choose from. Include up to 3. All 3 must be distinct with a maximum of 24. Default values: 1, 4, 8

custom_pending_reboot_notification_message
string <= 125 characters

Custom reboot message.

custom_pending_reboot_notification_message_mac
string <= 70 characters

The custom reboot message for macOS, which overrides custom_pending_reboot_notification_message string, if provided.

custom_pending_reboot_notification_max_delays
integer <int64>
Default: 0

Maximum number of times a user is allowed to defer the reboot. The default is 0.

custom_pending_reboot_notification_deferment_periods
Array of integers <int64>
Default: [1,4,8]

The time period options available to defer a reboot for each deferral selection. Default values: 1, 4, 8

notify_user_message_timeout
integer [ 15 .. 480 ]
Default: 15

The amount of time a patch notification appears before timing out and closing. Min: 15 min. Max: 480 min. Default is 15 minutes.

notify_deferred_reboot_user_message_timeout
integer [ 15 .. 480 ]
Default: 15

The amount of time a deferrable reboot notification message appears before timing out and closing. Min: 15 min. Max: 480 min. Default is 15 minutes.

notify_user_auto_deferral_enabled
boolean
Default: false

If a patch notification times out, apply the highest configured patch deferral.

notify_deferred_reboot_user_auto_deferral_enabled
boolean
Default: false

If a reboot notification times out, apply the highest configured reboot deferral.

schedule_days
required
integer <int64>

Decimal value of binary day schedule. See Policy and Device Filters, and Scheduling - Example Days per Week.

schedule_weeks_of_month
integer <int64>

Decimal value of binary week schedule. See Policy and Device Filters, and Scheduling - Example Weeks per Month.

schedule_months
integer <int64>

Decimal value of binary month schedule. See Policy and Device Filters, and Scheduling - Example Months per Year.

schedule_time
required
string

Scheduled time for automatic policy execution. Format: "hh:mm"

scheduled_timezone
string

Define the UTC offset for a policy where UTC is used for the scheduled start time. This is required when use_scheduled_timezone is true. Format: "UTC+0000"

use_scheduled_timezone
required
boolean

Determines whether to use UTC or the local time of the device for policy execution. true = policy executes at the scheduled time in UTC, false = policy executes at the scheduled time using the device's local time.

server_groups
required
Array of integers

An array containing a list of the server group IDs to be affected by the policy.

notes
required
string

Any notes associated with the policy.

Responses
201

Created

400

Invalid Request

401

Access token is missing or invalid

403

You do not have permission to perform this action.

404

Entity not found

429

Too many requests

503

Service Unavailable

default

Invalid Request

post/policies
Request samples
application/json
{
  • "id": 0,
  • "organization_id": 0,
  • "name": "string",
  • "policy_type_name": "patch",
  • "configuration": {
    • "auto_patch": true,
    • "auto_reboot": true,
    • "notify_user": true,
    • "missed_patch_window": true,
    • "patch_rule": "all",
    • "device_filters_enabled": true,
    • "device_filters": [
      • {
        • "field": "tag",
        • "op": "in",
        • "value": [
          • "Windows",
          • "Win10"
          ]
        }
      ],
    • "include_optional": true,
    • "notify_reboot_user": true,
    • "notify_deferred_reboot_user": true,
    • "custom_notification_patch_message": "Necessary Windows updates are about to be installed!",
    • "custom_notification_patch_message_mac": "Necessary Mac updates are about to be installed!",
    • "custom_notification_reboot_message": "Necessary Windows updates are about to be installed! Reboot Needed!",
    • "custom_notification_reboot_message_mac": "Necessary Mac updates are about to be installed! Reboot Needed!",
    • "custom_notification_max_delays": 0,
    • "custom_notification_deferment_periods": [
      • 1,
      • 4,
      • 8
      ],
    • "custom_pending_reboot_notification_message": "Your computer needs to restart to finish installing updates!",
    • "custom_pending_reboot_notification_message_mac": "Your Mac needs to restart to finish installing updates!",
    • "custom_pending_reboot_notification_max_delays": 0,
    • "custom_pending_reboot_notification_deferment_periods": [
      • 2,
      • 4,
      • 6
      ],
    • "notify_user_message_timeout": 15,
    • "notify_deferred_reboot_user_timeout": 15,
    • "notify_user_auto_deferral_enabled": false,
    • "notify_deferred_reboot_user_auto_deferral_enabled": false
    },
  • "schedule_days": 0,
  • "schedule_weeks_of_month": 0,
  • "schedule_months": 0,
  • "schedule_time": "string",
  • "scheduled_timezone": "string",
  • "use_scheduled_timezone": true,
  • "server_groups": [
    • 0
    ],
  • "notes": "string"
}
Response samples
application/json
{
  • "errors": [
    • "string"
    ]
}