Introduction

The Document API provides mechanisms to upload and manage files in Performio.

Document Resources

Import Files

Import Files are wrappers around uploaded files that are to be imported into Performio via an Import File Type (Standard or Custom). Once created, an Import File coupled with an Import File Type can be used to create an Import Errand, which will trigger the actual import of data.

POST /zuul/document/v1/import-files

Please note the /zuul prefix for this endpoint. If you do not provide it, your file upload will fail.

Utilise this endpoint to create an Import File by uploading a file.

Requests are multipart form data (multipart/form-data). Responses are JSON (application/json).

Request

$ curl 'https://gateway-domain.performio.co/gateway/zuul/document/v1/import-files' -i -X POST \
    -H 'Content-Type: multipart/form-data' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer e9036e38-d67e-11e8-9f8b-f2801f1b9fd1' \
    -F 'file=@/path/document-to-upload.json' \
    -F 'filename=test-file.json' \
    -F 'skipMD5=true' \
    -F 'errandId=1'
Headers
Name Description

Authorization

OAuth 2.0 authentication token
Parameters
Part Description

file

Object representing the multipart file to be uploaded.
Parameter Description

skipMD5

Boolean representing whether to skip MD5 digest generation for the Import File.

filename

(Optional) String representing an override for the uploaded file’s filename.

errandId

(Optional) Number representing the ID of a pre-created Import Errand. If provided, the Import File will be processed immediately.

Response

HTTP/1.1 201 Created
Content-Type: application/json;charset=UTF-8
Content-Length: 243

{
  "id" : 1,
  "filename" : "ParticipantSourceData.xlsx",
  "fileSize" : 22800082,
  "uploadedTimestamp" : 1539922402211,
  "md5Digest" : "2a6ea13d0e18b1718042998d3172a1bf",
  "type" : null,
  "imported" : false,
  "duplicateUpload" : false
}
Path Type Description

id

Number

Number representing the ID of the Import File. Utilised when creating Import Errands to indicate which Import File to import.

filename

String

String representing the filename of Import File.

fileSize

Number

Number representing the file size Import File in bytes

uploadedTimestamp

Number

Number representing the timestamp for when the Import File was uploaded.

md5Digest

Varies

String representing an MD5 digest of the uploaded file, Null if skipMD5 set to true in during upload.

type

Varies

String representing the Import File Type if the Import File has been imported, Null if it has not been imported.

imported

Boolean

Boolean representing if the Import File has been imported.

duplicateUpload

Boolean

Boolean representing if the the Import File is a duplicate of another Import File.

Error Conditions

Reason

Response

A required parameter is missing from the request.

 
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Content-Length: 179

{
  "timestamp" : 1617843928034,
  "status" : 400,
  "error" : "Bad Request",
  "message" : "Required request part 'file' is not present",
  "path" : "/document/v1/import-files"
}

Errand ID provided does not resolve to an Import Errand.

 
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Content-Length: 172

{
  "timestamp" : 1617843928408,
  "status" : 404,
  "error" : "Not Found",
  "message" : "Could not find Import Errand with ID 1",
  "path" : "/document/v1/import-files"
}

Due to an internal issue with file storage the uploaded file could not be saved.

 
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
Content-Length: 218

{
  "timestamp" : 1617843928148,
  "status" : 500,
  "error" : "Internal Server Error",
  "message" : "Error while creating Import File with name /path/document-to-upload.json",
  "path" : "/document/v1/import-files"
}

GET /document/v1/import-files

Utilise this endpoint to retrieve all Import Files. Results are paginated.

Responses are JSON (application/json).

Request

$ curl 'https://gateway-domain.performio.co/gateway/document/v1/import-files?page=0&size=20' -i -X GET \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer e9036e38-d67e-11e8-9f8b-f2801f1b9fd1'
Headers
Name Description

Authorization

OAuth 2.0 authentication token
Request Parameters
Parameter Description

page

(Optional) Number representing the page to retrieve. Pages start from 0.

size

(Optional) Number representing the records per page count. Default page size is 20 and the maximum is 2000.

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 633

