Documents

When using the Metadata endpoint the only document types that can be uploaded are those for Tasks, Quotations/Estimates and Sites. For Invoices the process is detailed in the Create Invoice section. Other types will follow in a future update.

Documents are uploaded in a two-stage process.

1. First the document's metadata is uploaded (file name, size, mime type, etc)
2. This returns an unique identifier for that document.
3. This identifier is used to upload the raw bytes of the document

Upload Document Metadata

POST /documents/{tenant}/{type}/{identifier}

Details the properties used when adding document metadata to the platform. The URL type parameter must be one of task, site or quote and the identifier parameter is the task reference number.

Property	Notes
Filename	The original name of the file.
MimeType	The file's Mime Type
FolderPath	Optional, if the destination has folders then the path can be specified here, with each level separated by >. If not specified the file will be uploaded into the root. For a Task path only the folders are required, for a Site it must begin with the Site Name unless the folder is a Global Folder (indicated by a small globe icon) where it is just the path. See examples below. Not applicable for Quotations. All folder names can be found via the Web UI there is currently no method to retrieve them via the API.
ByteSize	The size of the document in bytes. The maximum size is determined on a tenant-by-tenant basis, although all tenants support at least 10MB documents.
DocumentCategories	The list of categories that should be applied to the document. The categories can be read using the Reference List endpoint and the document group. Most documents will require at least one category assigned however this is not application for Quotations.
Description	Optional, the file's description
ValidFrom	Optional, when the file is valid from

Request Examples

Quotations

Added through the /task/{tenant}/{identifier}/quotes method. The Identifier is the Task Reference.

{
  "AmountNet": 1000,
  "Notes": "Quote to install new unit",
  "FileMetadata": {
    "Filename": "AirCon_Quote_QA33.pdf",
    "ByteSize": 512000,
    "MimeType": "application/pdf"
  },
  "Description": "Test for Quotes",
  "ValidFrom": "2022-03-01"
}

Tasks

Added through the /documents/{tenant}/task/{identifier} method. The Identifier is the Task Reference.

{
  "Filename": "IMG_3394.png",
  "MimeType": "image/png",
  "ByteSize": 351534,
  "FolderPath": "Test Folder > Sub Folder",
  "DocumentCategories": [
    "General"
  ],
  "Description": "Test for Tasks",
  "ValidFrom": "2022-03-02"
}

Sites

Added through the /documents/{tenant}/site/{identifier} method. The Identifier is the Site Code.

{
  "Filename": "IMG_3395.png",
  "MimeType": "image/png",
  "ByteSize": 351534,
  "FolderPath": "Test Site Name > Test Folder > Sub Folder",
  "DocumentCategories": [
    "General"
  ],
  "Description": "Test for Sites",
  "ValidFrom": "2022-03-03"
}

{
  "Filename": "IMG_3395.png",
  "MimeType": "image/png",
  "ByteSize": 351534,
  "FolderPath": "Test Global Folder > Sub Global Folder",
  "DocumentCategories": [
    "General"
  ],
  "Description": "Test for Sites",
  "ValidFrom": "2022-03-03"
}

A list of categories can be read using the Reference List method passing in document as the type parameter

Response Examples

Success

{
    "DocumentIdentifier": "75017e93-bfea-420a-90a6-b0bc00ac0011",
    "Messages": []
}

Failure

{
    "DocumentIdentifier": null,
    "Messages": [
        {
            "Key": "BrokenRule_DocumentLibrary_FileAlreadyExists",
            "Value": "A document UrgentTaskDocument.docx already exists in this folder."
        }
    ]
}

Upload Document

POST /documents/{tenant}/{identifier}

To upload the actual document you've received the meta data for before you must user the Document Identifier returned from the Meta Data endpoint in the URL as the {identifier} value. The Document itself must be sent as a Binary stream within the request body.

Response Examples

Success

{
    "Messages": []
}

Failure

{
    "Messages": [
        {
            "Key": "BrokenRule_DocumentLibrary_FileDoesntExist",
            "Value": "The file does not exist"
        }
    ]
}

Download Document

GET /documents/{tenant}/{documentIdentifier}

This method downloads the binary of the specified document if you have the correct permissions. The documentIdentifier variable is the identifying variable returned from the Meta Data stage of the document upload process.