Cards & Attachments API: Get an attachment resource pre-signed URL

API endpoints for card management and file attachments

Get an attachment resource pre-signed URL

Allows you to create a pre-signed URL for the given attachment.

To obtain the attachment binary contents:

  • forward the user to the url returned from the getAttachmentPresignedUrl method (recommended if applicable)

  • capture the binary stream from the url returned from the getAttachmentPresignedUrl method

  • invoke this API preferencing the 'application/octet-stream' response

  • This method requires the Attachments:Get permission to be associated with your role.

Permissions

To run this API, the nominated 'web-services' role needs to be given permission.

If you are not actively using the API, leave the permission off for better security.

Go to Roles / Apis and check on Attachments:Get

HTTP Method

Use the HTTP Method 'GET' for consuming this web service.

URL Examples

https://api.demo.catch-e.com/authenticate
https://api..catch-e.com/authenticate
https://api.test.catch-e.com/gb/attachments/100000

Input Fields (Body)

JSON FieldFormatNotesMandatory
attchment_idIntAttachment IDYes
url_timeoutIntUrlNo

Input Fields (JSON)

{ attchment_id = 100000url_timeout = 300}

Successful Response Example

{ "url": "https://catch-e-client-assets.s3.ap-southeast-2.amazonaws.com/client/example/100000?X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ZKIBIA46LLA7H5KN5S4Q%2F20190201%2Fap-southeast- 2%2Fs3%2Faws4_request&X-Amz-Date=20190201T045824Z&X-Amz-SignedHeaders=host&X-Amz-Expires=300&X-Amz-Signature=6dcb136a7e0d285419ec8f88602785df41dc0036df8657bbc6e20309d3f3d5ba"}

Error Response Details

Validation MessagesComments
401 Unauthorized
{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Unauthorized", "status": 401, "detail": "Unauthorized"}|

| You have not authenticated before running this API or The token_timeout of the current session has passed. You need to authenticate again. |
| 404 - Not Found | | |

{ { "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Not Found", "status": 404, "detail": "Attachment object not found"}

| Missing attachment /Object not found |
| 403 - Forbidden | | |

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Forbidden", "status": 403, "detail": "Forbidden"}

| You do not have permissions for this request. Go to System Roles and enter 'web_services' Navigate to the Roles / APIs tab to make sure the permission you need to run this API is checked. |
| 422 - noRecordFound | | |

{ "validation_messages": { "attachment_id": { "noRecordFound": "No record matching the input was found" } }, "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Unprocessable Entity", "status": 422, "detail": "Failed Validation"}}

| No object available in the system |
| 500 - Internal Error | | |

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "string", "status": 0, "detail": "string"}

Save an attachment

This service allows you to save an attachment via the API rather than using the regular web-based attachment upload function.

Permissions

To run this API, the nominated 'web-services' role needs to be given permission.

If you are not actively using the API, leave the permission off for better security.

Go to Roles / Apis and check on Attachments:Save.

HTTP Method

Use the HTTP Method 'POST' for consuming this web service.

URL Examples

https://api.demo.catch-e.com/authenticate
https://api..catch-e.com/authenticate
https://api.test.catch-e.com/gb/attachments

Headers

KeyFormatNotesMandatory
Audit-User-IdstringPass a user_id here to create audit records with this user's details. This can only be done if the authenticated API user has Roles / Apis checked for the permission Audit:UserIdOverrideNo

Input Fields (Body)

JSON FieldFormatNotesMandatory
attachment_fileChoose fileAttach a fileYes
target_tableTextNominate the table name for the attachment. The available tables are bkbookingevents fmapprovals fmclientevents fmcontractevents (see also createContractEvents) fmdriverevents fmmaintenance fmsupplierevents qtquoteeventsYes
record_idTextThe unique (primary) id of the record in the target table the attachment is to be associated with.Yes
notesTextAdd notes to be stored with the attachmentNo

Successful Response Example

{ "attachment_id": "100348", "table_name": "fm_approvals", "record_id": 104256, "filename": "fm_apporovals", "extension": "csv", "md5": "79db7ccbfc353b8ed0f816f27c70792d", "file_size": 24, "notes": null, "user_id": "11065", "created": "2021-07-20T05:05:03Z", "duplicate_check": true, "status_flag": "active", "_links": { "self": { "href": "https://api.test.catch-e.com/gb/attachments/100348" } }}

Error Response Details

