Imports 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

Imports are designed to get your data into our system. We support importing csv, Excel and our documented json format from ftp or an uploaded file. We suggest using imports when the number of entities to create or update is in the hundreds or more, managing enumerated values or upsert behavior for entities.

JSON Import

1. Optional: Create a new mount point and upload the file to it
2. Create a new import or update an existing import to reference a new mount point
3. Start the import

CSV/Excel Import

1. Create import with mappings manually in UI. Ensure you have the right import type in Settings. Make sure to record Import ID.
2. Create a new mount point and upload the file to it
3. Update the import to reference the new mount point
4. Start the import

Note: make sure to pass your authorization token in.  See  Getting Started with API Authorization for more information.

<org_id> should be replaced by the organization ID which is unique to each Salsify app instance. The org ID can be found after /orgs/ in the URL path for your Salsify organization, eg. in https://app.salsify.com/app/orgs/9-99999-9999-9999-9999-999999999/products the org ID is 9-99999-9999-9999-9999-999999999.

Creating a mount point

POST to /api/orgs/org_id/imports/upload_mounts

This will allow you to upload a file for importing.

Request:

curl 'https://app.salsify.com/api/orgs/<org_id>/imports/upload_mounts' 
-X POST --header "Authorization: Bearer <YOUR_AUTH_TOKEN_HERE>"

Response:

{
  url":"https://salsify-dandelion.s3-external-1.amazonaws.com",
  "form_data":{
	"key":"<MOUNT_POINT_UPLOAD_PATH>",
	"X-amz-server-side-encryption":"<SERVER_SIDE_ENCRYPTION>",
	"acl":"<ACL>",
	"policy":"<POLICY>",
	"x-amz-credential":"<CREDENTIAL>",
	"x-amz-algorithm":"<ALGORITHM>",
	"x-amz-date":"<DATE>",
	"x-amz-signature":"<SIGNATURE>"
  	}
}

Uploading to a mount point

POST multipart/form-data to the url from the mount point response with all elements of form-data from the mount point response as well as the new import file.

Request:

curl 'https://salsify-dandelion.s3-external-1.amazonaws.com' -X POST \ 
-H "Content-Type: multipart/form-data" \ 
-F "key=<MOUNT_POINT_UPLOAD_PATH>" \
-F "x-amz-server-side-encryption=<SERVER_SIDE_ENCRYPTION>" \
-F "acl=<ACL>" \
-F "policy=<POLICY>" \
-F "x-amz-credential=<CREDENTIAL>" \
-F "x-amz-algorithm=<ALGORITHM>" \
-F "x-amz-date=<DATE>" \
-F "x-amz-signature=<SIGNATURE>" \
-F file=@./file_name.json

Note:

• Errors will be returned as XML
• The path and file name are examples and will vary by what you are sending.
• Actual values represented here may be longer in your actual request/response interaction. They have been shortened here for ease of readability.

Creating a JSON import

POST to /api/orgs/<org_id>/imports

From a mount point

{
  "import": {
    "name": "My Import",
    "import_source": {
      "file": "<FILENAME>",
      "type": "upload_import_source",
      "upload_path": "<KEY_FROM_FORM_DATA>"
    },
    "import_format": {
      "type": "json_import_format"
    }
  }
}

From FTP

{
  "import": {
    "name": "My Import",
    "import_source": {
      "type": "ftp_import_source",
      "file": "<FILENAME>",
      "host": "<FTP HOSTNAME>",
      "port": "<FTP PORT>",
      "username": "<FTP USERNAME>",
      "password": "<FTP PASSWORD>",
      "protocol": "<ftp or sftp>",
    },
    "import_format": {
      "type": "json_import_format"
    }
  }
}

Updating an import to point at a new mount point

PUT to /api/orgs/<org_id>/imports/<IMPORT_ID> with JSON request (be sure to set the Content-Type to application/json) to update the import with a new file:

{
  "import": {
    "import_source": {
      "file": "<FILENAME>",
      "type": "upload_import_source",
      "type_label": "Upload",
      "upload_path": "<KEY FROM FORM-DATA>"
    }
  }
}

Starting an import run

POST to /api/orgs/<org_id>/imports/<IMPORT ID>/runs to start the import. 

Sample response:

{
  "id":856,
  "status":"running",
  "start_time":"2013-10-17T17:56:21.585Z",
  "end_time":null,
  "duration":0.240623376,
  "failure_reason":null,
  "progress":0,
  "stage_data":[
    {
      "id":"schema",
      "statistics":[...],
      "messages":[],
      "total_errors":0,
      "progress":0,
      "begin":"2013-10-17T17:56:21Z",
      "end":null,
      "duration":1
    }
  ],
  "import":{
    "id":462,
    "import_source":{
      "type":"cloud_import_source",
      "type_label":"Upload",
      "file":"export (13).xlsx",
      "upload_path":"1/103/user_data_import/1/2013/10/17/17:56:12-6c1b4797"
    },
    "import_format":{
      "type":"attribute_import_format",
      "import_mode":"upsert",
      "type_label":"Schema"
    }
  }
}

To check status and confirm success, GET /api/orgs/<org_id>/imports/runs/<IMPORT_RUN_ID> until status is completed or failed. The <IMPORT_RUN_ID> is the value from the “id” key at the root of the JSON document. In the above example response, <IMPORT_RUN_ID> would be 856. Recommended interval is 15s or more to minimize the load on our servers

Scheduling Imports

Imports can be scheduled in Salsify to run on a recurring basis by setting up the Repeat section of the import configuration.