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
- Optional: Create a new mount point and upload the file to it
- Create a new import or update an existing import to reference a new mount point
- Start the import
CSV/Excel Import
- Create import with mappings manually in UI. Ensure you have the right import type in Settings. Make sure to record Import ID.
- Create a new mount point and upload the file to it
- Update the import to reference the new mount point
- 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.