File Upload API

The Democrance platform permits bulk upload data via CSV and XLSX files.

An authenticated user, with apropriate permissions set, will be able to upload a file via an upload endpoint. This will return a task handle, which is used to monitor the status of the upload, and retrieve any import errors that may have occurred.

There are different types of files that can be uploaded, including customer lists and policy lists. The layout of the file is generally agreed upon as part of the integration between your company and the democrance platform. It will be often customised for a particular configuration or deployment.

These API’s can be seen in action by logging into the admin panel (https://your-democrance-instance.com/admin). Go to the ‘Import customer CSV’ or ‘Import policy CSV’ sections and observe the requests/responses there in real time using the developer tools of your favourite browser.

Some sample files are included for download from these respective admin panel pages. Note that these file layouts may change between democrance instances, should a different layout be agreed upon for your installation.

Authentication

Prior to using the API upload endpoints, you will be required to authenticate. API endpoints require you to be a registered user with a username and password.

Refer to User Login and Initiating a session for details on how to login and maintain a session for your API calls.

Policy File Upload

URL	/api/v1/policy/upload
Methods	POST

Submit a multipart form with a single xls or csv file attached.

Example headers:

"Content-Type": "multipart/form-data",
"Cookie": "sessionid=12341234123412341234"

Example Form Data:

"Content-Disposition": "form-data",
"name": "file",
"filename": "policy_template1.csv"

This will respond with a task UUID which you can use with the File Upload Status call described below.

{
    "task_uuid": "459001b6-2c0f-4d6f-8945-84612fa6d161"
}

Customer File Upload

URL	/api/v1/customer/upload
Methods	POST

Submit a multipart form with a single xls or csv file attached with the input name as ‘file’.

Example headers:

"Content-Type": "multipart/form-data",
"Cookie": "sessionid=12341234123412341234"

Example Form Data:

"Content-Disposition": "form-data",
"name": "file",
"filename": "customer_template1.csv"

This will respond with a task UUID which you can use with the File Upload Status call described below.

{
    "task_uuid": "459001b6-2c0f-4d6f-8945-84612fa6d161"
}

File Upload Status

URL	/api/v1/celery/UUID/
Methods	GET

This endpoint fetches information on the status of a submitted task, based on the UUID returned from one of the file upload endpoints.

The variable to watch for in the responses is ‘status’, as this will inform you of progress.

Status can be one of:

PENDING	Task has not started yet
STARTED	Task has been started
SUCCESS	Completed without errors
FAILURE	Completed with errors

The remaining variables are:

failed_rows	Number of rows that failed to process
header_errors	Description of errors in the csv header that describes the columns
messages	List of human readable feedback with warnings or errors, limited to the first 100 messages
processed_rows	Rows processed successfully
total_rows	Total rows found

Here are some example responses from the API in various states:

{
    "failed_rows": 0,
    "header_errors": null,
    "messages": [],
    "status": "PENDING",
    "processed_rows": 0,
    "total_rows": null
}

A successful upload:

{
   "failed_rows": 0,
   "header_errors": null,
   "messages": [],
   "status": "SUCCESS",
   "processed_rows": 1,
   "total_rows": 1
}

A failed upload:

{
    "failed_rows": 0,
    "header_errors": null,
    "messages": [],
    "status": "FAILURE",
    "processed_rows": 0,
    "total_rows": 1
}