---
updatedAt: 2026-01-28T13:42:55.000Z
---

Fetch the complete documentation index at: https://developer.connecteam.com/llms.txt. Use this file to discover all available pages before exploring further.

# Upload file to the Cloud

This guide walks you through securely uploading files to Connecteam's cloud storage using the Attachments API.

## Upload Flow Overview

```
1. Generate Upload URL  →  Get fileId + pre-signed URL
2. Upload File          →  PUT file to pre-signed URL
3. Complete Upload      →  Finalize with fileId
4. (Optional) Get Metadata  →  Verify upload status
```

> ⚠️ Time Limit
>
> The pre-signed URL expires in **300 seconds** (5 minutes). Complete all steps within this window or generate a new URL.

***

## Step 1: Generate Upload URL

Request a pre-signed URL for secure file upload.

**Endpoint**: `POST /attachments/v1/files/generate-upload-url`

### Request Body

| Field        | Type   | Required | Description                                       |
| :----------- | :----- | :------- | :------------------------------------------------ |
| fileName     | string | Yes      | Name of the file to upload                        |
| fileTypeHint | string | No       | MIME type (e.g., `image/jpeg`, `application/pdf`) |
| featureType  | string | Yes      | Target feature for the attachment                 |

### Feature Types

| Value            | Use Case                                |
| :--------------- | :-------------------------------------- |
| `chat`           | Chat messages and conversations         |
| `shiftscheduler` | Shift scheduler notes/attachments       |
| `users`          | User documents (payslips, certificates) |
| `quicktasks`     | Quick task attachments                  |

> 📝 MIME Type Detection
>
> If `fileTypeHint` is not provided, the API will attempt to detect the MIME type from the file extension. If detection fails, the request will return an error.

### Example Request

```bash
curl --request POST \
  --url https://api.connecteam.com/attachments/v1/files/generate-upload-url \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '{
    "fileName": "report.pdf",
    "fileTypeHint": "application/pdf",
    "featureType": "chat"
  }'
```

### Response

```json
{
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "fileId": "f8e7d6c5-b4a3-2109-8765-43210fedcba9",
    "uploadFileUrl": "https://s3.amazonaws.com/bucket/path?X-Amz-Algorithm=..."
  }
}
```

### Response Fields

| Field         | Type   | Description                                    |
| :------------ | :----- | :--------------------------------------------- |
| fileId        | string | Unique identifier for tracking the upload      |
| uploadFileUrl | string | Pre-signed URL for uploading (expires in 300s) |

***

## Step 2: Upload Your File

Upload the file directly to the pre-signed URL using a PUT request.

> 🚨 Important
>
> * Use the **exact URL** from the response (including query parameters)
> * Set `Content-Type` header to match your file's MIME type
> * This request goes directly to cloud storage, not the Connecteam API

### Example Request

```bash
curl --request PUT \
  --url 'https://s3.amazonaws.com/bucket/path?X-Amz-Algorithm=...' \
  --header 'Content-Type: application/pdf' \
  --data-binary @/path/to/your/report.pdf
```

### For Images

```bash
curl --request PUT \
  --url 'https://s3.amazonaws.com/bucket/path?X-Amz-Algorithm=...' \
  --header 'Content-Type: image/jpeg' \
  --data-binary @/path/to/photo.jpg
```

***

## Step 3: Complete Upload

Finalize the upload to register the file in Connecteam.

**Endpoint**: `PUT /attachments/v1/files/complete-upload/{fileId}`

### Path Parameters

| Parameter | Type   | Required | Description             |
| :-------- | :----- | :------- | :---------------------- |
| fileId    | string | Yes      | The file ID from Step 1 |

### Example Request

```bash
curl --request PUT \
  --url https://api.connecteam.com/attachments/v1/files/complete-upload/f8e7d6c5-b4a3-2109-8765-43210fedcba9 \
  --header 'X-API-KEY: YOUR_API_KEY'
```

### Response

```json
{
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "fileId": "f8e7d6c5-b4a3-2109-8765-43210fedcba9"
  }
}
```

***

## Step 4: Get File Metadata (Optional)

Verify the upload status and retrieve file information.

**Endpoint**: `GET /attachments/v1/files/{fileId}`

### Example Request

```bash
curl --request GET \
  --url https://api.connecteam.com/attachments/v1/files/f8e7d6c5-b4a3-2109-8765-43210fedcba9 \
  --header 'X-API-KEY: YOUR_API_KEY'
```

### Response

```json
{
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "fileId": "f8e7d6c5-b4a3-2109-8765-43210fedcba9",
    "fileUrl": "https://cdn.connecteam.com/bucket/path/report.pdf",
    "uploadCompleted": true,
    "fileType": "application/pdf",
    "featureType": "chat"
  }
}
```

### Response Fields

| Field           | Type    | Description                                                   |
| :-------------- | :------ | :------------------------------------------------------------ |
| fileId          | string  | Unique file identifier                                        |
| fileUrl         | string  | CDN URL for accessing the file (null if upload not completed) |
| uploadCompleted | boolean | Whether the upload has been finalized                         |
| fileType        | string  | MIME type of the file                                         |
| featureType     | string  | Feature the file is associated with                           |

***

## Error Responses

### Generate Upload URL Errors

| Error                                 | Cause                                                |
| :------------------------------------ | :--------------------------------------------------- |
| `Unsupported attachment feature type` | Invalid featureType value                            |
| `Could not identify file type`        | Missing fileTypeHint and unrecognized file extension |
| `Invalid file type hint`              | fileTypeHint is not a valid MIME type                |

### Complete Upload Errors

| Error                                                     | Cause                                          |
| :-------------------------------------------------------- | :--------------------------------------------- |
| `File ID not found`                                       | Invalid or expired fileId                      |
| `File not found in storage, upload the file`              | File was not uploaded to the pre-signed URL    |
| `File size is too big, file got deleted`                  | File exceeds 1 GB limit                        |
| `File already set as upload completed`                    | complete-upload already called for this fileId |
| `File type is not the same as declared, file got deleted` | Uploaded file type doesn't match declared type |

***

## Using the File ID

Once upload is complete, use the `fileId` in other API calls that accept attachments:

* **Chat**: Send messages with attachments
* **Users**: Upload payslips or documents
* **Tasks**: Attach files to quick tasks
* **Scheduler**: Add notes with attachments

***

[API Reference](https://developer.connecteam.com/reference/)