Import a Data CSV via API

With Watershed's CSV Import Feature, you can bring both xAPI and groups data into Watershed with a flat CSV file. This is done by first creating an xAPI template or creating a template for organizational hierarchy data. Users can then upload files with new data on a regular basis.

To avoid having to manually upload the CSV, you can use Watershed’s CSV Data Import API to send the CSV data to Watershed automatically.

This guide outlines the allowed resources and methods of the CSV Data Import API. In order to interact with the CSV Data Import API, you will need authentication credentials and an organization id (org id).

Please note: you will be to create a template via the UI before importing CSVs either by API or UI. We don’t recommend creating templates via API as the UI includes helpful validation to ensure the template works.

It contains 4 sections:

Upload Data as a CSV

Request URL: /api/organizations/[org-id]/csv-import

Method: POST

Expected response code: 202 Accepted

Request headers

Header

Details

Content-Type

The content type for this request is multipart/form-data. The content type header should also include the boundary used in the request content. E.g. multipart/form-data; boundary=BOUNDARY

Please note: The boundary string used should be a string which does not occur within the csv file.

Request parameters

Parameter

Details

template

Name (or id) of the template to use for the import import.

 

Request content

The content of the request is multipart, but in fact only has one part which is text/csv. For example:

--BOUNDARY
Content-Disposition: form-data; name="file"; filename="name.csv"
Content-Type: text/csv

header A, header B
cell 1A, cell 1B
cell 2A, cell 2B

--BOUNDARY--

Response

A successful response contains no content.

Please note: No errors are returned so long as the csv file is uploaded succesful, even if there are problems with the contents of the CSV file. Errors are logged in Watershed’s CSV Data Import UI. To check a CSV for errors before uploading it, make a request to preview the file.

Preview a CSV Upload

The preview request is similar to the upload request except that it returns generated statements and any errors, instead of storing them in Watershed.

Request URL: /api/organizations/[org-id]/statement-import/preview

Method: POST

Expected response code: 200 OK

Request headers

Header

Details

Content-Type

The content type for this request is multipart/form-data. The content type header should also include the boundary used in the request content. E.g. multipart/form-data; boundary=BOUNDARY

 

Request parameters

Parameter

Details

template

Name (or id) of the template to use for the import import.

 

Request content

The content of the request is multipart, but in fact only has one part which is text/csv. For example:

--BOUNDARY--
Content-Disposition: form-data; name="file"; filename="name.csv"
Content-Type: text/csv

header A, header B
cell 1A, cell 1B
cell 2A, cell 2B

--BOUNDARY--

Response

A successful response contains an object with two properties, failedRows and statements. Both of these properties contain an object, the properties of which are strings named with the row numbers of failed or successful rows.

Within the failedRows object, the value of each property is an error message outlining the error encountered with that row. For example (line breaks added for clarity):

"failedRows": {
    "1388": "Statement must include an ID, and the ID must
    be a UUID. The current value of the field is: 
    some-invalid-id."
 }

Within the statements object, the value of each property is an array of xAPI statements generated by that row.

Please note: the header row counts as row 1 so normally the first successful or failed row will be row 2.

Fetch CSV Imports

Gets details of csvs that have been imported and not voided. This might be useful if you need to void an import via API. Where possible you should avoid voiding statements and should ensure that any data sent is new data since the last import, rather than replacing the full CSV every time.

Please note: the response to this request can be large if a large number of statements was generated.

Request URL: /api/organizations/[org-id]/csv-import

Method: GET

Expected response code: 200 OK

Request parameters

Parameter

Details

id

Id of the import to get. If not included all imports will be returned.

template

Name of template to filter by. Returns only those imports using this template.

 

Response

A successful response returns a collection object with count and results properties. The count property contains a count of the results. The results property contains an array of import objects, the properties of which are outlined in the table below.

Property

Details

id

Id of the import.

created

ISO 8602 timestamp of when the CSV was imported

version

Not necessary

size

Size of file?

originalFilename

The name of the file imported

file

The name of the file imported

mediaType

Always text/csv

hashFileName

 

userName

The full name of the user who uploaded the file.

statemenIds

A comma separated string listing the ids of all the statements generated by the import.

alllStatementIds

An array of ids of all the statements generated by the import.

failedRows

An object whose properties correspond to row numbers of rows that errored. The value of each property is the error generated for that row.

template

The name of the template used for the import

Void an Import

If a CSV has been uploaded in error or needs to be replaced by a newer version, it is possible to delete the import and void all statements created. If the file had groups information, voiding the file will remove any people, groups, and permissions created by the import, even if the information had been edited by a lter import. It won't revert any changes made to people and groups that previously existed.

Please note: voiding statements should normally be avoided on production environments and only correct CSVs containing new data should be uploaded. Integrations that routinely void large numbers of statements are strongly discouraged and can cause problems with reporting.

Request URL: /api/organizations/[org-id]/csv-import/[import-id]

Method: DELETE

Expected response code: 200 OK

Response

A successful responses returns no content.

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

If you can't find what you need or you want to ask a real person a question, please contact customer support.