Files

Close users wishing to attach files to outgoing emails or other objects via the Close API must first upload these files using the Files API.

Files will be uploaded to a Close-provided Amazon S3 bucket. The Close API provides the data needed to make a request to S3 to store your file.

To do so:

1. Make a POST request to /files/upload/ with the filename and content_type of the file you are uploading.
2. Use the data in the response to construct a multipart/form-data POST request: The request should be to the URL provided in the upload.url. All fields in the upload.fields object must be included in the form fields of the request. This request must be made within 60 seconds of your request to /files/upload, otherwise it will fail. See the AWS documentation for more information.
3. Once the upload request has been made successfully (201 HTTP status code), the file will be available for use in other API endpoints for at most 24 hours. The response from /files/upload will contain a download.url field, whose value should be used when referencing this file in other API endpoints. Note: attempting to use this file before the S3 upload request has been made successfully will result in a failed request to the Close API.

The below sample code can be used to make the request to S3. This example uses the requests library in Python.

from closeio_api import Client
import requests

api = Client("YOUR_API_KEY")
files_upload_response = api.post("files/upload", {
    "filename": "image.jpg",
    "content_type": "image/jpeg"
})

# Use the data in the response to construct a multipart/form-data POST request
s3_upload_response = requests.post(
    files_upload_response["upload"]["url"],
    data=files_upload_response["upload"]["fields"],
    files={
      "file": ("image.jpg", open("path/to/image.jpg", "rb"), "image/jpeg")
    }
)
assert s3_upload_response.status_code == 201

# The file will be available for use in other API endpoints, for example below
# when creating an email activity.
email_create_response = api.post("activity/email", data={
    "attachments": [{
        "url": files_upload_response["download"]["url"],
        "filename": "image.jpg",
        "size": 1108447,
        "content_type": "image/jpeg"
    }],
    "contact_id": "cont_8NNOJnVwmHQEYuVOgJ4B4zU7g9RUxYH4JnPjza5Vr6t",
    "lead_id": "lead_KwD00BYbXCHiPWj68LxFkxaeWuULpZ7awzm6LqeFs0h",
    "user_id": "user_scOgjLAQD6aBSJYBVhIeNr6FJDp8iDTug8Mv6VqYoFn",
    "direction": "outgoing",
    ...
})

Generate a signed S3 POST

POST /files/upload/

Get the data needed to make a request to S3 to store your file.