Upload data through REST API

Learn how to upload customer data and location (geofence and geobeacon) data through the REST API by using tools such as Postman (for Chrome) or REST Client (for Firefox).

 

 

Prerequisite

Before you can upload data, ensure that you define your data descriptors. If you need to create a data descriptor, see Creating a Data Descriptor.

Get the Data Descriptor

The REST call to create a data descriptor returns an ID that can be used to access the descriptor in other calls.

Use this REST call to get the data descriptor:

GET https:<server>/SASWebMarketingMid/rest/descriptors

This call returns a REST collection similar to this example:


{
"links": [links removed from example. You can use the
links to navigate through resource collections.],
"name": "descriptors",
"accept": "application/vnd.sas.marketing.data.descriptor.summary
application/vnd.sas.marketing.data.descriptor
application/vnd.sas.collection application/json text/plain",
"start": 0,
"count": 3,
"items": [
{
"name": "customer",
"id": "7f995e66-4474-4b9b-b37a-c64796c09bab",
},
{
"name": "geofence_location",
"id": "dc8947e9-ed62-4b0c-b7bd-f82c52e310f9",
},
{
"name": "contact_preference",
"id": "7ba72601-24bc-4d61-b325-c8127f760234",
}
],
"limit": 3,
"version": 2
}

The customer table has a data descriptor ID of 7f995e66-4474-4b9b-b37a-c64796c09bab. This value is used to retrieve the location to upload the data file.
Get a Transfer Location

Use the descriptor ID to get a temporary URL that you can use to upload the file.

Note: Temporary URLs can be accessed for about 15 minutes before they time out. You can use them more than once, but you can always request a new URL if you do not start your upload in the 15-minute window.

POST

https:<server>/SASWebMarketingMid/rest/fileTransferLocation/

The response should be similar to this example. (Be aware that line breaks in the URL string are for readability only.)


{
"signedURL":
"https://<somehost>.s3.amazonaws.com/transfers/5/fc80e6ed904e4a988
1625b34481535c2?x-amz-security-token=AQoDYXdzEF4a4AN8n1XWewOv27%2B5gIbEP
JiZRrpmnyVi4Jl8g5moBn%2FX6YvLcsm1IuGZJsy3420t4u6lYWG9j4if45Wt%2FTjRZaF1k
mi608%2BAuTBSl4SSe7wNSgxkKaezqdlaN0WyrRjnp15o%2BvHo8HzHXA6qKXpLjMofMGgFc
J%2FFTP2blwnUhrNlWTYBYEUedcktP2Onh2KvTDL6xYD2AeOT%2F4D0QuSM21%2BLDGph2X0
kpMvGL8kgZy%2FqrslKqXqjJV1Kkz8eQpFVwzEWLoDBgnikrVeyeYaTzM48bhIrXy%2BXT9x
AkPifS3C0BPEkKoMt%2BuFiQziGDcgtyR7d0JNOeB%2Bp5POGtly9sl7iFLKTyed6ugoIKTB
xl6%2FylJ69ACUSAZYeinIThEp5pznLRv4Ov%2BxVq0cMlanLlpipPvF3ANppYN4eKJfZ5xs
dghggtrapxuqF6mbD1KQ5NQjXj9Y86EouYUb44ifsMjC88uuKCqvlJOR7O%2BtzVw2LwRA1u
a8lPWFqwuP4u771uewUmA1Vz2kumbvVpiOpQVDkHCsHUsuJcXqf1LbGXQa2uZvOIcGBVIRXS
6rkDfiPMHojiQhPhSoZtwC8YqXnLlUXUrGwAo%2FieXw0PLUGmuBRu4RRXniuM5GrozAU9dH
0ZjcguaSQrAU%3D&AWSAccessKeyId=ASIAI2IPARNVEU575GBA&Expires=1434722523&
Signature=n9mYRyF%2Fc47Czni4bdvnnsmushI%3D"
"httpMethod": "POST",
"createdTimeStamp": "2016-03-08T13:47:03Z",
"expiresTimeStamp": "2016-03-08T14:02:03Z"
}

