Clickup Reference Architecture

---
name: clickup-reference-architecture
description: 'Production architecture for ClickUp API v2 integrations with layered
  design,

  custom fields, time tracking, goals, and two-way sync patterns.

  Trigger: "clickup architecture", "clickup design", "clickup project structure",

  "clickup custom fields", "clickup time tracking", "clickup goals API".

  '
allowed-tools: Read, Grep
version: 1.6.0
license: MIT
author: Jeremy Longshore <jeremy@intentsolutions.io>
tags:
- saas
- productivity
- clickup
compatibility: Designed for Claude Code
---
# ClickUp Reference Architecture

## Overview

Production-ready architecture for ClickUp API v2 integrations covering custom fields, time tracking, goals, and two-way sync with external systems.

## Prerequisites

- Approved workspace/list scope, data classification, and integration owner
- Dedicated scoped identity, secret reference, and separate non-production path
- Versioned mapping, idempotency, conflict-resolution, and recovery decisions
- Monitoring/alerting for sync freshness, retries, and authorization failures

## Instructions

Implement the client boundary and mappings in a staging scope first, then test
one-way and two-way changes with deterministic external IDs, conflict handling,
and least-privilege access. Promote only after observed sync, permission, and
rollback behavior match the architecture; do not use last-write-wins by default
for business-critical fields without a named owner decision.

## Architecture Layers

```
┌──────────────────────────────────────────┐
│          Application Layer               │
│   (Routes, Controllers, Webhooks)        │
├──────────────────────────────────────────┤
│          Service Layer                   │
│   (Business Logic, Orchestration)        │
├──────────────────────────────────────────┤
│          ClickUp Client Layer            │
│   (API Wrapper, Types, Cache, Retry)     │
├──────────────────────────────────────────┤
│          Infrastructure                  │
│   (Queue, Cache, Monitoring, Secrets)    │
└──────────────────────────────────────────┘
          │
          ▼
  api.clickup.com/api/v2/
```

## Custom Fields API

Custom fields let you extend tasks beyond built-in fields. Each field has a UUID and a type.

```
GET  /api/v2/list/{list_id}/field          Get accessible custom fields
POST /api/v2/task/{task_id}/field/{field_id}  Set custom field value
DELETE /api/v2/task/{task_id}/field/{field_id}  Remove custom field value
```

### Custom Field Types and Value Formats

| Type | `value` Format | Example |
|------|---------------|---------|
| `text` | string | `"Release v2.1"` |
| `number` | number | `42` |
| `money` / `currency` | number (in smallest unit) | `9999` (= $99.99) |
| `date` | Unix ms timestamp | `1695000000000` |
| `drop_down` | option UUID from `type_config.options` | `"opt_uuid_123"` |
| `labels` | array of label UUIDs | `["lbl_uuid_1", "lbl_uuid_2"]` |
| `checkbox` | boolean | `true` |
| `email` | string | `"user@example.com"` |
| `phone` | string | `"+1-555-0100"` |
| `url` | string | `"https://example.com"` |
| `rating` | number (0-5) | `4` |
| `location` | object | `{ "lat": 33.749, "lng": -84.388 }` |

```typescript
// Get custom fields for a list
const fields = await clickupRequest(`/list/${listId}/field`);
// Response: { fields: [{ id: "uuid", name: "Sprint", type: "drop_down", type_config: { options: [...] } }] }

// Set a dropdown custom field
const sprintField = fields.fields.find((f: any) => f.name === 'Sprint');
const nextSprint = sprintField.type_config.options.find((o: any) => o.name === 'Sprint 24');

await clickupRequest(`/task/${taskId}/field/${sprintField.id}`, {
  method: 'POST',
  body: JSON.stringify({ value: nextSprint.orderindex }),
});

// Set a date custom field
await clickupRequest(`/task/${taskId}/field/${dateFieldId}`, {
  method: 'POST',
  body: JSON.stringify({ value: Date.now() + 604800000 }), // 1 week from now
});
```

## Time Tracking API

```
POST   /api/v2/team/{team_id}/time_entries     Create time entry
GET    /api/v2/team/{team_id}/time_entries     Get time entries (date range)
GET    /api/v2/team/{team_id}/time_entries/current  Get running timer
GET    /api/v2/task/{task_id}/time             Get tracked time on task
PUT    /api/v2/team/{team_id}/time_entries/{timer_id}  Update entry
DELETE /api/v2/team/{team_id}/time_entries/{timer_id}  Delete entry
```

