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

Feature Types

📝

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

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

{
  "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

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

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

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

Example Request

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

{
  "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

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

Response

{
  "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

Error Responses

Generate Upload URL Errors

Complete Upload Errors

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