Upload the JSON File

Upload the file with curl. Pass in the URL that was recently generated:


curl -v --upload-file myfile.csv
"https://<somehost>.s3.amazonaws.com/transfers/5/fc80e6ed904e4a988
1625b34481535c2?x-amz-security-token=AQoDYXdzEF4a4AN8n1XWewOv27%2B5gIbEP
JiZRrpmnyVi4Jl8g5moBn%2FX6YvLcsm1IuGZJsy3420t4u6lYWG9j4if45Wt%2FTjRZaF1k
mi608%2BAuTBSl4SSe7wNSgxkKaezqdlaN0WyrRjnp15o%2BvHo8HzHXA6qKXpLjMofMGgFc
J%2FFTP2blwnUhrNlWTYBYEUedcktP2Onh2KvTDL6xYD2AeOT%2F4D0QuSM21%2BLDGph2X0
kpMvGL8kgZy%2FqrslKqXqjJV1Kkz8eQpFVwzEWLoDBgnikrVeyeYaTzM48bhIrXy%2BXT9x
AkPifS3C0BPEkKoMt%2BuFiQziGDcgtyR7d0JNOeB%2Bp5POGtly9sl7iFLKTyed6ugoIKTB
xl6%2FylJ69ACUSAZYeinIThEp5pznLRv4Ov%2BxVq0cMlanLlpipPvF3ANppYN4eKJfZ5xs
dghggtrapxuqF6mbD1KQ5NQjXj9Y86EouYUb44ifsMjC88uuKCqvlJOR7O%2BtzVw2LwRA1u
a8lPWFqwuP4u771uewUmA1Vz2kumbvVpiOpQVDkHCsHUsuJcXqf1LbGXQa2uZvOIcGBVIRXS
6rkDfiPMHojiQhPhSoZtwC8YqXnLlUXUrGwAo%2FieXw0PLUGmuBRu4RRXniuM5GrozAU9dH
0ZjcguaSQrAU%3D&AWSAccessKeyId=ASIAI2IPARNVEU575GBA&Expires=1434722523&
Signature=n9mYRyF%2Fc47Czni4bdvnnsmushI%3D"

For more information about how to use curl, see the curl website at https://curl.haxx.se/.
Initialize the Import Process

After the data file is uploaded, use this REST call to request that SAS Customer Intelligence 360 import the data:

POST
https:<server>/SASWebMarketingMid/rest/descriptors/{dataDescriptorID}/imports

The URL would look similar to this example:

https:<server>/SASWebMarketingMid/rest/descriptors/9f995e66-4374-
4b9b-b37a-c64796c09bab/imports

In the body of the request, add the JSON script that describes the data that is being imported. Here is an example import request:


{
   "fileLocation":
     "https://<somehost>.s3.amazonaws.com/transfers/5/fc80e6ed904e4a988
     1625b34481535c2?x-amz-security-token=AQoDYXdzEF4a4AN8n1XWewOv27%2B5gIbEP
     JiZRrpmnyVi4Jl8g5moBn%2FX6YvLcsm1IuGZJsy3420t4u6lYWG9j4if45Wt%2FTjRZaF1k
     mi608%2BAuTBSl4SSe7wNSgxkKaezqdlaN0WyrRjnp15o%2BvHo8HzHXA6qKXpLjMofMGgFc
     J%2FFTP2blwnUhrNlWTYBYEUedcktP2Onh2KvTDL6xYD2AeOT%2F4D0QuSM21%2BLDGph2X0
     kpMvGL8kgZy%2FqrslKqXqjJV1Kkz8eQpFVwzEWLoDBgnikrVeyeYaTzM48bhIrXy%2BXT9x
     AkPifS3C0BPEkKoMt%2BuFiQziGDcgtyR7d0JNOeB%2Bp5POGtly9sl7iFLKTyed6ugoIKTB
     xl6%2FylJ69ACUSAZYeinIThEp5pznLRv4Ov%2BxVq0cMlanLlpipPvF3ANppYN4eKJfZ5xs
     dghggtrapxuqF6mbD1KQ5NQjXj9Y86EouYUb44ifsMjC88uuKCqvlJOR7O%2BtzVw2LwRA1u
     a8lPWFqwuP4u771uewUmA1Vz2kumbvVpiOpQVDkHCsHUsuJcXqf1LbGXQa2uZvOIcGBVIRXS
     6rkDfiPMHojiQhPhSoZtwC8YqXnLlUXUrGwAo%2FieXw0PLUGmuBRu4RRXniuM5GrozAU9dH
     0ZjcguaSQrAU%3D&AWSAccessKeyId=ASIAI2IPARNVEU575GBA&Expires=1434722523&
     Signature=n9mYRyF%2Fc47Czni4bdvnnsmushI%3D"
   "fieldDelimiter": ",",
   "contentName": "Customer Data as of May 2015",
   "fileType": "CSV",
   "recordLimit": 0,
   "headerRowIncluded": true
}

