Teamwork#

Teamwork is registered for API sync with sync-coupled user import. It pulls tasks from one configured Teamwork project or tasklist into a reviewable import session, proposes TeamBoost user mappings from Teamwork people and task actors, and projects each task into the internal integrations task-create draft.

The endpoints below live under /api/v1/providers/teamwork/.... They are generic: the same routes serve any registered provider by substituting the {provider} path segment. All routes require an organization-scoped user token (see Authentication).

Discovery#

GET /api/v1/providers/teamwork

{
  "status": "success",
  "data": { "provider": "teamwork", "capabilities": ["SYNC", "USER_IMPORT"] }
}

Credential Verification#

Teamwork API keys can be stored and verified as an encrypted JSON credential:

PUT /api/v1/providers/teamwork/credentials?organization_id=<id>
POST /api/v1/providers/teamwork/credentials/verify?organization_id=<id>

The stored secret is a JSON object:

{
  "site_url": "https://example.teamwork.com",
  "api_key": "<teamwork-api-key>",
  "sync_scope": {
    "kind": "project",
    "id": "12345"
  }
}

sync_scope.kind may be project or tasklist; id is the numeric Teamwork scope id as a string or number. Verification uses Teamwork Basic auth with api_key:x and a cheap Teamwork V3 API probe:

• project scope: GET /projects/api/v3/projects.json?projectIds=<id>&pageSize=1
• tasklist scope: GET /projects/api/v3/tasklists/<id>.json?pageSize=1

The service accepts a copied Teamwork browser URL and normalizes it to the tenant base URL, for example https://example.teamwork.com/app/projects/123/settings becomes https://example.teamwork.com. Stored secrets are encrypted at rest and never returned by the credential endpoints.

Importing From The Teamwork API#

POST /api/v1/providers/teamwork/imports/sync?organization_id=<id>

Uses the stored, encrypted Teamwork credential to fetch the configured project or tasklist scope. The adapter follows Teamwork V3 pagination, pulls people for the proposed user mapping, and requests task sideloads for users, tags, tasklists, and projects.

Teamwork source records preserve raw task fields plus mapping context such as projectName, tasklistName, tag names, assignee ids, workflow stages, parent task id, dependency/predecessor/subtask ids, and custom field values.

User Mapping#

Teamwork USER_IMPORT rides the sync flow. The adapter proposes mappings from:

• people returned by GET /projects/api/v3/people.json;
• users sideloaded from task responses;
• task creator and assignee ids referenced by synced tasks.

The primary matching key is the Teamwork user id (sourceAccountId). E-mail is secondary when present. A present but unmapped primary assignee creates a blocking projectionError. A missing or unmapped creator leaves creatorId unset with a non-blocking mapping note.

If a Teamwork task has multiple assignees, the first deterministic assignee is used as the proposed TeamBoost owner and all assignee ids are preserved in descriptionJson with a mapping note.

Projection Field Coverage#

Not Built Yet#

• Teamwork CSV/report import.
• Teamwork OAuth app install flow.
• Teamwork webhook registration and event verification.