Page tree


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).


Creating and finding a manual segment in the Evergage 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:
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}${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:
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}${DATASET}/manualSegment/create?_at=${API_TOKEN}&entityType=${ENTITY_TYPE}&folderId=${FOLDER_ID}" 

Upserting members to a manual segment

Note: This section is recommended for developers only. For non-developers, once your .CSV file and manual segment are constructed, feel free to send it to and we can upsert it for you. Please be sure to mention your desired intent (e.g. remove users or accounts from this segment, or set this segment's population to the contents of the .CSV file).

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:
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}${DATASET}/manualSegment/${UPSERT_COMMAND}?_at=${API_TOKEN}&segmentId=${SEGMENT_ID}"


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.

  • No labels

This page has no comments.