Validation MessagesComments
401 Unauthorized
{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Unauthorized", "status": 401, "detail": "Unauthorized"}|

| You have not authenticated before running this API or The token_timeout of the current session has passed. You need to authenticate again. |
| 404 - Not Found | | |

{ { "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Not Found", "status": 404, "detail": "Attachment object not found"}

| Missing attachment /Object not found |
| 422- Unsupported target table | | |

}, "target_table": { "notInArray": "Unsupported target table" },|

| Unsupported target table |
| 422- Unprocessable Entity | | |

{ "validation_messages": { "attachment_file": { "identicalAttachmentFile": The same file has already been attached to the associated record } }, "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Unprocessable Entity", "status": 422, "detail": "Failed Validation"}|

| "The same file has already been attached to the associated record". |
| 403 - Forbidden | | |

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Forbidden", "status": 403, "detail": "Forbidden"}

| You do not have permissions for this request. Go to System Roles and enter 'web_services' Navigate to the Roles / APIs tab to make sure the permission you need to run this API is checked. |
| 422 - uploaded file exceeds the maximum filesize | | |

{ "validation_messages": { "attachment_file": { "fileUploadMaxFileSize": "The uploaded file exceeds the maximum filesize of 10 bytes" } }, "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Unprocessable Entity", "status": 422, "detail": "Failed Validation"}|

| The uploaded file exceeds the maximum filesize |
| 422 - noRecordFound | | |

{ "validation_messages": { "attachment_id": { "noRecordFound": "No record matching the input was found" } }, "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Unprocessable Entity", "status": 422, "detail": "Failed Validation"}}

| No object available in the system |
| 500 - Internal Error | | |

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "string", "status": 0, "detail": "string"}

Delete an attachment

Allows you to delete an attchment.

Permissions

To run this API, the nominated 'web-services' role needs to be given permission.

If you are not actively using the API, leave the permission off for better security.

Go to Roles / Apis and check on Attachments:Delete

HTTP Method

Use the HTTP Method 'DELETE' for consuming this web service.

URL Examples

https://api.demo.catch-e.com/authenticate
https://api..catch-e.com/authenticate
https://api.test.catch-e.com/gb/attachments/100000

Input Fields (Body)

JSON FieldFormatNotesMandatory
attchment_idIntAttachment IDYes

Input Fields (JSON)

{ "contract_id": 100000, "inertia_flag": "no", "billing_interval": "monthly", "initial_billings": 0, "periodic_billings": 60, "payment_method": "direct-debit"}

Successful Response Example

{date: Thu, 15 Jul 2021 04:20:44 GMTserver: Apache/2.4.46 OpenSSL/1.0.2k-fipsvary: X-Forwarded-Proto}

Error Response Details

Validation MessagesComments
204 No Content
The request was successful request. No response is required
401 - Unauthorized
{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Unauthorized", "status": 401, "detail": "Unauthorized"}

| You have not authenticated before running this API or The token_timeout of the current session has passed. You need to authenticate again. |
| 403 - Forbidden | | |

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Forbidden", "status": 403, "detail": "Forbidden"}

| You do not have permissions for this request. Go to System Roles and enter 'web_services' Navigate to the Roles / APIs tab to make sure the permission you need to run this API is checked. |
| 422 - noRecordFound | | |

{ "validation_messages": { "attachment_id": { "noRecordFound": "No record matching the input was found" } }, "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Unprocessable Entity", "status": 422, "detail": "Failed Validation"}}

| No object available in the system |
| 500 - Unexpected error | | |

{ "status": 500, "title": "Unexpected error", "describedBy": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "detail": "JSON encoding error occurred: Malformed UTF-8 characters, possibly incorrectly encoded",}

| If a query has encrypted fields which are not decrypted using aes_decrypt in JSON response, below error is thrown. Please decrypt the fields in query before adding the query in table. |

Template Attachments

Emails can be set-up to contain template attachments.

This includes emails generated by scheduler mailQuery jobs.

You can attach one or multiple attachments.

Examples of suitable applications are as follows:

  • attaching an FBT Statutory Declaration to Novated Driver Reports at FBT year end
  • attaching an explanatory document to the Novated Driver login notification
  • attaching a finance application to a Novated Vehicle Quote
  • Using HTML to customise the email message when sending a quote (Note below)

Contact Catch-e support if you would like to have any attachments set up.

A technical description of the file structure is as follows:

