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 section details how to upload specific user and account data into a pre-existing manual segment using the Interaction Studio API.
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
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.