```typescript
// Create a time entry (logged time)
await clickupRequest(`/team/${teamId}/time_entries`, {
  method: 'POST',
  body: JSON.stringify({
    task_id: 'abc123',
    description: 'Worked on auth module',
    start: Date.now() - 3600000, // 1 hour ago
    duration: 3600000,           // 1 hour in ms
    assignee: 183,               // user ID
    billable: true,
  }),
});

// Get entries for a date range (default: last 30 days)
const entries = await clickupRequest(
  `/team/${teamId}/time_entries?start_date=${startMs}&end_date=${endMs}`
);
// Note: negative duration means timer is currently running
```

## Goals API

```
POST   /api/v2/team/{team_id}/goal         Create goal
GET    /api/v2/team/{team_id}/goal         Get goals
GET    /api/v2/goal/{goal_id}              Get goal
PUT    /api/v2/goal/{goal_id}              Update goal
DELETE /api/v2/goal/{goal_id}              Delete goal
POST   /api/v2/goal/{goal_id}/key_result   Create key result
PUT    /api/v2/key_result/{key_result_id}  Update key result
DELETE /api/v2/key_result/{key_result_id}  Delete key result
```

```typescript
// Create a goal with key results
const goal = await clickupRequest(`/team/${teamId}/goal`, {
  method: 'POST',
  body: JSON.stringify({
    name: 'Q1 2026 Engineering OKRs',
    due_date: 1711929600000,
    description: 'Engineering team quarterly objectives',
    multiple_owners: true,
    owners: [183, 456],
    color: '#05a1f5',
  }),
});

// Add a key result (target)
await clickupRequest(`/goal/${goal.goal.id}/key_result`, {
  method: 'POST',
  body: JSON.stringify({
    name: 'Reduce P95 latency to <200ms',
    type: 'number',
    steps_start: 500,
    steps_end: 200,
    unit: 'ms',
    owners: [183],
  }),
});
```

## Two-Way Sync Pattern

```typescript
// Sync ClickUp tasks to external system and vice versa
class ClickUpSyncService {
  async syncToExternal(listId: string) {
    const { tasks } = await clickupRequest(`/list/${listId}/task?archived=false`);

    for (const task of tasks) {
      await externalSystem.upsert({
        externalId: task.id,
        title: task.name,
        status: this.mapStatus(task.status.status),
        assignee: task.assignees[0]?.email,
        updatedAt: parseInt(task.date_updated),
      });
    }
  }

  async syncFromExternal(externalItem: ExternalItem) {
    if (externalItem.clickupTaskId) {
      await clickupRequest(`/task/${externalItem.clickupTaskId}`, {
        method: 'PUT',
        body: JSON.stringify({
          name: externalItem.title,
          status: this.reverseMapStatus(externalItem.status),
        }),
      });
    }
  }

  private mapStatus(clickupStatus: string): string {
    const map: Record<string, string> = {
      'to do': 'backlog', 'in progress': 'active',
      'review': 'in_review', 'complete': 'done',
    };
    return map[clickupStatus] ?? 'backlog';
  }
}
```

## Error Handling

| Issue | Cause | Solution |
|-------|-------|----------|
| Custom field UUID not found | Field removed or renamed | Re-fetch fields via `/list/{id}/field` |
| Time entry negative duration | Timer still running | Stop timer before reading duration |
| Goal permission denied | User not goal owner | Add user to goal owners |
| Sync conflict | Both sides updated | Last-write-wins or manual merge |

## Output

Produce an architecture record with source/destination boundaries, mappings,
identity scope, conflict and idempotency policy, monitoring, retention, owner,
and rollback evidence. It must avoid live tokens, private task content, and
unapproved member data.

## Examples

Synchronize one staging list with external IDs, then create a controlled
simultaneous edit to prove the selected conflict policy and audit outcome. If
the mapping or permission check fails, halt the sync and restore the prior
certified state before expanding to additional lists.

## Resources

- [Custom Fields Docs](https://developer.clickup.com/docs/customfields)
- [Set Custom Field Value](https://developer.clickup.com/reference/setcustomfieldvalue)
- [Time Tracking Endpoints](https://developer.clickup.com/reference/createatimeentry)
- [ClickUp Developer Portal](https://developer.clickup.com/)

## Next Steps

For multi-environment setup, see `clickup-multi-env-setup`.