Endpoints with Nested Classes

The Endpoint Security REST API v2 includes endpoints where the Model Schema contains nested classes. Unfortunately, due to technical limitations, this cannot be documented in the current implementation of Swagger.
Below is the reference description of these API endpoints.

For API endpoints that are not listed below, please refer to Swagger for further details.

Stringified JSON

The code samples below are indicative for the data that must be provided. The actual body of the POST must be stringified JSON.
So if the provided sample is:

{

Name: "Test",
JobType: 1,
StartTime: "2022-03-03T11:30:00.000Z",
DiscoveryTargets:{

RangeIpTargets:[{StartIp: "192.168.19.100", EndIP: "192.168.19.200"}]

},

}

The actual body will be:

{

"value" : "{

Name: \"Test\",
JobType: 1,
StartTime: \"2022-03-03T11:30:00.000Z\",
DiscoveryTargets:{

RangeIpTargets:[{StartIp: \"192.168.19.100\", EndIP: \"192.168.19.200\"}]

},

}"

}

API Reference

Use this API endpoint for creating a job to discover, install and uninstall agents.
Request URL:
http://<host>:<port>/api/v2/Jobs

{

Name: "<JobName>",
JobType: 1,
StartTime: "2022-03-03T11:30:00.000Z",
OverwriteExistingAgents: false,
Credentials: {

Username: "<WindowsUserName>",
Password: "<WindowsPassword>",

},
Modules: {

AC: false,
AV: false,
DC: false,
PR: false,

},
DiscoveryOptions: {

PortScanDiscovery: true,
IcmpDiscovery: true,
ResolveDnsName: true,
ResolveMacAddress: true,
ResolveNetbiosName: true,
SnmpDiscovery: true,
VerifyWithPing: true,
WindowsDiscovery: true,

},
DiscoveryTargets: {

SingleIpTargets: [{

Ip: "192.168.0.100",
Timeout: 3000,
Retry: 3

}],
RangeIpTargets: [{

StartIp: "192.168.0.100",
EndIp: "192.168.0.200",
Timeout: 3000,
Retry: 3

}],
ComputerNameTargets: [{

ComputerName: "<ComputerName>",
Timeout: 3000,
Retry: 3

}],
ActiveDirectoryTargets: [{

CanonicalName: "<CN>",
OrganizationalUnit: "<OU>",
Domain: "<DomainName>",
Username: "<UserName>",
Password: "<Password>",
Timeout: 3000,
Retry: 3

}]

},

}

Reference

The descriptions below contain several examples with code snippets. For the full Model Schema and to see how these snippets fit in, please expand the sample JSON body above.

  • Name (required):
    Sets the name of the job
  • JobType (required):
    Sets the job type. Can have one of the following values:

    1 - Creates a discovery-only job. Equivalent to Discover -> Assets...

    2 - Creates an install job. Equivalent to Discover -> Assets and Install Agents...

    3 - Creates an uninstall job. Equivalent to Discover -> Assets and Uninstall Agents...

  • StartTime (required):
    Sets the start time of the job.
    • If the start time is set in the past, the job will run immediately. Equivalent to the option Immediate from the Scan Wizard.
    • If the start time is set in the future, the scheduling will be equivalent to the option Once from the Scan Wizard.
  • OverwriteExistingAgents (optional):
    Specifies whether to overwrite existing agent installs. This option is equivalent to the option Overwrite the existing agents, at Discover > Assets and Install Agents... on the Agent Options page. Can be true or false.

    If set to true, overwritten agents will lose their history, group membership and policy assignments.

  • Credentials (optional):
    Sets the Windows credentials. If not set, discovery-only jobs might work, but agent installs and uninstalls will fail with Access Denied message.
  • Modules (optional):
    Specifies which modules to install if the job is an install job. For other job types, this property is ignored.
    If not set, all modules will be set to false by default.
    To set which modules to install, set the equivalent inner properties to true.
    • Install only AV:

      Modules: {

      AV: true

      }

    • Install only AC and PR:

      Modules: {

      AC: true,
      PR: true

      }

    • Install all modules:

      Modules: {

      AC: true,
      AV: true,
      DC: true,
      PR: true

      }

  • DiscoveryOptions (optional)
    Sets how to discover the assets. If this property is not specified, all discovery options will be set to true.
    • Only ICMP is true, the rest of the options are false:

      DiscoveryOptions: {

      IcmpDiscovery: true

      }

    • All options true, except PortScanDiscovery:

      DiscoveryOptions: {

      IcmpDiscovery: true,
      ResolveDnsName: true,
      ResolveMacAddress: true,
      ResolveNetbiosName: true,
      SnmpDiscovery: true,
      VerifyWithPing: true,
      WindowsDiscovery: true

      }

      Because PortScanDiscovery is not listed, it is considered false by default.

    • All discovery options set to false:

      DiscoveryOptions: {}

  • DiscoveryTargets (required):
    Sets the discovery targets.
    These targets can currently be discovered using four target types:

    • SingleIpTargets (optional)
      Specified using class: Ip.

    • RangeIpTargets (optional)
      Specified using classes: StartIp and EndIp.

    • ComputerNameTargets (optional)
      Specified using class: ComputerName.

    • ActiveDirectoryTargets (optional)
      Specified using classes: CanonicalName, OrganizationalUnit, and Domain.

    At least one target type must be set.

    All of the discovery targets have two common properties:

    • Timeout (in milliseconds; default value = 3000)

    • Retry (default value = 3)

    If these two properties are missing, the default value will be considered.

    • Only one IP address, Timeout is 3000ms and Retry is 3:

      DiscoveryTargets: {

      SingleIpTargets: [{

      Ip: "192.168.0.1"

      }]

      }

      Because Timeout and Retry are not listed, their default values are used.

    • Only one computer name, Timeout is 5000ms and Retry is 3:

      DiscoveryTargets: {

      ComputerNameTargets: [{

      ComputerName: "my pc",
      Timeout: 5000

      }]

      }

    • One computer name with Timeout 5000ms and Retry 3 and one address with Timeout 3000ms and Retry 10:

      DiscoveryTargets: {

      ComputerNameTargets: [{

      ComputerName: "my pc",
      Timeout: 5000

      }],
      SingleIpTargets: [{

      Ip: "192.168.0.1",
      Retry: 10

      }]

      }

    • Multiple single IP addresses:

      DiscoveryTargets: {

      SingleIpTargets: [{

      Ip: "192.168.0.1"}, {Ip: "192.168.0.2"}, {Ip: "192.168.0.2"

      }]

      }

    • No target type specified:

      DiscoveryTargets: {}

    • Target types specified, but no actual targets specified:

      DiscoveryTargets: {

      ComputerNameTargets: [],
      SingleIpTargets: []

      }

Use this API endpoint to create a deployment of a custom patch list to a deployment group. This is equivalent to using the Deployment Wizard.
Request URL:
http://<host>:<port>/api/v2/DeploymentGroups

{

CustomPatchListId: 1,
AgentGuids: ["9e317d51-07ac-4c17-8a1f-3111d385bc7e"],
GroupIds: [1009],
StartTime: "2023-01-06T11:35:02.007Z",
Notify: {

Message: "Notification options",
AllowCancel: false,
AllowSnooze: true,
NotificationOnTop: true,
UseAgentPolicies: false,
UseAgentPolicy_AllowCancel: false,
UseAgentPolicy_AllowSnooze: true,
UseAgentPolicy_NotificationOnTop: true,
DeployWithin: 60,

}
Reboot: {

Message: "Reboot options",
AllowCancel: false,
AllowSnooze: true,
NotificationOnTop: true,
UseAgentPolicies: false,
UseAgentPolicy_AllowCancel: false,
UseAgentPolicy_AllowSnooze: true,
UseAgentPolicy_NotificationOnTop: true,
RebootWithin: 60,

}

}

Reference

The descriptions below contain several examples with code snippets. For the full Model Schema and to see how these snippets fit in, please expand the sample JSON body above.

  • CustomPatchListId (required):
    The ID of the custom patch list base on which the deployment is created. For more details, please refer to the Custom Patch List documentation.
  • AgentGuids (optional if GroupIds is specified):
    An array containing the target endpoints.
  • GroupIds (optional if AgentGuids is specified):
    An array containing the target groups.
  • StartTime (required)
    The start time of the deployment.
  • Notify (optional)
    Equivalent to the Deployment Notification Options on the Notification Options page of the Deployment Wizard.
    • Message (optional)
      The notification message. The REST API does not support localization. so the default message will always be in English. The default value is: "The download and installation of the patch: {Package Name} is ready to begin. If you require any additional information, please contact your Ivanti Endpoint Security administrator."
    • AllowCancel (optional; default is false)
      Allows the user to cancel the deployment.
    • AllowSnooze (optional; default is true)
      Allows the user to snooze the deployment.
    • NotificationOnTop (optional; default is true)
      Specifies if the notification should appear on top.
    • UseAgentPolicies (optional; default is false)
      Specifies if the deployment should use agent policies.
    • UseAgentPolicy_AllowCancel (optional; default is false)
      Specifies if the deployment should use agent policies for AllowCancel.
    • UseAgentPolicy_AllowSnooze (optional; default is true)
      Specifies if the deployment should use agent policies for AllowSnooze.
    • UseAgentPolicy_NotificationOnTop (optional; default is true)
      Specifies if the deployment should use agent policies for NotificationOnTop.
    • DeployWithin
      The time in minutes after which the deployment will begin.

    If Notify is not present in the JSON body, endpoints will not be notified of this deployment.
    If Notify is present, but no inner options are specified (for example Notify: {}), the default values for the notification options, as used in the Deployment Wizard, is applied.
    You can overwrite any individual option by setting it inside the Notify JSON structure. For options that are not overwritten, the default value is applied.

  • Reboot (optional)
    Equivalent to the Reboot Notification Options on the Notification Options page of the Deployment Wizard.
    This property uses the same options as listed for Notify (directly above), except for DeployWithin. Instead, it uses:
    • RebootWithin
      The time in minutes after which the reboot will begin.

    If Reboot options are set in the request body, but the deployment does not require a reboot, these options will be ignored. This behavior is identical to the Deployment Wizard: the user cannot set reboot options if the deployment does not require a reboot.

    • No Notify or Reboot options:

      {

      CustomPatchListId : 1,
      AgentGuids : ["9e317d51-07ac-4c17-8a1f-3111d385bc7e"],
      GroupIds: [1009],
      StartTime: "2023-01-06T11:35:02.007Z",

      }

    • Overwriting only some of the Notify options:

      {

      CustomPatchListId : 1,
      AgentGuids : ["9e317d51-07ac-4c17-8a1f-3111d385bc7e"],
      GroupIds: [1009],
      StartTime: "2023-01-06T11:35:02.007Z",
      Notify: {

      AllowCancel: true,
      DeployWithin: 222

      }

      }

    • Overwriting some Notify and some Reboot options:

      {

      CustomPatchListId : 1,
      AgentGuids : ["9e317d51-07ac-4c17-8a1f-3111d385bc7e"],
      GroupIds: [1009],
      StartTime: "2023-01-06T11:35:02.007Z",
      Notify: {

      AllowCancel: true,
      DeployWithin: 222

      },
      Reboot: {

      AllowSnooze: false,
      RebootWithin: 222

      }

      }