Toggl Track Connector

Overview

The Toggl Track connector allows you to sync Excel data directly to your Toggl workspace:

Connector capacity and add-on packs
Toggl uses one connector slot and consumes connector data-transfer balance when you sync records. Add-on packs can extend either limit without changing your main subscription, which is useful for ongoing sync work, larger import periods, or Free-plan accounts that need targeted connector capacity.

• Clients: Create and update client records
• Projects: Create and update project records
• Tags: Sync tags used by time entries
• Time Entries: Import and update tracked work
• Tasks: Work with project tasks
• Workspace Users: Review and update workspace-user settings

This guide starts with the Clients workflow because it is the simplest first-time setup. The same connection can also be used for the other verified Toggl endpoints listed above.

Prerequisites

Before connecting:

1. Toggl Account: You need an active Toggl Track account
2. API Token: Generate your personal API token from Toggl
3. Workspace ID: Know which workspace you want to sync to

Getting Your Toggl Credentials

Step 1: Get Your API Token

1. Log in to Toggl Track
2. Click your profile icon (bottom left)
3. Click Profile Settings
4. Scroll to API Token section
5. Click Click to reveal to show your token
6. Copy the token (looks like: 1234567890abcdef1234567890abcdef)

Security: Keep your API token secret - it gives full access to your Toggl account.

Step 2: Get Your Workspace ID

Option A: From URL

1. Go to your Toggl workspace
2. Look at the URL: https://track.toggl.com/timer/w/1234567
3. The number after /w/ is your workspace ID (1234567)

Option B: From API

1. Use the test connection feature in the add-in
2. It will show available workspaces if ID is wrong

Setting Up the Connection

1. Select Toggl Connector

In the ExForms add-in:

1. Click Other Destinations tab
2. Expand Project Management category
3. Click Toggl Track

2. Configure Connection

Fill in the configuration form:

3. Test Connection

1. Click Test Connection
2. Wait for verification (2-3 seconds)
3. Success message: "Connection to Toggl Track is working correctly"
4. Status indicator turns green ✅

If test fails:

• Verify API token is correct
• Verify workspace ID is correct
• Check internet connection

4. Save Connection

1. Click Save
2. Connection appears in Saved Connections list
3. Status shows ✅ Connected

Syncing Clients to Toggl

Quick Start: Auto-Map (Fastest Method)

The fastest way to get started is to use Auto-Map, which automatically creates Excel tables and field mappings for you:

Method 1: Auto-Map from Connection Setup

1. After saving your connection, you'll see unmapped endpoints
2. Click Auto-Map Endpoints button
3. Select which endpoints to map (e.g., "Clients")
4. Click Create Tables & Map
5. Done! Excel tables are created with the correct column names AND mappings are saved

What Auto-Map Does:

• ✅ Creates a new Excel sheet named "Clients" (or similar)
• ✅ Creates an Excel table with columns: name, notes
• ✅ Automatically maps table columns to Toggl fields
• ✅ Saves the mapping to the server
• ✅ Ready to sync immediately

Method 2: Auto-Map from "Add New Mapping"

1. Click Add New Mapping in Table Mappings view
2. If all Excel tables are already mapped, you'll see a dialog
3. Dialog shows unmapped endpoints and asks: "Would you like to Auto-Map?"
4. Click Auto-Map Endpoints
5. Tables and mappings are created automatically

Result: You can immediately add data to the Excel table and sync!

Manual Setup: Prepare Your Excel Data

If you prefer to create your own Excel structure:

Option A: Excel Table

| name               | notes                           |
|--------------------|---------------------------------|
| Acme Corporation   | Main client - monthly retainer  |
| TechStartup Inc    | Hourly billing                  |
| Local Nonprofit    | Pro bono work                   |

Option B: Named Ranges

• Create Named Range: name → "Acme Corporation"
• Create Named Range: notes → "Main client - monthly retainer"

💡 Tip: If you name your Excel columns/ranges to match Toggl field names (name, notes), field mapping becomes automatic!

Manual Field Mapping

Note: If you used Auto-Map, this is already done! Only follow these steps if you're creating custom mappings.

1. From Saved Connections, click Map Fields next to your Toggl connection
2. The mapping screen shows:

Destination Fields (Toggl):

• name (required) - Client name
• notes (optional) - Client notes

Your Excel Sources:

• Select which Excel table column or named range maps to each field

Example Mapping:

Or if using a table:

3. Click Save Mapping

Choose Sync Mode

For first-time sync: Use Insert mode

• Creates new clients
• Errors if client already exists

For regular updates: Use Upsert mode

• Creates new clients
• Updates existing clients by name
• Most flexible option

Sync Your Data

1. Click Sync Data next to your Toggl connection
2. Select Sync Mode: Upsert (recommended)
3. Review the preview showing what will be sent
4. Click Send

Review Results

After sync completes:

✅ 3 clients synced successfully
  - Created: 2 clients
  - Updated: 1 client
  
❌ 0 errors

