legacy.add_segment

‹ BACK TO API PAGE


Description

WARNING: This method cannot be combined with any other method call within the same POST command.

When transferring a list of subscribers using the legacy.bulk_sync API, it is often necessary to create a static segment for the subscriber list. Adding a static segment and using the "group_id" returned allows you to post a list of subscribers that will appear separately within the system.

This method also allows you to fill a static segment with a list of contacts using email addresses, provided those email addresses match subscribers already in your subscriber list. This method is also useful to fill a static segment using a list of BlueHornet contact IDs. You may fill an existing segment by providing a single (or list of) "group_id", and/or fill a new segment by providing a "groupname". The two methods may be combined to create a static segment and fill existing segments within the same API call.

Arguments

Field Description Field Type Required Example
groupname The name of the static segment that you wish to create. The name of the new segment must not already exist for this account. Limit: 150 characters. String Conditional; this element is required only if the <groups> element is not included in the POST message. eTail East 2010 Opt-ins
hidden A boolean value that controls whether the static segment is hidden from a standard survey.
  • 0 -(the default value) make this static segment available for standard surveys.
  • 1 – hide this segment from a standard survey.
Boolean No 0
category_id The category ID number that you want to associate the static segment with. Use the method legacy.retrieve_segment to obtain a list of categories and their ID numbers that exist for your account. Number No 34985
groups A comma-delimited list of static segment IDs that you want to add your list of contacts to. If you provide this element, then you must also provide the list of contacts contained within the <contacts> element. String Conditional; this element is required only if the <groupname> element is not included in the POST message.; 2678,2679,2790
contacts A comma-delimited list of email addresses or BlueHornet Contact IDs that you want to add to the static segments specified either in the <groupname> element or the <groups> element. String Conditional; this element is required only if the <groups> element is included in the POST message. jsmith@​example.com, jane.doe@​example.com
or
12345,56789

Response

Field Description Example
message Indicates whether the action was successful or not.
  • 1 – the creation of the new static segment, or the addition of the contacts to the static segment(s) was successful.
  • 2 – the requested action was unsuccessful for the reason specified in the <reason> element
1
group_id The group_id of the newly created static segment. 39649
reason Human-readable explanation for the reason of the failure. not all variables passed through

Response Codes

Message Code Reason Description
2 segment name already exists The name of the new static segment already exists for this account.
2 not all variables passed through The POST message is missing required elements.
Response Code Response Text Description
401 group added A new static segment (a.k.a. group) was added to your account.
405 not all variables passed through Not all required elements were included in the request. Review the documentation for this method for the conditional elements.
406 group name already exists The value provided in the <groupname> element already exists for your account.
428 Missing variables A required variable is missing from the input.

Example Post

<methodCall>

<methodName>legacy.add_segment</methodName>

<groupname>Current Customers</groupname>

<hidden>1</hidden>

<category_id>44</category_id>

</methodCall>

Example Response

<methodResponse>

<item>

<methodName>legacy.add_segment</methodName>

<responseData>

<message>1</message>

<group_id>39469</group_id>

</responseData>

<responseNum>1</responseNum>

</item>

</methodResponse>

Example Error

<methodResponse>

<item>

<methodName>legacy.add_segment</methodName>

<responseData>

<message>2</message>

<reason>eTail East 2010 Opt-ins already exists</reason>

</responseData>

<responseNum>1</responseNum>

</item>

</methodResponse>


Back to API Reference Guide