You can import specific catalog item data into a dataset using the Interaction Studio API. This is useful if you want to add catalog items from your database to your Interaction Studio 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 Interaction Studio it is updated, otherwise it is inserted. This data must be constructed very precisely and submitted to Interaction Studio 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.).
Deprecated API
This API is deprecated. Customers that continue to leverage this API should be aware that support troubleshooting and bug fixes for this API are no longer available. We recommend leveraging the productized feeds outlined here.
This section details how to import user and account data into a dataset using the Interaction Studio API.
Introduction
Here is the basic structure for the Users Upsert API, assuming your account name with Interaction Studio is "account" and your dataset is "engage"
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.
[ { "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.
[ { "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:
Interaction Studio Account Key (this is the subdomain you use to login to Interaction Studio with, if your account is "testaccount.evergage.com", then use "testaccount"):
testaccount
Interaction Studio Dataset (by default this is "engage"):
engage
API Token Key ID (the ID of the API token you are using to authenticate and authorize the request)
AACEA8E0-1A43-414C-97E0-FD8357485CF7
API Token Secret Key (the API key secret for the designated API token
wdrsZ4aSwJ1zkxcVuyLyBstgM-k6hL7h4967PAQW7xg
Authorization Value (for some examples, this is the HTTP Basic encoding of your API Token key ID and secret key.
Basic QUFDRUE4RTAtMUE0My00MTRDLTk3RTAtRkQ4MzU3NDg1Q0Y3OndkcnNaNGFTd0oxemt4Y1Z1eUx5QnN0Z00tazZoTDdoNDk2N1BBUVc3eGc=
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" -H "Authorization: Basic QUFDRUE4RTAtMUE0My00MTRDLTk3RTAtRkQ4MzU3NDg1Q0Y3OndkcnNaNGFTd0oxemt4Y1Z1eUx5QnN0Z00tazZoTDdoNDk2N1BBUVc3eGc=" "https://testaccount.evergage.com/api/dataset/engage/users/upsert?_at=1234567A-1A2B-DEF1-A123-123A456B789C"
CSV:
curl -k -X POST -F "file=@fileName.csv" -H "Authorization: Basic QUFDRUE4RTAtMUE0My00MTRDLTk3RTAtRkQ4MzU3NDg1Q0Y3OndkcnNaNGFTd0oxemt4Y1Z1eUx5QnN0Z00tazZoTDdoNDk2N1BBUVc3eGc=" "https://testaccount.evergage.com/api/dataset/engage/users/upsert?_at=1234567A-1A2B-DEF1-A123-123A456B789C"
Java Example for User Upsert
- 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 apiTokenId = "AACEA8E0-1A43-414C-97E0-FD8357485CF7"; // in practice, never hard-code this secret! String apiTokenSecret = ""; client.addFilter(new HTTPBasicAuthFilter(apiTokenId, apiTokenSecret)); 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) { $requestURI = "https://" . $evergageAccount . ".evergage.com/api/dataset/" . $dataset . "/users/upsert"; // 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', 'Authorization: Basic QUFDRUE4RTAtMUE0My00MTRDLTk3RTAtRkQ4MzU3NDg1Q0Y3OndkcnNaNGFTd0oxemt4Y1Z1eUx5QnN0Z00tazZoTDdoNDk2N1BBUVc3eGc='); 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"); ?>
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") req.add_header("Authorization", "Authorization: Basic QUFDRUE4RTAtMUE0My00MTRDLTk3RTAtRkQ4MzU3NDg1Q0Y3OndkcnNaNGFTd0oxemt4Y1Z1eUx5QnN0Z00tazZoTDdoNDk2N1BBUVc3eGc=") response = urllib2.urlopen(req, json.dumps(data))