If errors occur, they'll show:

❌ 1 error
  - Row 2: Client name is required

Excel Setup Examples

Example 1: Simple Named Ranges

Excel Setup:

1. Cell A1: "Acme Corporation"
2. Define Name: ClientName = $A$1
3. Cell B1: "Main client"
4. Define Name: ClientNotes = $B$1

Mapping:

• Toggl name ← Excel ClientName
• Toggl notes ← Excel ClientNotes

Result: Syncs one client at a time (change cell values and re-sync)

Example 2: Excel Table (Bulk Sync)

Excel Setup:

1. Create table with columns:
   • Column A: "Client Name"
   • Column B: "Notes"
2. Add multiple rows of data
3. Insert → Table → Name it "Clients"

Mapping:

• Toggl name ← Table Clients Column Client Name
• Toggl notes ← Table Clients Column Notes

Result: Syncs all table rows at once

Example 3: Auto-Map (Recommended for New Users)

Setup:

1. Connect to Toggl
2. Click Auto-Map Endpoints or use Auto-Map from "Add New Mapping" dialog
3. Select "Clients" endpoint
4. Click Create Tables & Map

What Happens:

1. New sheet created: "Clients"
2. Excel table created with columns: name, notes
3. Table-to-endpoint mapping saved automatically
4. Ready to enter data and sync!

Result: Fastest setup - zero manual configuration needed

Field Specifications

Client Name (required)

Field: name
Type: Text
Max Length: 255 characters
Rules:

• Cannot be empty
• Must be unique within workspace
• Trimmed of leading/trailing spaces

Excel Examples:

✅ "Acme Corporation"
✅ "TechStartup Inc."
❌ "" (empty - will error)
❌ "  " (whitespace only - will error)

Client Notes (optional)

Field: notes
Type: Text
Max Length: 5000 characters
Rules:

• Can be empty
• Plain text only (no HTML)

Excel Examples:

✅ "Monthly retainer client"
✅ "" (empty is OK)
✅ "Client since 2020\nPrefers email communication"

Sync Modes for Clients

Insert Mode

When to use: First-time import of clients

Behavior:

• Creates new client in Toggl
• If client name already exists → error
• Safe for initial data load

Example:

Excel: "New Client Corp"
Toggl: (doesn't exist)
Result: ✅ Created "New Client Corp"

Excel: "Existing Client"
Toggl: (already exists)
Result: ❌ Error: "Client already exists"

Update Mode

When to use: Updating notes for existing clients

Behavior:

• Finds client by name
• Updates the notes
• If client doesn't exist → error

Note: Toggl API doesn't support client updates yet. Use Upsert instead.

Upsert Mode (Recommended)

When to use: Regular syncs, mixed new and existing clients

Behavior:

• Finds client by name
• If exists → updates notes
• If doesn't exist → creates new client
• Most flexible

Example:

Excel: "Acme Corp" (notes: "Updated notes")
Toggl: "Acme Corp" already exists
Result: ✅ Updated notes for "Acme Corp"

Excel: "New Client Inc"
Toggl: (doesn't exist)
Result: ✅ Created "New Client Inc"

Troubleshooting

"Connection test failed"

Cause: Invalid credentials

Solutions:

1. Verify API token is correct (copy/paste carefully)
2. Check workspace ID (must be numeric)
3. Ensure you have access to the workspace
4. Try generating a new API token

"Client name is required"

Cause: Excel cell is empty or contains only whitespace

Solutions:

1. Check Excel cell has a value
2. Remove leading/trailing spaces
3. Verify Named Range points to correct cell

"Client already exists"

Cause: Using Insert mode, but client name already in Toggl

Solutions:

1. Switch to Upsert mode
2. Or rename the client in Excel
3. Or delete duplicate in Toggl first

"Rate limit exceeded"

Cause: Too many requests to Toggl API

Solutions:

1. Wait 60 seconds
2. Reduce batch size (sync fewer rows at once)
3. Toggl limit: 1 request per second

Rate Limits

Toggl Track has rate limiting:

• Limit: 1 request per second
• Our Handling: Automatic throttling built-in
• Recommendations:
  • Sync in batches of 50 clients max
  • Wait between syncs if doing multiple

Other Available Endpoints

In addition to the client workflow shown in this guide, the current connector surface also exposes:

• Projects
• Tags
• Time Entries
• Tasks
• Workspace Users
• Organizations
• Project Rates

Notes:

• some endpoints have provider-specific constraints, such as Toggl task availability depending on the Toggl plan
• inviting brand-new workspace users still belongs in the Toggl web UI; the ExForms connector does not replace the Toggl invitation flow
• connector-specific public API docs for Toggl are not published yet

API Reference

Connector-specific public API docs for Toggl are not published yet.

Need Help?

Common Questions:

• General Connectors Guide
• Field Mapping Best Practices

Support:

• Email: [email protected]
• Include: Connection name, error message, screenshot

Toggl Resources:

• Toggl API Documentation
• Toggl Support