Page tree
Skip to end of metadata
Go to start of metadata

We have the option to upload specific user and account data into a pre-existing  manual segment  using the Interaction Studio API. This is useful if you want to group a specific set of users or accounts into a manual segment for reporting or personalization purposes. This data must be constructed very precisely and submitted to Interaction Studio in the form of a .CSV (Comma Separated Value) file. These files can be created in any spreadsheet program (Excel, Google Spreadsheet, etc.). Unlike the  user or account upsert , new users or accounts will not be created in the dataset, only placed into the appropriate manual segment if they exist already. The manual segment API allows you to add, remove or set (repopulate entire segment with .CSV file contents) users or accounts. You can also create and lookup manual segments.

Interaction Studio Classic Only

Please note, the contents of this article are intended for customers using Interaction Studio (formerly Evergage Classic). Do not adjust your beacon version to downgrade or upgrade.

If you are a Campaigns & Templates customer, please refer to the CSV Feed Requirements in this knowledge base, or the Feeds article in developer.evergage.com.

This Article Explains

This section details how to upload specific user and account data into a pre-existing  manual segment  using the Interaction Studio API.

Sections in this Article

Constructing the .CSV file

The steps to create a .CSV file for manual segment upserts are much simpler than that of user or account upserts. Only one column is needed, with an appropriate header, then the list of user or account IDs in that column. See the screenshot below:

Here, "exampleUser1", "exampleUser2" and "exampleUser3" are existing users that will be placed in the manual segment. The field identifier, in this case, "name", should be in cell A1. Other valid identifiers are "id", "accountName", "ID", "accountId", or "accountID". The same format exists for both user and account upserts.


Upserting the .CSV file via REST API

Once the .CSV file is constructed, you must create the manual segment. This can be done from inside the Interaction Studio web app or the API (below). Make sure you create the right type of segment for the entities you're upserting (user or account).

Authorizing the REST API Request

Use HTTP Basic Authentication the add your API token's token ID and secret key as the username as password.


Creating and finding a manual segment in the Interaction Studio API

'find' - returns the ID of the manual segment if a segment with the specified name exists, returns a 404 "Segment not found" error otherwise. In the example below, we use the -G and --data-urlencode parameters together to URL-encode non URL-safe characters such as spaces.

Example URL:

https://myaccount.evergage.com/api/dataset/mydataset/manualSegment/find?_at=12345678-90AB-CDEF-1234-567890ABCDEF&segmentName=My%20Segment
export ACCOUNT='myaccount'
export DATASET='mydataset'
export API_BASIC_AUTH_STRING='QUFDRUE4RTAtMUE0My00MTRDLTk3RTAtRkQ4MzU3NDg1Q0Y3OndkcnNaNGFTd0oxemt4Y1Z1eUx5QnN0Z00tazZoTDdoNDk2N1BBUVc3eGc='
export SEGMENT_NAME='My Segment'
 
curl -k -X GET -G --data-urlencode "segmentName=${SEGMENT_NAME}" -H "Authorization: Basic ${API_BASIC_AUTH_STRING}" "https://${ACCOUNT}.evergage.com/api/dataset/${DATASET}/manualSegment/find"


'create' - creates a new manual segment with given name and returns the ID of the new segment.

The parameters "entityType" and "folderId" are optional. "entityType" specifies whether members in the segment are of type "Users" or "Accounts". The default is "Users". If no "folderId" is provided, the segment will be put under the "Uncategorized" folder.

Example URL:

https://myaccount.evergage.com/api/dataset/mydataset/manualSegment/create?_at=12345678-90AB-CDEF-1234-567890ABCDEF&entityType=Users&segmentName=My%20Segment
export ACCOUNT='myaccount'
export DATASET='mydataset'
export API_BASIC_AUTH_STRING='QUFDRUE4RTAtMUE0My00MTRDLTk3RTAtRkQ4MzU3NDg1Q0Y3OndkcnNaNGFTd0oxemt4Y1Z1eUx5QnN0Z00tazZoTDdoNDk2N1BBUVc3eGc='
export ENTITY_TYPE='Users'
export FOLDER_ID='folderID' # This can be found in the parameter folderId when viewing the folder in the Interaction Studio Web App
 
curl -k -X POST -G --data-urlencode "segmentName=${SEGMENT_NAME}" -H "Authorization: Basic ${API_BASIC_AUTH_STRING}" "https://${ACCOUNT}.evergage.com/api/dataset/${DATASET}/manualSegment/create?entityType=${ENTITY_TYPE}&folderId=${FOLDER_ID}" 

Upserting members to a manual segment

Note: This section is recommended for developers only. 

Below is an example of a cURL command to upsert to a manual segment.
Change the "UPSERT_COMMAND" variable to choose which action is performed:
'addMembers' - adds users/accounts to the manual segment
'removeMembers' - removes users/accounts from the manual segment
'setMembers' - sets the manual segment population to the list of users/accounts


Example URL:

https://myaccount.evergage.com/api/dataset/mydataset/manualSegment/addMembers?_at=12345678-90AB-CDEF-1234-567890ABCDEF&segmentId=a1B2c3
export ACCOUNT='myaccount'
export DATASET='mydataset'
export UPSERT_FILENAME='upsertFile.csv'
export API_BASIC_AUTH_STRING='QUFDRUE4RTAtMUE0My00MTRDLTk3RTAtRkQ4MzU3NDg1Q0Y3OndkcnNaNGFTd0oxemt4Y1Z1eUx5QnN0Z00tazZoTDdoNDk2N1BBUVc3eGc='
export SEGMENT_ID='a1B2c3'
export UPSERT_COMMAND='addMembers'

curl -k -X POST -F "file=@${UPSERT_FILENAME}" -H "Authorization: Basic ${API_BASIC_AUTH_STRING}" "https://${ACCOUNT}.evergage.com/api/dataset/${DATASET}/manualSegment/${UPSERT_COMMAND}?segmentId=${SEGMENT_ID}"

Limits

There is a limit of 5 minutes processing time when adding, removing or setting the members of a segment. To stay below that limit, only send 200k users at a time to these APIs. If you wish to add more than that many users to a segment, add them in batches. If you wish to set the segment membership with more than 200k users, set the membership with the first batch, then add the remaining batches.