Users and Accounts Import API

You can import specific catalog item data into a dataset using the Evergage API. This is useful if you want to add catalog items from your database to your Evergage dataset directly instead of waiting for them populate with specific events. You can also use catalog item upserts to update a specific catalog already in your dataset. These import are called "upserts" because if the catalog item is already known to Evergage it is updated, otherwise it is inserted. This data must be constructed very precisely and submitted to Evergage as a .CSV (Comma Separated Value) file. These files can be created in any spreadsheet program such as MS Excel or Google Sheets. Spreadsheet, etc.).

This Article Explains

This section details how to import user and account data into a dataset using the Evergage API.

Sections in this Article

Introduction

Here is the basic structure for the Users Upsert API, assuming your account name with Evergage is "account" and your dataset is "engage"

https://account.evergage.com/api/dataset/engage/users/upsert

Users can be updated in batch. Data is sent in array form and must include the user's unique ID, and if the dataset is setup to track accounts, it must also include the matching accountName.

Here is the basic structure for the Accounts Upsert API, assuming your account name with Evergage is "account" and your dataset is "engage"

https://account.evergage.com/api/dataset/engage/accounts/upsert

Example JSON file format for User Upsert

The following is example JSON that can be posted to the user upsert path to update user attributes.

This example updates the user attributes "age" and "state" respectively. All attributes must be sent as strings.

[
    { "name": "bobsmith@aes.com", "attributes": { "age": "33", "state": "MA" }, "accountName": "the aes corporation" },
    { "name": "janesmith@company.com", "attributes": { "age": "19", "state": "VA" }, "accountName": "the company com" }
]

Example JSON file format for Account Upsert

The following is example JSON that can be posted to the account upsert path to update account attributes.

This example updates the account attribute "accountStatus". All attributes must be sent as strings.

[
    { "name": "the aes corporation", "attributes": { "accountStatus": "Paid" } },
    { "name": "the company com", "attributes": { "accountStatus": "Free" } }
]

Example CSV file format for Updates

See CSV Users and Accounts Import for a detailed document on how the CSV file should look.

Update Language Examples

For all examples, we will be using the following values:

Evergage Account Key (this is the subdomain you use to login to Evergage with, if your account is "testaccount.evergage.com", then use "testaccount"):

testaccount

Evergage Dataset (by default this is "engage"):

engage

