Create attachment ^ALPHA

Description #

Creates or updates an attachment for future use as an attachment to a calendar event.

These are uploaded first via this API, and then available to be attached to an event.

URL format #

{data_center_url}/v1/attachments

Example Request #

POST /v1/attachments HTTP/1.1
Host: {data_center_url}
Authorization: Bearer {API_KEY}
Content-Type: application/json; charset=utf-8

{
  "attachment": {
    "file_name": "job_description.pdf",
    "content_type": "application/pdf",
    "base64_content": "TmV2ZXIgZ29ubmEgZ2l2ZSB5b3UgdXAK..."
  },
  "subscriptions": [
    {
      "type": "webhook",
      "uri": "https://example.com/customer_123/webhooks",
      "interactions": [
        { "type": "attachment_approved" },
        { "type": "attachment_rejected" },
      ]
    }
  ]
}

Example Response #

HTTP/1.1 200 Success

{
    "attachment": {
        "attachment_id": "att_5e4d5a6668ed0f4b213e90fe",
        "file_name": "my-file.pdf",
        "content_type": "application/pdf",
        "md5": "344aab9758bb0d018b93739e7893fb3a"
    }
}

Request parameters #

attachment required  #

Object describing the Attachment.

attachment.file_name required  #

The file name to be used when attached to an event.

Please note that the file extension must be in the list expected for the content type. For example, application/pdf will require the filename to end in .pdf.

Also, to maximise compatibility, we restrict the characters usable in the file name. If you believe a name should be valid but isn’t, please contact support@cronofy.com.

attachment.content_type required  #

The MIME type for the attachment. This must match the file extension.

Note this is the Content-Type for the attachment part of the request. The Content-Type for the overall request must be application/json.

Supported content types

attachment.base64_content required  #

A base64 representation of the file. This can be up to 2 MB to comply with calendar server limits.

Example base64 conversion code #

base64_value = Base64.urlsafe_encode64(
  File.read("docs/attachment.pdf", binmode: true)
)

let base64Value = new FileReader().readAsDataURL("docs/attachment.pdf");

import base64

with open("docs/attachment.pdf", "rb") as file:
    base64_value = base64.b64encode(file.read())

$data = file_get_contents('docs/attachment.pdf');
$base64_value = base64_encode($data);

Byte[] bytes = File.ReadAllBytes("docs/attachment.pdf");
String file = Convert.ToBase64String(bytes);

subscriptions optional  #

Attachments are be virus scanned by Cronofy before being synced to calendars. Subscriptions can be used to receive a callback to the status of an attachment.

Any events created while an attachment is being scanned will be held for up to 10 seconds to see if the file is approved. If the file is rejected or not approved in this time, the event will be written to the calendar without the attachment. Generally this is desirable to hold the time, and Cronofy will update the event with the attachment when it is approved.

However this may not be desirable for events with large numbers of attendees, as the late addition of the attachment will trigger an update to the event and email all of the attendees.

To avoid this, you can subscribe to the attachment_approved and attachment_rejected events and only call create event once the attachment has been approved.

subscriptions[].type optional  #

Only one value of webhook is supported at present.

subscriptions[].uri optional  #

The URI within your application you want Cronofy to send notifications to when the interaction is triggered. Must be an externally accessible HTTP or HTTPS URI.

subscriptions[].interactions optional  #

An array of interactions that should trigger a call to the uri.

subscriptions[].interactions[].type optional  #

The following interaction subscriptions are supported:

• attachment_approved - the attachment has passed all checks and is ready to be included on events.
• attachment_rejected - the attachment has failed a check. The request will include a body describing the failure.

Response Parameters #

attachment.attachment_id  #

The ID which has been assigned to this attachment. Unlike the majority of our APIs, Cronofy provides the ID for attachments to make it clearer that Attachments are not upserted.

attachment.file_name  #

The file name which will appear on events when the attachment is included.

attachment.content_type  #

The content type of the attachment.

attachment.md5  #

The MD5 hash of the file stored. This can be compared with an MD5 of your file to spot any issues with the upload.