Documentation & Feedback/Using Evergage/Setting Up Evergage

How to Import and Export Data via REST API

Andrew Patti
posted this on August 02, 2013 01:22 PM

Customer data can be securely retrieved and update in Evergage using the REST - JSON API. Data including engagement score and change, customer attributes and activity can be exported for use in other systems. User and Account attributes can also be updated.
 
API Endpoints for users and accounts are available in JSON and CSV format. 
Users:
 
   https://<EVERGAGE_ACCOUNT>.evergage.com/api/dataset/<DATASET>/users.[ json | csv ]
 
 
 
Accounts:
 
  https://<EVERGAGE_ACCOUNT>.evergage.com/api/dataset/<DATASET>/accounts.[ json | csv ]
 
 
Parameters:
 
 
Parameter Description Required
_at
API Token (Required); to get the API token, after logging into Evergage click on your name in the top right hand corner and you'll see an option for an API token
True
filter
Optional Filter or Segment name or ID
 
start Optional start time in epoch milliseconds used for engagement statistics  
end Optional end time in epoch milliseconds used for engagement statistics  
segmentationId Optional segmentation identifier  
segmentId Optional segment identifier  
pageSize The number of records to return (defaults to all records)  
page The page number of records to show. Starting at zero for the first page. (defaults to zero)  
 
 
User Retrieval Example:
 
 
[{
    "name":"abdulagoras@adelphia.com", 
    "engagementScore":0.012, 
    "engagementPercentChange":0.002, 
    "firstActivity":1358957180647, 
    "lastActivity":1359066698647, 
    "totalActions":0, 
    "attributes":{}, 
    "accountName":"adelphia communications corporation", 
    "displayName":"Abdul Agoras"
}]
 
Account Retrieval Example:
 
 
[{
    "name":"3com corp",
    "engagementScore":0.546,
    "engagementPercentChange":-0.138,
    "firstActivity":1358640000000,
    "lastActivity":1360195200000,
    "totalActions":51,
    "accountStatus":"premium",
    "attributes":{},
    "accountName":"3com corp",
    "activeUsers":3
}]
 
 
 
Update User Example:
 
Users can be updated in batch via the following path. Data is sent in array form and must include the 
user's unique ID and if the dataset is setup for accounts it must also include the match accountName.
 
 
 
 
Example update JSON:
The following is example JSON that can be posted to the user upsert path to update user attributes. 
This example updates the user attribute "age" to the value "33". All attributes must be sent as strings.
 
[{
    "name":"adelinabaumiester@the.com", 
    "attributes":{ "age":"33"}, 
    "accountName":"the aes corporation" 
}]
 
 
 
Example user upsert Java:
 
mport 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 = "myEvergageAccount";
        String dataset = "myDataset";
        String apiToken = "apiToken";
 
        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); } } }
Update Account Example:
 
Users can be updated in batch via the following path. Data is sent in array form and must include the 
user's unique ID and if the dataset is setup for accounts it must also include the match accountName.
 
 
 
 
Example update JSON:
 
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" to the value "Paid". All attributes must be sent as strings.
 
[{
    "name":"the aes corporation", 
    "attributes":{ "accountStatus":"Paid"}
}]

PHP API Example:
User retrieval Example (PHP)

 <!doctype html>
<head>
<title>Evergage Customer Retrieval Example</title>
</head>
 
<body>
<?php
 
 
function RetrieveEvergageData($account, $dataset, $kind, $apiToken)
{
 
$port = "";
if ($account === "localtest") {
$port = ":8443";
}
 
// The reqest URI
$requestURI = "https://" . $account . ".evergage.com" . $port . "/api/dataset/" . $dataset . "/" . $kind . ".json?_at=" . $apiToken ;
// print("URL: " . $requestURI . "<br/>");
 
$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);
 
 
$headers = array(
'Accept: application/json',
'Content-Type: application/json',
);
curl_setopt($session, CURLOPT_HTTPHEADER, $headers);
 
curl_setopt ($session, CURLOPT_CUSTOMREQUEST, "GET");
curl_setopt($session, CURLOPT_URL, $requestURI);
 
$response = curl_exec($session);
$info = curl_getinfo($session);
 
 
$responseCode = $info["http_code"];
if ($responseCode >= 300) {
print("Error loading data: " . $responseCode . "<br/>");
print($response);
} else {
$body = substr($response, $info['header_size']);
$decoded_result = json_decode($body, true);
}
 
curl_close($session);
 
return $decoded_result;
}
 
 
 
 
 $users = RetrieveEvergageData("localtest", "test", "users", "28CE470F-938B-4E14-4C22-729862718AAA");
 
 
  if ($users) {
 
  print( "<table> ");
  print("  <tr><td>Username</td> <td>Account</td> <td> Engagement Score</td> <td>Engagement % Change</td></tr>");
 
  foreach ($users as $user) {
   print("<tr>");
print( "<td>" . $user['name'] . "</td>");
 
   print(" <td>" . $user['accountName'] . "</td>");
 
   print(" <td>" . $user['engagementScore'] . "</td>");
   print(" <td>" . $user['engagementPercentChange'] . "</td>");
 
   print("</tr>");
  }
  }
 
?>
 
</body>
</html>


User update  Example (PHP)

<!doctype html>
<head>
<title>Evergage Customer Retrieval Example</title>
</head>
 
<body>
<?php

function UpdateEvergageData($account, $dataset, $kind, $apiToken)
{
 
$port = "";
if ($account === "localtest") {
$port = ":8888";
}
 
// The reqest URI
$requestURI = "http://" . $account . ".evergage.com" . $port . "/api/dataset/" . $dataset . "/" . $kind .
              "/upsert?_at=" . $apiToken . "&_ak=" . $account;
// print("URL: " . $requestURI . "<br/>");

// Set Request Options
$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 . "<br/>");
print($response);
} else {
$body = substr($response, $info['header_size']);
$decoded_result = json_decode($body, true);
}
 
curl_close($session);
 
return $decoded_result;
}

RetrieveEvergageData("localtest", "websim", "users", "2387528A-6C0B-EB85-A914-040E92DA6C66");

?>
 
</body>
</html>