API Token (this is used to authenticate your requests and can be found in our UI under Settings -> API Tokens:

1234567A-1A2B-DEF1-A123-123A456B789C

File name. When using file names (CURL), we assume you've named your files fileName.json and fileName.csv (for JSON and CSV formats respectively):

fileName.json / fileName.csv

CURL Example for User Upsert

Upserting data through CURL on the command line can be done with both CSV and JSON files.

The syntax is slightly different for both formats, so be sure to use the correct command depending on the format of your data.

For both commands you will need a few key values. In the commands listed below be sure to replace the accountKey, datasetName, apiToken, and fileName fields to their correct values. The account token value is available under the API Tokens Settings.

JSON:

curl -k -X POST -d @fileName.json -H "Content-Type:application/json" "https://testaccount.evergage.com/api/dataset/engage/users/upsert?_at=1234567A-1A2B-DEF1-A123-123A456B789C"

CSV:

curl -k -X POST -F "file=@fileName.csv" "https://testaccount.evergage.com/api/dataset/engage/users/upsert?_at=1234567A-1A2B-DEF1-A123-123A456B789C"

Java Example for User Upsert

Dependencies:

Jersey REST Client: https://jersey.java.net/documentation/latest/client.html
Jackson JSON serialization provider (jackson-jaxrs-providers):https://github.com/FasterXML/jackson-jaxrs-providers

import com.sun.jersey.api.client.Client;
import com.sun.jersey.api.client.ClientResponse;
import com.sun.jersey.api.client.WebResource;
import javax.ws.rs.core.UriBuilder;
import java.net.URI;
import java.util.HashMap;
import java.util.Map;

public class RestCustomerUpdateToolMap {
    public static void main(String[] args) {
        Client client = Client.create();
        String evergageAccount = "testaccount";
        String dataset = "engage";
        String apiToken = "1234567A-1A2B-DEF1-A123-123A456B789C";
        URI uri = UriBuilder.fromUri(
                "https://" + evergageAccount + ".evergage.com/api/dataset/" + dataset + "/users/upsert")
                .queryParam("_at", apiToken).queryParam("_ak", evergageAccount).build();
        WebResource webResource = client.resource(uri);

        Map<String, Object> user = new HashMap<String, Object>();
        user.put("name", "adelinabaumiester@the.com");
        user.put("accountName", "the aes corporation");
        Map<String, String> userAttributes = new HashMap<String, String>();
        userAttributes.put("age", "37");
        user.put("attributes", userAttributes);

        ClientResponse response = webResource.type("application/json").post(ClientResponse.class, new Object[]{user});

        int status = response.getStatus();
        if (status >= 300) {
            System.out.println("Output from Server .... \n");
            String output = response.getEntity(String.class);
            System.out.println(output);
            throw new RuntimeException("Failed : HTTP error code : " + response.getStatus());
        } else {
            System.out.println("Updates sent.... \n");
            String output = response.getEntity(String.class);
            System.out.println(output);
        }
    }
}

PHP Example for User Upsert

User update  Example (PHP)

<!doctype html>
<?php

function UpdateEvergageData($evergageAccount, $dataset, $apiToken)
{
    $requestURI = "https://" . $evergageAccount . ".evergage.com/api/dataset/"
        . $dataset . "/users/upsert?_at=" . $apiToken . "&_ak=" . $evergageAccount;

    // Set Request Options $session = curl_init();

    $session = curl_init();
    curl_setopt($session, CURLOPT_FAILONERROR, false);
    curl_setopt($session, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($session, CURLOPT_FOLLOWLOCATION, false);
    curl_setopt($session, CURLOPT_HEADER, true);
    curl_setopt($session, CURLOPT_SSL_VERIFYHOST, false);
    curl_setopt($session, CURLOPT_SSL_VERIFYPEER, false);
    curl_setopt($session, CURLOPT_POST, true);
    curl_setopt($session, CURLOPT_CUSTOMREQUEST, "POST");
    curl_setopt($session, CURLOPT_URL, $requestURI);

    //Set Headers

    $headers = array('Accept: application/json', 'Content-Type: application/json');

    curl_setopt($session, CURLOPT_HTTPHEADER, $headers);

    // Construct User Data

    $data = array(
        array("name" => "adelinabaumiester@the.com", "accountName" => "the aes corporation", "attributes" => array("age" => "38")),
        array("name" => "agripinablevins@agco.com", "accountName" => "agco corporation", "attributes" => array("age" => "40"))
    );

    $data_string = json_encode($data);
    curl_setopt($session, CURLOPT_POSTFIELDS, $data_string);

    $response = curl_exec($session);

    $info = curl_getinfo($session);

    $responseCode = $info["http_code"];
    if ($responseCode >= 300) {
        print("Error loading data:" . $responseCode . "");
        print($response);
    } else {
        $body = substr($response, $info['header_size']);
        $decoded_result = json_decode($body, true);
    }

    curl_close($session);

    return $decoded_result;
}

UpdateEvergageData("testaccount", "engage", "1234567A-1A2B-DEF1-A123-123A456B789C");

?>

Python Example for User Upsert

import json
import urllib2

data = [{"name":"kevin", "attributes":{"AlexTest":"success"}}]
req = urllib2.Request("https://testaccount.evergage.com/api/dataset/engage/users/upsert?_at=1234567A-1A2B-DEF1-A123-123A456B789C")
req.add_header("Content-Type", "application/json")
response = urllib2.urlopen(req, json.dumps(data))

Space shortcuts

Page tree