V1.Projects.Create

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/timely/main/json-schema/timely-v1-projects-create-schema.json",
  "title": "V1.Projects.Create",
  "x-generated": "2026-10-27",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/timely-openapi.json#/components/schemas/V1.Projects.Create",
  "type": "object",
  "properties": {
    "project": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Project name",
          "minLength": 1
        },
        "color": {
          "type": "string",
          "description": "Hex color code (3-6 characters, without #)",
          "minLength": 3,
          "maxLength": 6,
          "pattern": "^([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$"
        },
        "company_id": {
          "type": "integer",
          "description": "Client ID. Not required if \"new_company\" or \"client_id\" attribute filled"
        },
        "client_id": {
          "type": "integer",
          "description": "Client ID (alias for company_id). Not required if \"new_company\" or \"company_id\" attribute filled"
        },
        "new_company": {
          "type": "string",
          "description": "Create new client with this name. Not required if \"company_id\" or \"client_id\" attribute filled"
        },
        "hour_rate": {
          "type": "number",
          "description": "Hourly rate for the project"
        },
        "rate_type": {
          "type": "string",
          "description": "Rate type for the project (e.g., project, user)",
          "enum": [
            "project",
            "user",
            "non-billable"
          ]
        },
        "budget": {
          "type": "number",
          "description": "Budget amount (hours or money depending on budget_type)"
        },
        "budget_type": {
          "type": "string",
          "description": "Budget type: hours or money",
          "enum": [
            "H",
            "M"
          ]
        },
        "billable": {
          "type": "boolean",
          "description": "Whether the project is billable by default"
        },
        "active": {
          "type": "boolean",
          "description": "Whether the project is active"
        },
        "external_id": {
          "type": "string",
          "description": "External reference ID for integrations"
        },
        "budget_scope": {
          "type": "string",
          "description": "Budget scope: project-wide or per tag",
          "enum": [
            "tag",
            "project"
          ]
        },
        "send_invite": {
          "type": "boolean",
          "description": "Whether to send invitation emails to project users"
        },
        "required_notes": {
          "type": "array",
          "description": "Deprecated: Use required_label_ids instead",
          "items": {
            "type": "string"
          }
        },
        "required_labels": {
          "type": "array",
          "description": "Deprecated: Use label_ids with required_label_ids instead",
          "items": {
            "type": "string"
          }
        },
        "enable_labels": {
          "type": "boolean",
          "description": "Whether tags are enabled for this project"
        },
        "default_labels": {
          "type": "boolean",
          "x-internal": true,
          "description": "Whether to use default tags"
        },
        "invoice_by_budget": {
          "type": "integer",
          "description": "Invoice settings based on budget"
        },
        "team_ids": {
          "type": "array",
          "description": "Array of team IDs to assign to the project",
          "items": {
            "type": "integer"
          }
        },
        "update_hour_billable_state": {
          "type": "boolean",
          "description": "Whether to update billable state of existing hours"
        },
        "currency_code": {
          "type": "string",
          "description": "Currency code for the project (e.g., USD, EUR)"
        },
        "exchange_rate": {
          "type": "string",
          "description": "Exchange rate for currency conversion"
        },
        "description": {
          "type": "string",
          "description": "Project description"
        },
        "label_ids": {
          "type": "array",
          "description": "Array of tag IDs to assign to the project",
          "items": {
            "type": "integer"
          }
        },
        "required_label_ids": {
          "type": "array",
          "description": "Array of tag IDs that are required for time entries",
          "items": {
            "type": "integer"
          }
        },
        "users": {
          "type": "array",
          "description": "Array of users to assign to the project with their hourly rates",
          "items": {
            "type": "object",
            "properties": {
              "user_id": {
                "type": "integer",
                "description": "User ID to assign to the project"
              },
              "hour_rate": {
                "type": "number",
                "description": "Hourly rate for this user on the project"
              }
            },
            "required": [
              "user_id",
              "hour_rate"
            ]
          }
        },
        "labels": {
          "type": "array",
          "description": "Array of tags with their configurations",
          "items": {
            "type": "object",
            "properties": {
              "label_id": {
                "type": "number",
                "description": "Tag ID"
              },
              "budget": {
                "type": "number",
                "description": "Budget allocated for this tag"
              },
              "required": {
                "type": "boolean",
                "description": "Whether this tag is required for time entries"
              },
              "default": {
                "type": "boolean",
                "description": "Whether this tag is selected by default"
              }
            },
            "required": [
              "label_id"
            ]
          }
        },
        "budget_recurrence": {
          "type": "array",
          "description": "Budget recurrence rules for recurring budget allocation",
          "items": {
            "type": "object",
            "properties": {
              "recur": {
                "type": "string",
                "description": "Recurrence pattern: monthly or until end date",
                "minLength": 1,
                "enum": [
                  "end_date",
                  "month"
                ]
              },
              "start_date": {
                "type": "string",
                "format": "date-time",
                "description": "Start date for budget recurrence",
                "minLength": 1
              },
              "end_date": {
                "type": "string",
                "format": "date-time",
                "description": "End date for budget recurrence. Required when recur_until is end_date"
              },
              "recur_until": {
                "type": "string",
                "description": "When to stop recurring: until end date or until project is archived",
                "minLength": 1,
                "enum": [
                  "end_date",
                  "archived"
                ]
              }
            },
            "required": [
              "recur",
              "start_date",
              "recur_until"
            ]
          }
        }
      },
      "required": [
        "name",
        "rate_type"
      ]
    }
  },
  "required": [
    "project"
  ]
}