Views:
Initiate a profile distribution to a segment group, or to one or more virtual segments on a device.
This API provides two separate interfaces on the same URL path. The parameter names are different in each interface, so use the parameters that match the method you call.
  • GET: Specify the profile and the target as query parameters. Use this method to distribute to a single target.
  • POST: Specify the profile and the targets in an XML request body. Use this method to distribute to multiple targets, or to targets of different types, in a single request.

Definition

ipsProfileMgmt/distributeProfile
Method: GET or POST

GET query parameters

Parameter Type Description
profileName string Required. Name of the profile to distribute.
profileVersion string Optional. Profile version to distribute. The latest version of the profile is used if this parameter is not specified.
segmentGroupName string Name of the segment group to distribute to. Specify either this parameter or both deviceIpAddr and segmentName.
deviceIpAddr string IP address of the target device. Must be specified with segmentName.
segmentName string Name of the virtual segment on the device. Must be specified with deviceIpAddr.
distribPriority string Optional. Distribution priority.
  • high (default)
  • low
Important
Important
You must identify a distribution target. If you specify neither segmentGroupName nor the deviceIpAddr and segmentName pair, the request fails with an HTTP 404 error and the message Unable to determine target segment.

GET examples

Distribute the latest version of a profile to a segment group: 
curl -k --header "X-SMS-API-KEY: <string>"
"https://<sms_server>/ipsProfileMgmt/distributeProfile?profileName=MyProfile&
segmentGroupName=MySegmentGroup&distribPriority=high"
Distribute a specific version of a profile to a virtual segment on a device: 
curl -k --header "X-SMS-API-KEY: <string>"
"https://<sms_server>/ipsProfileMgmt/distributeProfile?profileName=MyProfile&
profileVersion=1.2.3&deviceIpAddr=10.0.0.1&segmentName=Segment-A"

POST request body elements

Submit the request body as an XML file attachment using the multipart/form-data content type.
Element Type Description
profile/name string Name of the profile to distribute. Specify either name or id.
profile/id string Internal ID assigned to the profile. Specify either name or id.
profile/version string Profile version to distribute.
priority string Optional. Distribution priority.
  • high (default)
  • low
segmentGroup/name string Name of the segment group to distribute to.
segmentGroup/id string Internal ID assigned to the segment group.
device/id string Internal ID assigned to the device.
device/shortID integer Internal number assigned to the device.
device/name string Device name.
device/ipAddress string Device IP address.
device/virtualSegment string Virtual segment on the device, identified by name or id. Specify one element for each virtual segment you want to distribute to.
virtualSegment/id string Internal ID assigned to a virtual segment. Use this element to distribute to a virtual segment without specifying a device. A virtual segment specified this way can be identified only by ID.
Note
Note
Identify a device by name, id, shortID, or ipAddress. If you specify more than one of these elements, the SMS uses the first one it finds.

POST example

Save the request body to a file, and then reference the file in the request: 
<distribution>
	<profile name="MyProfile" version="1.2.3"/>
	<priority>high</priority>
	<segmentGroup>
		<name>MySegmentGroup</name>
	</segmentGroup>
	<device>
		<ipAddress><IP address></ipAddress>
		<virtualSegment>
			<name>Segment-A</name>
		</virtualSegment>
	</device>
</distribution>
curl -k --header "X-SMS-API-KEY: <string>" -F "file=@</path/to/request.xml>"
"https://<sms_server>/ipsProfileMgmt/distributeProfile"

POST request body schema

<?xml version="1.0" encoding="utf-8"?>
	 <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
	  <xs:simpleType name="uuid">
	  	<xs:restriction base="xs:string">
	  	<xs:pattern value="<value>"/>
	 			</xs:restriction>
	 </xs:simpleType>

	<xs:complexType name="idname">
	  	<xs:choice>
	  		<xs:element name="id" type="uuid"/>
	  		<xs:element name="name" type="xs:string"/>
	  	</xs:choice>
 </xs:complexType>

	<xs:element name="distribution">
	 		<xs:complexType>
	 			<xs:sequence>
	 				<xs:element name="profile" minOccurs="1"maxOccurs="1">
	 		<xs:complexType>
	  			<xs:attribute name="id" type="uuid"/>
	  			<xs:attribute name="name" type="xs:string"/>
	  			<xs:attribute name="version" type="xs:string" use="required"/>
	  	</xs:complexType>
 </xs:element>

	<xs:element name="priority" minOccurs="0">
	 	<xs:simpleType>
	 		<xs:restriction base="xs:string">
	 				<xs:enumeration value="high"/>
	 				<xs:enumeration value="low"/>
	 		</xs:restriction>
	  </xs:simpleType>
 </xs:element>

<xs:element name="segmentGroup" type="idname" minOccurs="0"
			maxOccurs="unbounded"/>
 <xs:element name="virtualSegment" minOccurs="0"
				maxOccurs="unbounded">
			<xs:complexType>
	 			<xs:sequence>
	  			<xs:element name="id" type="uuid"/>
	  		</xs:sequence>
	  	</xs:complexType>
 </xs:element>

	<xs:element name="device" minOccurs="0" maxOccurs="unbounded">
 	<xs:complexType>
	 	<xs:sequence>
	 		<xs:choice>
	  		<xs:element name="id" type="uuid"/>
	  		<xs:element name="shortID" type="xs:positiveInteger"/>
	  		<xs:element name="name" type="xs:string"/>
	  		<xs:element name="ipAddress" type="xs:string"/>
	  	</xs:choice>
	  		<xs:element name="virtualSegment" type="idname"
							maxOccurs="unbounded"/>
	  </xs:sequence>
	  </xs:complexType>

</xs:element>
	</xs:sequence>
  </xs:complexType>
  </xs:element>
</xs:schema>

Response

The response returns the ID assigned to the distribution session, along with the initial status of the session and of each target. 
<distributions>
	<distribution id="<number>">
		<profile name="MyProfile" id="<profile_id>" version="<number>"/>
		<target>segment group</target>
		<start-time>Apr 8, 2026, 12:30:00 AM</start-time>
		<status>Distributing</status>
		<distribution>
			<target>device</target>
			<status>Waiting</status>
			<device>
				<name>IPS-Device-1</name>
				<shortID>42</shortID>
			</device>
		</distribution>
	</distribution>
</distributions>
Important
Important
Save the id attribute of the distribution element. This value identifies the distribution session, and you must specify it to check the status of the distribution. See Get distribution status.
If the SMS cannot resolve an individual target, the error is returned with that target instead of the status: 
<segmentGroup><status>Segment Group name not found: MySegmentGroup</status></segmentGroup>
<device><status>Device IP Address not found: <IP address number></status></device>