How to Create Goals with the ClickUp API

The ClickUp API lets you create goals programmatically so your product, integration, or automation can stay perfectly in sync with workspace objectives. This how-to guide walks you through every field required to call the Create Goal endpoint successfully, based strictly on the official API reference.

Understanding the ClickUp Create Goal endpoint

The Create Goal endpoint lets you add a new goal inside a specific team (also called a workspace). Each goal can contain targets that measure progress, and these can be tied to tasks, monetary values, numbers, or true/false outcomes.

The official reference for this endpoint is available here: ClickUp Create Goal API documentation.

Prerequisites for using the ClickUp API

Before you can create a goal, you need a few items ready in your application:

A valid API token with the correct permissions.
The team (workspace) ID where the goal will live.
Access to an HTTP client such as curl, Postman, or a backend language SDK or library.

In addition, make sure you understand your internal naming conventions for goals and how they map to your workspace structure.

ClickUp Create Goal endpoint overview

The Create Goal endpoint is a POST request that uses a team ID path parameter. It accepts a JSON body defining the new goal and optionally its targets.

HTTP method and URL

Method: POST
Endpoint: https://api.clickup.com/api/v2/team/{team_id}/goal

Replace {team_id} with the numeric identifier for the team where the goal should be created.

Required headers

When calling the endpoint, you must provide:

Authorization: <your_api_token>
Content-Type: application/json

The authorization token is generated within your workspace and must not be shared publicly.

Request body fields for a ClickUp goal

The request body is a JSON object that describes the goal. Some fields are required, while others are optional but very useful for reporting and automation.

Core goal properties

name (string, required): The goal name as it will appear in the workspace.
due_date (integer, optional): Unix timestamp in milliseconds defining when the goal is due.
description (string, optional): A longer explanation of what the goal represents.
multiple_owners (boolean, optional): Whether several owners can be assigned.
owners (array of strings, optional): User IDs for people responsible for the goal.
color (string, optional): A hex color or named color used to visually identify the goal.

If you omit optional fields, the ClickUp backend applies default behaviors, such as having no due date or owners.

Targets inside a ClickUp goal

You can attach one or more targets when you create the goal. Each target measures progress differently. The body uses a targets array where each item includes:

name (string, required): Target label.
type (string, required): How progress is tracked. Supported values typically include:
- number for simple numeric values.
- currency for financial amounts.
- boolean for completed or not completed states.
- tasks for counting done tasks.
unit (string, optional): A unit such as USD, tasks, or any descriptive label.
steps_start (number, optional): Starting value for the target.
steps_end (number, required): Target value to reach.
tasks (array, optional): List of task IDs that contribute to a tasks-based target.

Use targets to ensure your adoption of the ClickUp goal feature remains measurable and aligned with your reporting needs.

Step-by-step: Create a goal with the ClickUp API

Follow this sequence to create a goal via the API from any backend or integration.

1. Collect team and user data

First, retrieve or confirm the team ID and any owner user IDs you plan to associate with the goal. You can obtain these from other endpoints in the same platform API.

2. Build the JSON payload

Construct the JSON body using your preferred language. A typical payload might look like this:

{
  "name": "Increase Qualified Leads",
  "due_date": 1735689600000,
  "description": "Grow the number of qualified leads this quarter.",
  "multiple_owners": true,
  "owners": ["123456", "789012"],
  "color": "#4B8BF5",
  "targets": [
    {
      "name": "Lead Volume",
      "type": "number",
      "unit": "leads",
      "steps_start": 0,
      "steps_end": 500
    },
    {
      "name": "Closed Deals",
      "type": "tasks",
      "unit": "tasks",
      "steps_start": 0,
      "steps_end": 50,
      "tasks": ["task_id_1", "task_id_2"]
    }
  ]
}

Adjust target types and units to match how your team tracks progress in the workspace.

3. Send the POST request

Use curl, a REST client, or a backend library to send the request. A curl example would look like:

curl -X POST "https://api.clickup.com/api/v2/team/<team_id>/goal" \
  -H "Authorization: <your_api_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Increase Qualified Leads",
    "due_date": 1735689600000,
    "description": "Grow the number of qualified leads this quarter.",
    "multiple_owners": true,
    "owners": ["123456", "789012"],
    "color": "#4B8BF5",
    "targets": [
      {
        "name": "Lead Volume",
        "type": "number",
        "unit": "leads",
        "steps_start": 0,
        "steps_end": 500
      }
    ]
  }'

Confirm that you replaced the placeholders with real IDs and your live token.

4. Interpret the response

On success, the endpoint returns a JSON object containing the created goal, including its ID, targets, and metadata. Common tasks after a successful response include:

Storing the goal ID in your application database.
Displaying confirmation messages to end users.
Scheduling automations that update target progress over time.

Error handling with the ClickUp Create Goal endpoint

If the request fails, the API responds with an error status code and a message description. Some typical issues include:

Missing or invalid authorization header.
Team ID that does not exist or is not accessible to the token.
Invalid goal fields such as unsupported types or missing required attributes.

Log both the HTTP status and body whenever you receive an error to speed up debugging and keep your integration stable.

Best practices for ClickUp goal automation

When you scale your usage of this endpoint, follow these practical suggestions for robust automations:

Validate input data before sending it to the API.
Use consistent naming conventions for goals and targets.
Limit the number of targets per goal to what your team can realistically maintain.
Cache frequently used IDs, such as owners, to reduce additional API calls.

These practices help keep your integration maintainable and easier to extend later.

Next steps and additional resources

After you master the Create Goal endpoint, you can expand into updating goals, modifying targets, and integrating with reporting. For further platform strategy and implementation guidance, you can learn more at Consultevo.

Always refer to the official reference for the most current parameter details and examples: ClickUp Create Goal endpoint.

With this workflow in place, your application can reliably create, track, and manage goals using the same structures available inside the main workspace interface.

Need Help With ClickUp?

If you want expert help building, automating, or scaling your ClickUp workspace, work with ConsultEvo — trusted ClickUp Solution Partners.

Get Help

“`

Create Goals with ClickUp API