Attachments

The API supports attachments on any attribute in the system via generic attachment endpoints. Additional endpoints are provided for working with attachments on documents.

• Generic Endpoints
• Document Endpoints

Attachment Groups

Attachments are typically created in a specific Attachment Group. The available Attachment Groups for a Document Type or Attribute can be queried as follows

• GET /api/DocumentType/{docTypeRef}/AttachmentGroup
  • docTypeRef = id or code of the document type
• GET /api/Attribute/{attributeRef}/AttachmentGroup
  • attributeRef = id or type name of the attribute

When creating or searching attachments the attachment group must be specified by id eg.

GET /api/Document/{docRef}/AttachmentGroup/b7881ec4-3372-47e4-97bc-bae1047b8c71/Attachment

The special value 'other' can be used in place of {attachmentGroupId} to work with attachments that are not in a specified group.

Create Attachments

Attachments can be added to a document using docRef and attachmentGroupId

• POST /api/Document/{docRef}/AttachmentGroup/{attachmentGroupId}/Attachment
  • docRef = id, doc_no or int_ref

or to an arbitrary source item using attributeRef, sourceId and attachmentGroupId

• POST /api/Attachment/create/{attributeRef}/{sourceId}/AttachmentGroup/{attachmentGroupId}
  • attributeRef = id or type_name

The attachment content must be sent as part of a multipart/form-data request body which may also optionally contain the description and document date.

Important

The maximum file size for attachments is 16MB.

Examples

POST /api/Document/{docRef}/AttachmentGroup/{attachmentGroupId}/Attachment
Content-Type: multipart/form-data; boundary=X-FORM-BOUNDARY

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

a,b,c,d
1,2,3,4
5,6,7,8
--X-FORM-BOUNDARY
Content-Disposition: form-data; name="description"

My attachment
--X-FORM-BOUNDARY
Content-Disposition: form-data; name="documentDate"

2023-01-01T00:00:00.000
--X-FORM-BOUNDARY--

POST /api/Document/{docRef}/AttachmentGroup/{attachmentGroupId}/Attachment
Content-Type: multipart/form-data; boundary=X-FORM-BOUNDARY

--X-FORM-BOUNDARY
Content-Disposition: form-data; name="file"; filename="PDF.pdf"
Content-Type: application/pdf

%PDF-1.7
%    
1 0 obj
[rest of byte contents of PDF.pdf]
--X-FORM-BOUNDARY--

POST /api/Document/{docRef}/AttachmentGroup/{attachmentGroupId}/Attachment
Content-Type: multipart/form-data; boundary=X-FORM-BOUNDARY

--X-FORM-BOUNDARY
Content-Disposition: form-data; name="file"; filename="Word.docx"
Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document

[byte contents of Word.docx]
--X-FORM-BOUNDARY--

Search Attachments

A list of existing attachments in a specific group (or in the 'other' group) can be retrieved for a document or arbitrary source item as follows

• GET /api/Document/{docRef}/AttachmentGroup/{attachmentGroupId}/Attachment
• GET /api/Attachment/search/{attributeRef}/{sourceId}/AttachmentGroup/{attachmentGroupId}

  [
    {
      "id": "1b1a0acc-0e2e-45a5-bcc1-c877b45cade8",
      "description": "Attachment Description",
      "documentDate": "2023-08-01T10:00:00",
      "createdBy": "username",
      "created": "2023-09-04T09:38:26.993",
      "fileName": "My Spreadsheet.xlsx",
      "fileSize": 8504
    },
    ...
  ]

Results can be filtered on created date and file name

• GET /api/Document/{docRef}/AttachmentGroup/{attachmentGroupId}/Attachment?createdFrom=2023-09-01
• GET /api/Attachment/search/{attributeRef}/{sourceId}/AttachmentGroup/{attachmentGroupId}?fileName=MyFile.pdf

Retrieve Attachment

A single attachment file can be retrieved by id via

• GET /api/Attachment/{attachmentId}/File

Meta data for a single attachment can be retrieved by id via

• GET /api/Attachment/{attachmentId}/Details

  {
    "id": "1b1a0acc-0e2e-45a5-bcc1-c877b45cade8",
    "description": "Attachment Description",
    "documentDate": "2023-08-01T10:00:00",
    "createdBy": "username",
    "created": "2023-09-04T09:38:26.993",
    "fileName": "My Spreadsheet.xlsx",
    "fileSize": 8504
  }

Update Attachment

Selected meta data fields of an existing attachment can be updated via

• PATCH /api/Attachment/{attachmentId}

  {
    "description": "New Description",
    "documentDate": "2023-08-01T10:00:00"
  }

Delete Attachment

An attachment can be deleted by id via

• DELETE /api/Attachment/{attachmentId}