The JSON script in the body can uses these parameters:

JSON Body of POST Call to Import Data

NameTypeDescription
fileLocationStringThe upload location of the data file. This location is the URL that is returned when you request the transfer location.  
fieldDelimiter
StringThe delimiter that separates columns in the data file.
Note: Only commas (,) are supported currently.  
fileTypeString

The file type of the data.

Note: Only CSV files are supported currently.  

recordLimitint(Optional) Specifies the number of records to import. If the value is empty or set to 0, then all of the records are imported.  
updateModeString

(Optional) The mode in which the imported data is processed.

The mode can be:

  • replace: This method replaces all the data from previous uploads to this descriptor
  • append: This method appends data from the imported file to the customer records that already exist for this data descriptor.
  • upsert: this method updates any existing records and appends new records. The upsert mode updates values based on the checking data items with the isKey set. For more information, see Structure of a Data Descriptor.
headerRowIncludedbooleanSet to true if the first row contains header information instead of a data record. Note: Even if you include a header row, the column is not read to determine the placement of columns. The data must be in the same order as the fields in the descriptor.  
   

The CSV file must have data columns in the same order as the descriptor. Use a comma to separate the columns. This specific request says that the input file has a header row that should be skipped when processing the data.  

Example of a Contact Preference File

The following example is a contact preference file that contains a header row:


id_type,id_value,preference_type_cd,preference_value
email_id,jose.silva@place.com,OPT-OUT,false
email_id,amita.yeleswarapu@example.com,OPT-OUT,true
email_id,bill.withers@yahoo.com,OPT-OUT,true
email_id,yuki.minami@example.com,OPT-OUT,true

Tips

  • Ensure that any contact lists (such as email opt-out lists) do not contain duplicate email addresses.
  • In the data descriptor, define the isKey value for more than one column to create a composite identity key. This composite key is used when you use data import’s upsert mode to update your data.

    For this example, you could set the isKey value to true for id_type, id_value, and preference_type_cd. In the second row, “email_id”, “jose.silva@place.com”, and “OPT-OUT” specify the OPT-OUT value for that email address. Many rows might have the values "email_id" and "OPT-OUT" for those respective data columns, but this specific record is made unique when you combine those values with the unique email address.  


Be a part of the SAS® Customer Intelligence Community

Meet and mingle with other users in the SAS Customer Intelligence Community. Ask questions. Get answers. Share tips. It's a great place to learn, grow and collaborate.        

Join the community

More Ways to Learn

users-guides-computer-book

User's Guides

Get guidance on optimizing marketing activities, analyzing visitor behavior, and gaining a 360-degree customer view.

computer-with-keyboard

Training

Explore our training options – from on-site classroom, to live web, to e-learning, to one-on-one mentoring.

light-blub-plant

Certification

Validate your SAS knowledge and skills. Earn a globally recognized credential from SAS to set yourself apart.

Back to Top