Template reports are setup in the table gbtemplates. The table gbtemplateattachments is linked to gbtemplates via template_id.

This allows multiple static attachments to be included Contains as many static file attachments as you want per report.

The static document needs to be uploaded to the following folder:

/[client]/core/fleet/reports/attachments/

The table gbtemplateattachments has the following fields:

  • templateattachmentid - unique id
  • templateid - templateid from gb_templates
  • file - full name of file e.g. /clientname/core/fleet/reports/attachments/FBT_Declaration.pdf
  • status_flag - either 'active' or 'inactive'. If 'inactive' attachment ignored.

Each entry in this table represents one additional file attachment for the email. Multiple entries for a given template_id will result in multiple attachments.

Note: The email body when sending a quote email is linked to the Quote PDF document, e.g. the template may be named 'pdfquotenofb_lease'. Instructions for editing this template are:

  1. Use a docx file
  2. Change document as required and save (Catch-e will keep a copy in a project task)
  3. Save the document again with the format 'Web Page, Filtered'
  4. Open the resulting file in notepad and cut and paste the text into the message field in gb_templates for the required template.

GetSuppressedDestination

This API is used to check a specified email address is a suppressed destination.

Suppressed emails will bounce. See reporting details of this on the Mail Failed page.

Permissions

To run this API, the nominated 'web-services' role needs to be given permission.

If you are not actively using the API, leave the permission off for better security.

Go to Roles / Apis and check on Mail:SuppressedDestinationGet.

Input Fields (Header)

  • Header should contain the 'accept' Key with the Value = 'application/problem+json' or application/vnd.catch-e-api.v1+json.

Input Fields (Body)

JSON FieldFormatNotesMandatory
email_addressIntemail addressYes

URL Examples

https://api.test.catch-e.com/docs/#/Mail/getSuppressedDestination

Response Details

Validation MessagesComments
200
Email Address is suppressed
401 - Unauthorized
{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Unauthorized", "status": 401, "detail": "Unauthorized"}

| You have not authenticated before running this API or The token_timeout of the current session has passed. You need to authenticate again. |
| 403 - Forbidden | | |

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Forbidden", "status": 403, "detail": "Forbidden"}

| You do not have permissions for this request. Navigate to the Roles / APIs tab to make sure the permission you need to run this API is checked. |
| 404 - Email Address Not Found | | |

{ "validation_messages": { "message for this task } }, "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Unprocessable Entity", "status": 404, "detail": "Email Address Not Found"}

| 406 - Not Acceptable | | |

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Not Acceptable", "status": 406, "detail": "Not Acceptable"}

| 422 - Unprocessable Entity | | |

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Unprocessable Entity", "status": 422, "detail": "Unprocessable Entity"}

| 500 - Unexpected error | | |

{ "status": 500, "title": "Unexpected error", "describedBy": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "detail": "",}

DeleteSuppressedDestination

This API is used to remove an email address from the suppression list.

Suppressed emails will bounce. See reporting details of this on the Mail Failed page.

Permissions

To run this API, the nominated 'web-services' role needs to be given permission.

If you are not actively using the API, leave the permission off for better security.

Go to Roles / Apis and check on Mail:SuppressedDestinationDelete.

Input Fields (Header)

  • Header should contain the 'accept' Key with the Value = 'application/problem+json' or application/vnd.catch-e-api.v1+json.

Input Fields (Body)

JSON FieldFormatNotesMandatory
email_addressIntemail addressYes

URL Examples

https://api.test.catch-e.com/docs/#/Mail/deleteSuppressedDestination

Response Details

Validation MessagesComments
204 No Content
Email Address has been deleted from the suppression list
401 - Unauthorized
{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Unauthorized", "status": 401, "detail": "Unauthorized"}

| You have not authenticated before running this API or The token_timeout of the current session has passed. You need to authenticate again. |
| 403 - Forbidden | | |

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Forbidden", "status": 403, "detail": "Forbidden"}

| You do not have permissions for this request. Navigate to the Roles / APIs tab to make sure the permission you need to run this API is checked. |
| 404 - Email Address Not Found | | |

{ "validation_messages": { "message for this task } }, "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Unprocessable Entity", "status": 404, "detail": "Email Address Not Found"}

| 406 - Not Acceptable | | |

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Not Acceptable", "status": 406, "detail": "Not Acceptable"}

| 500 - Unexpected error | | |

{ "status": 500, "title": "Unexpected error", "describedBy": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "detail": "",}