Segment Services, Version 1.0

79 Segment Services, Version 1.0

This chapter provides the information necessary to send messages contained in version 1.0 of the Segment Services API. Information can be obtained using the Web Service Description Language (WSDL) in conjunction with a Simple Object Access Protocol (SOAP), XML Schema, and various methods contained in the classes of the API to provide the web service described above.

The URL for the WSDL is:

https://<servername>:<portNumber>/ws/v1_0/SegmentServices?wsdl

where <servername> is the name or address of the server. For a cloud installation, the default port number is 443.

The information presented below describes the methods and classes.

The format of the method and any arguments is shown along with an explanation of what the method does and any other information that is necessary to use the method properly. If an argument is shown in dark blue, it is a class and the class name is a link to a description of the class and its attributes.

The class section shows the attributes of the classes along with an explanation of each attribute and when necessary, when they are used.

Note:

Authentication is required. See Introduction for information on creating and implementing an authentication key.

Methods

This section presents the methods used in Version 1.0 of the Segment Services API.

addCustomerToSegment

string[] addCustomerToSegment(                              string[] customerIds,                              long segmentId,     throws RelateProcessingException

Variable	Required?	Description
`customerIds`	[optional]	Array of customer IDs.
`segmentId`	[required]	ID of the segment.

The addCustomerToSegment method adds a customer to an existing segment.

This method returns an array of string elements.

createManualSegment

long createManualSegment(                         string segmentName,                         string description,                         boolean privateFlag,                         string userId,     throws RelateProcessingException

Variable	Required?	Description
`segmentName`	[required]	Name of the segment.
`description`	[required]	Description of the segment.
`privateFlag`	[required]	Indicates whether the segment is private (`true`) or public (`false`).
`userId`	[required]	ID of the user creating the segment.

The createManualSegment method creates a new segment that will contain individually selected customers. These customers are added using the addCustomerToSegment method and removed using the removeCustomerFromSegment method.

This method returns a long value.

getCustomersOfSegment

wsPageOfSegmentCustomers getCustomersOfSegment(                          long segmentId,                          string[] optionalAssociateIds,                          int startIndex,                          int pageSize,     throws RelateProcessingException

Variable	Required?	Description
`segmentId`	[required]	ID of the segment.
`optionalAssociateIds`	[optional]	Array of IDs for associates to whom the customers are assigned.
`startIndex`	[required]	Start index of the customer list.
`pageSize`	[required]	Maximum number of records per page.

The getCustomersOfSegment method retrieves a set of customers belonging to a segment, beginning with customer number startIndex and containing pageSize customers.

This method returns a wsPageOfSegmentCustomers element.

getMyManualSegments

wsSegmentSummary[] getMyManualSegments(                          string relateUserId,     throws RelateProcessingException

Variable	Required?	Description
`relateUserId`	[optional]	ID of user making request.

The getMyManualSegments retrieves the manual segments for a user.

This method returns an array of wsSegmentSummary elements.

getSegments

wsSegmentSummary[] getSegments(              string relateUserId,              boolean ignoreNonListSegments,              dateTime optionalNewerThanLastRunDate,              segmentViewType optionalSegmentViewType,              long optionalSegmentId,     throws RelateProcessingException

Variable	Required?	Description
`relateUserId`	[optional]	ID of user making request.
`ignoreNonListSegments`	[required]	Indicates whether to only return segments containing a list of customers (`true`), or to also include segments that only produce customer counts (`false`).
`optionalNewerThanLastRunDate`	[optional]	Indicates whether to only return segments newer than the entered date.
`optionalSegmentViewType`	[optional]	Type of segment (`PRIVATE`, `PUBLIC`, or `OPEN_ACCESS`).
`optionalSegmentId`	[optional]	ID of segment.

The getSegments method returns an array of segments matching the entered search criteria.

This method returns an array of wsSegmentSummary elements.

removeCustomerFromSegment

void removeCustomerFromSegment(                               string[] customerIds,                               string segmentId,     throws RelateProcessingException

Variable	Required?	Description
`customerIds`	[optional]	ID of the customer.
`segmentId`	[optional]	ID of the segment.

The removeCustomerFromSegment method removes a customer from a manual segment.

This method has no return value.

Classes

This section presents the classes used in Version 1.0 of the Segment Services API.

RelateProcessingException

For a description of this class, see Introduction.

wsCustTiny

The wsCustTiny class contains the following elements:

Type	Element	Description
string	associateId	ID of associate (if any) assigned to the customer.
string	custId	ID of the customer.
string	firstName	Customer first name.
string	lastName	Customer last name.

wsPageOfSegmentCustomers

The wsPageOfSegmentCustomers class contains the following elements:

Type	Element	Description
wsCustTiny[]	customers	The customers in the page.
boolean	morePages	Indicates whether there are more pages in the results.
long	pageSize	Number of customers on the page.
long	startIndex	Sequence number indicating the order of the first customer in the page results.

wsSegmentSummary

The wsSegmentSummaryWithAttribute class contains the following elements:

Type	Element	Description
string	createdByUserId	ID of the user who created the segment.
long	custCount	Number of customers in the segment.
string	description	Description of the segment.
boolean	isListSegment	Indicates whether the segment is a list segment.
boolean	isManualSegment	Indicates whether the segment is a manual segment.
dateTime	lastRunDate	The last time the segment was run.
string	name	Name of the segment.
long	segmentId	ID of the segment.
segmentQueryType	segmentQueryType	Type of query used to create the segment.
segmentViewType	segmentViewType	Type of view used for the segment.