(888) 310-0589 x2
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.
'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.
Upserting members to a manual segment
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.