Ephemeral Exports APIĀ 

Updates have been made to include organization ID in the URL path as of April 2017. This is the preferred method, but previously-working methods will continue to function as expected.

Overview

Ephemeral exports are designed as data dumps from the system, allowing exports of raw data from Salsify.

To create an ephemeral export, you should follow these steps:

  1.  Call the export API with your export configuration.  This will create an export run
  2. Get status of the export run and download the product file and assets when it completes

Calling the Salsify Export API

You will first call the export API with a configuration payload to kick off the export.  To do that, you will create a file that contains the export run configuration (in JSON) and pass that into the export_run API.  

Minimum User Permissions

The user needs to have these minimum Salsify permissions:

Exports - Read/Manage
Products - Read
Profile - Read/Manage
Properties - Read

Click here for more information about setting user permissions.

The export run configuration (JSON) should look something like this. In this example, we are saving this JSON in a file in the same directory from which we are running CURL, and the file is named example.json:

{
  "configuration":{
    "entity_type":"product",
    "filter":"=list:default",
    "properties":"'sku','Name','Supplier','Release Date','NEW_COLUMN_JC','Long Description'",
    "include_all_columns":true,
    "product_type":"all"
  }
}

Next, call the export_run API like this:

curl -X POST https://app.salsify.com/api/orgs/9999-9999-9999-9999/export_runs -d @example.json --header "Content-Type:application/json" --header "Authorization: Bearer <AUTH TOKEN HERE>"

This should return something like this:

{"id":27606,"status":"running","start_time":"2014-10-01T13:47:44.155Z","end_time":null,"duration":0.024469168,"url":"","progress":0,"failure_reason":null,"estimated_time_remaining":""}

The requirement for you on your end would be to store the id above after you perform each export so that you can poll the export_runs API for status to determine if the export finished successfully or not. See below for how to poll the export_runs API for this status, using this id.

curl -X GET https://app.salsify.com/api/orgs/9999-9999-9999-9999/export_runs/27606 --header "Authorization: Bearer <AUTH TOKEN HERE>"

This should return a status such as the following:

{"id":27606,"status":"completed","start_time":"2014-10-01T13:47:44.155Z","end_time":"2014-10-01T13:47:56.456Z","duration":12.3018922805786,"url":"https://salsify-dandelion.s3.amazonaws.com/1/226/user_data_export/1/2014/10/01/13%3A47%3A56-43d9875e/export.xlsx?AWSAccessKeyId=AKIAJSAUHNZHZGLUDXDA&Expires=1412175525&Signature=qZP46KIFANjVl1%2B5MwjvusKUI1s%3D","progress":100,"failure_reason":null,"estimated_time_remaining":"less than a minute"}

API Response Guidelines  

A successful export run generates a JSON file split up into several sections: 

Header 

  • Key in JSON: header

Attributes 

  • Key in JSON: attributes
  • Format
    { "salsify:id": "Our Company ID", "salsify:role": "product_id"} 
    • Each entry has a “salsify:id” that maps to the identifier in your Salsify system.
    • Each entry has a “salsify:role” that maps to the role in your system, which could be “product_id”, “product_name”, or no role.

Attribute Values 

  • Key in JSON: attribute_values 
  • Format 
    { "salsify:attribute_id": "My Category", "salsify:id": "Accessories", "salsify:name": "Accessories"} 
    • Each entry has a “salsify:attribute_id” that maps to the identifier of a category.
    • Each entry has a “salsify:id” and “salsify:name” that identifies an attribute value for the given category.

Products 

  • Key in JSON: products
  • Format
    { "salsify:id": "An ID for this product", "Our Company ID": "An ID for this product", "salsify:name": "My favorite product", "salsify:system_id": s-123-456-789"} 
    • The first two, salsify:id and Our Company ID have the same values because the ID for this company is Our Company ID and our global name for a company’s ID is called a salsify:id.
    • The third entry is the salsify:name, or the value for the product’s name identifier.
    • The last entry is the salsify:system_id, which is an ID that we use to uniquely identify products across companies in our system.

We DO NOT commit to the order of these sections or the order of any keys in the sections of the response JSON. The addition of a new section would NOT amount to a breaking change in the API format.