Manual Segment Upsert

We have the option to upload specific user and account data into a pre-existing  manual segment  using the Evergage 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 Evergage 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.

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 Evergage web app or the API (below). Make sure you create the right type of segment for the entities you're upserting (user or account).

'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_TOKEN='12345678-90AB-CDEF-1234-567890ABCDEF'
export SEGMENT_NAME='My Segment'
 
curl -k -X GET -G --data-urlencode "segmentName=${SEGMENT_NAME}" "https://${ACCOUNT}.evergage.com/api/dataset/${DATASET}/manualSegment/find?_at=${API_TOKEN}"

'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_TOKEN='12345678-90AB-CDEF-1234-567890ABCDEF'
export ENTITY_TYPE='Users'
export FOLDER_ID='folderID' # This can be found in the parameter folderId when viewing the folder in the Evergage Web App
 
curl -k -X POST -G --data-urlencode "segmentName=${SEGMENT_NAME}" "https://${ACCOUNT}.evergage.com/api/dataset/${DATASET}/manualSegment/create?_at=${API_TOKEN}&entityType=${ENTITY_TYPE}&folderId=${FOLDER_ID}" 

Upserting members to a manual segment

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_TOKEN='12345678-90AB-CDEF-1234-567890ABCDEF'
export SEGMENT_ID='a1B2c3'
export UPSERT_COMMAND='addMembers'

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