Page tree



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 article will explain how to:

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.


User-only upserts

For user-only upserts, construct your data as shown in the screenshot at the right so that the first cell, A1, has the word "name" in it. This is the API term for userID. Below this (in the first column) list userID of each user that you would like to upsert. Across the 1st row, list the names of the custom fields you want to upsert. Below each column, list the values for the custom fields for each of the users designated by name in the first column.


With user-only upserts, only the name (userId) field is required

Account-only upserts

Account upserts are very similar to user upserts, the only difference is you'll want to make sure that the designated fields you submit are custom fields that are attributes of the account. The value for A1 should be accountName. As shown in the screenshot at the right, the first column includes the account name of each account that you would like to upsert. Across the 1st row, list the names of the custom fields you want to upsert. Below each column, list the values for the custom fields for each of the accounts designated by the accountName in the first column. 


With account-only upserts, only the accountName (accountID) field is required

User and account upserts

This is a combination of the user and account upserts. The "name" value will still occupy A1, with the userIDs below it. In B1 you'll have the accountName and the accounts below it. The rest of the columns will be custom fields associated with the user or account. The screenshot at the right shows an example of how to include the data.


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 "," 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

Create and assign custom fields

If you choose to upsert custom fields with a .CSV file, you need to make sure these custom fields are assigned as an attribute of the user or account before you upsert. To do this, go into your dataset and navigate to the custom fields tab (Settings=> Fields). From here you can set the custom fields as an attribute of the user or account. Make sure the "Field" value is an exact match to the field name that will appear in the first row of your .CSV file.


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 and we'll double check then upsert it for you.

This page has no comments.