---
title: Files
subtitle: Upload files to attach to outgoing emails or other objects via the API.
---

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](https://aws.amazon.com/pm/serv-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](https://docs.aws.amazon.com/AmazonS3/latest/API/sigv4-HTTPPOSTForms.html) 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.
```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_xxx",
    "lead_id": "lead_xxx",
    "user_id": "user_xxx",
    "direction": "outgoing",
    ...
})
```