Uploading data using flat files

The /uploads/files end point allows you to import data into Betterez from external systems.

At the moment you can upload data for the 'employee-pass' and 'pay-on-account' payment methods.

You can find templates of those files in the back-end of your Betterez system.

Other file types may be available at a later date.

Requirements

You will need a X-API-KEY and JWT token.

A note on encoding

Make sure your files are saved with UTF-8 encoding.

If you use Excel to create your files, make sure to save as a flat CSV file and that the proper encoding is used. A common source of errors come from saving the files with other encoding.

This is specially important if you are using extended characters, very common on languages other than English.

Uploading the file

You will POST a file indicating the file type:

curl --request POST 
 --header "x-api-key: {{x-api-key}}"
 --header 'authorization: Bearer {{jwt-token}}'
 -F "cbType=email"
 -F "cbValue=mail@example.com"
 -F "type=pay-on-account"
 -F "file=@./pay_on_account_template.csv" https://api.betterez.com/uploads/files

If the request is successful you will receive a response that looks like this:

{
  "originalFilename": "pay_on_account_template.csv",
  "bucket": "btrz-uploads-sandbox",
  "s3object": "b0ce8560-c00a-11e7-9b5f-chakdsasd.txt",
  "s3Url": "https://s3.amazonaws.com/btrz-uploads-sandbox/b0ce8560-c00a-11e7-9b5f-chakdsasd.txt",
  "uploaded": "2017-11-02T20:16:20.662Z",
  "accountId": "{{THIS WILL BE YOUR ACCOUNT ID}}",
  "inQueue": true,
  "columnDelimiter": ",",
  "cbType": "email",
  "cbValue": "mail@example.com",
  "type": "pay-on-account",
  "_id": "59fb7d14f5001b8b0f96c919"
}

How to know if the file was processed properly

You can provide a call back type and value to be notified on the progress of the upload job.

The cbType and cbValue parameters are non mandatory.

The only cbType accepted at the moment is 'email' and the cbValue needs to be a valid email address.

If cbType is provided a valid email needs to be provided as well for cbValue.

The system will use that email to send a confirmation email once the file is processed indicating the number of lines read, the number of successfully processed lines and the number of errors.

In most cases the system will return details for the errors as well.