{
  "results" : [ {
    "id" : 1,
    "filename" : "ParticipantSourceData.xlsx",
    "fileSize" : 22800082,
    "uploadedTimestamp" : 1539922402211,
    "md5Digest" : "2a6ea13d0e18b1718042998d3172a1bf",
    "type" : null,
    "imported" : false,
    "duplicateUpload" : false
  }, {
    "id" : 2,
    "filename" : "ParticipantSourceData.xlsx",
    "fileSize" : 22800082,
    "uploadedTimestamp" : 1539922402211,
    "md5Digest" : "2a6ea13d0e18b1718042998d3172a1bf",
    "type" : null,
    "imported" : false,
    "duplicateUpload" : false
  } ],
  "page" : {
    "totalPages" : 1,
    "totalElements" : 2,
    "hasNext" : false
  }
}
Path Type Description

results.[].id

Number

Number representing the ID of the Import File. Utilised when creating Import Errands to indicate which Import File to import.

results.[].filename

String

String representing the filename of Import File.

results.[].fileSize

Number

Number representing the file size Import File in bytes

results.[].uploadedTimestamp

Number

Number representing the timestamp for when the Import File was uploaded.

results.[].md5Digest

Varies

String representing an MD5 digest of the uploaded file, Null if skipMD5 set to true in during upload.

results.[].type

Varies

String representing the Import File Type if the Import File has been imported, Null if it has not been imported.

results.[].imported

Boolean

Boolean representing if the Import File has been imported.

results.[].duplicateUpload

Boolean

Boolean representing if the the Import File is a duplicate of another Import File.

page

Object

Object representing result pagination.

page.totalPages

Number

Number representing the total pages at current page size.

page.totalElements

Number

Number representing the total possible elements for the request.

page.hasNext

Boolean

Boolean representing if there is a next page of results.

GET /document/v1/import-files/{importFileId}

Utilise this endpoint to retrieve a specific Import File.

Responses are JSON (application/json).

Request

$ curl 'https://gateway-domain.performio.co/gateway/document/v1/import-files/1' -i -X GET \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer e9036e38-d67e-11e8-9f8b-f2801f1b9fd1'
Headers
Name Description

Authorization

OAuth 2.0 authentication token
Parameters
Parameter Description

importFileId

Number representing the ID of the Import File to fetch.

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 243

{
  "id" : 1,
  "filename" : "ParticipantSourceData.xlsx",
  "fileSize" : 22800082,
  "uploadedTimestamp" : 1539922402211,
  "md5Digest" : "2a6ea13d0e18b1718042998d3172a1bf",
  "type" : null,
  "imported" : false,
  "duplicateUpload" : false
}
Path Type Description

id

Number

Number representing the ID of the Import File. Utilised when creating Import Errands to indicate which Import File to import.

filename

String

String representing the filename of Import File.

fileSize

Number

Number representing the file size Import File in bytes

uploadedTimestamp

Number

Number representing the timestamp for when the Import File was uploaded.

md5Digest

Varies

String representing an MD5 digest of the uploaded file, Null if skipMD5 set to true in during upload.

type

Varies

String representing the Import File Type if the Import File has been imported, Null if it has not been imported.

imported

Boolean

Boolean representing if the Import File has been imported.

duplicateUpload

Boolean

Boolean representing if the the Import File is a duplicate of another Import File.

Error Conditions

Reason

Response

Import File ID provided does not resolve to an Import File.

 
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Content-Length: 172

{
  "timestamp" : 1617843928299,
  "status" : 404,
  "error" : "Not Found",
  "message" : "Could not find Import File with ID 1",
  "path" : "/document/v1/import-files/1"
}

GET /document/v1/import-files/{importFileId}/contents

Utilise this endpoint to retrieve the contents of a specific Import File.

Responses are streamed (application/octet-stream).

Request

$ curl 'https://gateway-domain.performio.co/gateway/document/v1/import-files/1/contents' -i -X GET \
    -H 'Accept: application/octet-stream' \
    -H 'Authorization: Bearer e9036e38-d67e-11e8-9f8b-f2801f1b9fd1'
Headers
Name Description

Authorization

OAuth 2.0 authentication token
Parameters
Parameter Description

importFileId

Number representing the ID of the Import File to fetch.

Response

HTTP/1.1 200 OK
Content-Length: 115
Content-Type: application/octet-stream
Content-Disposition: attachment; filename="ParticipantSourceData.xlsx"
Accept-Ranges: bytes

participant, period, client, total
exampleUser, 1, acme, 1000
exampleUser, 2, acme, 1500
exampleUser, 3, acme, 1200