(888) 310-0589 x2
You have the option to upload specific user and account data into your dataset using the Evergage API. This is useful if you want to add a custom field to many users or accounts at once, or add them to a dataset instead of waiting for them to log into your app. 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.).
This section details how to upload specific user and account data into your dataset using the Evergage API.
Construct the .CSV file
Evergage has the ability to upload just users, just accounts, or users with their associated accounts into your dataset, as well as any custom field. However there are many rules to ensure the process goes smoothly. This section details how the spreadsheet data is supposed to look for each of these three scenarios:
In all cases, each individual entity will occupy one row in the spreadsheet. Also, the first row of the spreadsheet should detail the field being upserted.
|With user-only upserts, only the name (userId) field is required|
|With account-only upserts, only the accountName (accountID) field is required|
|With upserts including both users and accounts, only the userID (name) and accountName fields are required|
Check for Completeness
Confirm exact string matches
It is very important that the userIds and company fields that you upsert are exact string matches to what we'll naturally see as events in Evergage. What this means is that if the userId being tracked by the beacon (or Visual Editor) is "testuser@email@example.com," and in the .CSV file you submit "testuser" for the name, it will not update the current user but instead create a new one. This is true for the account field as well. If you submit "evergage" in the .CSV file but you're passing us "evergage (0001)" with an ID # appended to it through the beacon, it will not upload correctly and create a new account.
Use the correct field names
For Evergage to know which value to assign and where, you have to use the field names recognized by the Evergage API. The two most important ones are for the userId and account:
userId = name
account = accountName
Evergage also has built in defaults for the display name, email and account type:
User's display name = userName
User's email = userEmail
Account Type = accountType
Account Name = displayName
Use the proper date format
A common use case for upserting is to submit a registration date as a custom field with an account or user. The intention is to be able to create a segment of (and possibly message) users that have registered before or after a certain date. If this is the case, the date field must be constructed such that Evergage can create a numerical KPI that will be used to create a segment. The format is: YYYYMMDD. This format creates a number that increases as the days progress. For example, you can create a segment that filters out users with registration dates greater than January 1st, 2017 by finding all values greater than 20170101. If you submit a date in any other format, including 01/01/2014, 2014/01/01, 01012014, Evergage won't be able to resolve it into a segment.
Remove hyperlinks from e-mails
Spreadsheet programs have a tendency to hyperlink email addresses. If you notice this happening, select the addresses, then right click to remove the hyperlink, otherwise they will be saved in your .CSV file with a "mailto: " appended before the email address.
Upsert Your CSV File
When your .CSV file has been constructed, please submit to firstname.lastname@example.org and we'll double check then upsert it for you.