---
title: "Create a task"
method: POST
path: "/companies/{company}/tasks"
tags: ["Tasks"]
---

# Create a task

`POST /companies/{company}/tasks`

## Request

- Base URL: `https://api.factuarea.com/v1`
- URL: `https://api.factuarea.com/v1/companies/{company}/tasks`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Create a task in a project; `project_id` and `title` are required.
- It starts in the first column unless you send `column_id` or a virtual `status` (`planned` for the backlog).
- `entity_link` (`type` + `id`) links a document or contact atomically; if the entity is not found or accessible, 404 `linked_entity_not_found` and no task is created.

## Path parameters

- `company` string, uuid, required

## Headers

- `Idempotency-Key` string
- `Factuarea-Version` string, date

## Request body

- CreateTaskV1Request
  - `project_id` string, uuid, required: `id` of the project the task belongs to.
  - `title` string, required: Task title (1 to 500 characters).
  - `description` string, nullable: Description in Markdown.
  - `priority` 'none' | 'low' | 'medium' | 'high' | 'urgent': Priority: `none` (default), `low`, `medium`, `high` or `urgent`.
  - `column_id` string, uuid, nullable: `id` of the project column the task is created in. Mutually exclusive with `status`.
  - `status` string, nullable: Virtual status the task is created in (`planned` or `archived`). Mutually exclusive with `column_id`.
  - `start_on` string, date, nullable: Start date (`YYYY-MM-DD`).
  - `due_on` string, date, nullable: Due date (`YYYY-MM-DD`).
  - `assignee_id` string, uuid, nullable: `id` of the company member user the task is assigned to.
  - `label_ids` string[]: `id` of the company task labels to attach to the task.
  - `custom_fields` object: Values of the project's custom fields, as a map from the custom field public identifier (UUID v7) to its value: text, number, boolean, or a list of options for a `multiselect` field. `null` leaves the field empty.
  - `entity_link` object, nullable: Links the task to a Factuarea document or contact in the same transaction. If the entity does not exist, belongs to another company or its module is not accessible, the call returns 404 `linked_entity_not_found` and the task is not created.
    - `type` 'invoice' | 'quote' | 'proforma' | 'delivery_note' | 'purchase_invoice' | 'recurring_invoice' | 'contact' | 'product' | 'employee', required: Type of the entity.
    - `id` string, uuid, required: UUID of the entity.

## Response `201`

Task created successfully. The `Location` header contains the canonical URL of the newly created task.

- object
  - `data` Task, required: A task of a project board.
    - `id` string, uuid, required: UUID v7 of the task.
    - `object` 'task', required: Stripe-like discriminator. Always `task` for this resource.
    - `key` string, required: Task key: project key and number (`DEV-12`).
    - `number` integer, required: Number of the task in its project.
    - `project_id` string, uuid, required: UUID of the project.
    - `column_id` string, uuid, nullable, required: UUID of the board column, or `null` in the backlog (`planned`) or when `archived`.
    - `status` 'planned' | 'active' | 'archived', required: Board status: `planned` (backlog), `active` (in a column of the board) or `archived`.
    - `priority` 'none' | 'low' | 'medium' | 'high' | 'urgent', required: Task priority.
    - `title` string, required: Task title.
    - `description` string, nullable, required: Description in Markdown, or `null`.
    - `start_on` string, date, nullable, required: Start date, or `null`.
    - `due_on` string, date, nullable, required: Due date, or `null`.
    - `assignee_id` string, uuid, nullable, required: UUID of the assigned member, or `null`.
    - `labels` object[], required: Labels of the task.
      - `id` string, uuid, required: UUID of the label.
      - `name` string, required
      - `color` string, required
    - `custom_fields` object[], required: Values of the custom fields of the project.
      - `field_id` string, uuid, required: UUID of the custom field.
      - `name` string, required
      - `type` 'text' | 'number' | 'date' | 'dropdown' | 'boolean' | 'multiselect', required
      - `value` string, nullable, required: Value serialized as a string (a JSON array for `multiselect`), or `null`.
    - `completed_at` string, date-time, nullable, required: When the task was completed, or `null` while open.
    - `created_at` string, date-time, required: Creation timestamp.
    - `updated_at` string, date-time, required: Last update timestamp.
    - `counts` object, required: Counters of the task.
      - `subtasks_total` integer, required
      - `subtasks_completed` integer, required
      - `comments` integer, required
      - `attachments` integer, required

## Other responses

- `400`: `parameter_unknown` with `subcode` `retired_active_profile_header`: the retired `X-Active-Profile` header was sent; the company goes in the path. `parameter_invalid_format` on `Factuarea-Version`: the header is not a `YYYY-MM-DD` date. `unsupported_api_version`: the `Factuarea-Version` date is not a supported version.
- `401`: Missing or invalid API key.
- `403`: The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).
- `404`: The requested resource does not exist or belongs to another company.
- `409`: The request conflicts with data that already exists or with a request running at the same time. `task_column_capacity_exceeded`: the destination column has reached its maximum number of tasks. Move the task to another column. `task_relation_exists`: the two tasks are already related with that relation type. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.
- `422`: Validation failed. The `error.param` field identifies which input is invalid.
- `429`: Rate limit exceeded. Retry after the duration in `Retry-After`.
- `500`: Unexpected server error.

---

[API](https://skmtc.dev/factuarea/apis/factuarea-public-api.md) · [All operations](https://skmtc.dev/factuarea/apis/factuarea-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/factuarea/apis/factuarea-public-api/revisions/718e77934422?raw)