Using Teamwork

Practical guide for working with Teamwork projects, tasks, milestones, and time tracking through Fp Switchboard.

Quick Tips

• All IDs are numeric integers. Endpoint uses “people” not “users”
• V1 dates: YYYYMMDD. V3 dates: ISO 8601. V1 keys: hyphenated. V3: camelCase
• Tasks require a tasklist: POST /tasklists/{id}/tasks.json
• Custom fields: Create in V3, attach in V1, retrieve in V2
• Rate limit: 150/min (Grow), 300/min (Scale). Check X-Rate-Limit-Remaining

Common Gotchas

People Not Users Critical

Endpoint paths use “people” but task assignments use userIds.

	Example
Wrong	GET /projects/api/v3/users.json
Correct	GET /projects/api/v3/people.json (but assignees.userIds in task body)

Date Formats Vary by Version Critical

V1 uses YYYYMMDD, V3 uses ISO 8601. Key names also differ.

Version	Example
V1	start-date: "20250115"
V3	startAt: "2025-01-15"

Tasks Need Tasklist Critical

Cannot create orphan tasks. Must specify tasklist in URL.

	Example
Wrong	POST /projects/api/v3/tasks.json
Correct	POST /projects/api/v3/tasklists/{tasklistId}/tasks.json

Custom Fields Multi-Version Important

Custom fields require using multiple API versions together:

• Create in V3
• Attach in V1
• Retrieve in V2 with includeCustomFields=true

V1 vs V3 Key Names Important

V1	V3
todo-item	task
start-date	startAt
due-date	dueAt
Hyphenated keys	camelCase keys

Multi-Step Patterns

Create Task

1. Get or create project
2. Get or create tasklist in project
3. POST /projects/api/v3/tasklists/{tasklistId}/tasks.json
4. Use camelCase keys (name, startAt, dueAt)

Upload File

1. GET /projects/api/v1/pendingfiles/presignedurl.json
2. Upload to S3 URL with exact Content-Length
3. Attach using ref ID: pendingFileAttachments: ["tf_..."]

ID Format Reference

ID Type	Format	Example
Project/Task/Person ID	Numeric integer	12345

Example Prompts

• “List my Teamwork projects”
• “Show tasks assigned to me this week”
• “Create a task in the Development tasklist”
• “Log 2 hours on task 12345”
• “List milestones for the Q1 project”

Rate Limits

Plan	Limit
Grow	150 requests/minute
Scale	300 requests/minute
Header	Check X-Rate-Limit-Remaining