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
| Name | Type | Description |
|---|---|---|
| fileLocation | String | The upload location of the data file. This location is the URL that is returned when you request the transfer location. |
| fieldDelimiter | String | The delimiter that separates columns in the data file. Note: Only commas (,) are supported currently. |
| fileType | String | The file type of the data. Note: Only CSV files are supported currently. |
| recordLimit | int | (Optional) Specifies the number of records to import. If the value is empty or set to 0, then all of the records are imported. |
| updateMode | String | (Optional) The mode in which the imported data is processed. The mode can be:
|
| headerRowIncluded | boolean | Set 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
User's Guides
Get guidance on optimizing marketing activities, analyzing visitor behavior, and gaining a 360-degree customer view.
Training
Explore our training options – from on-site classroom, to live web, to e-learning, to one-on-one mentoring.
