(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 Article Explains
This section details how to upload specific user and account data into your dataset using the Evergage API.
Sections in this Article
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.
NOTE
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.
NOTE
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.
NOTE
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@evergage.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
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, select your dataset and navigate to Settings > Attributes. From here you can set the custom fields as an attribute of the user or account. Make sure the Attribute 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 support@evergage.com and we'll double check then upsert it for you.
Overview
Content Tools