# Creating a New Work Item 

** Create work items from scratch or from pre-configured templates by providing a title, assignee, client, and start date, with support for setting work types, statuses, and fee structures, plus filtering and updating existing work items via the API. **
---

Work items represent the tasks and engagements you manage for clients. You can create them from scratch or from a work template that pre-populates tasks and settings.

## Required Fields

Every work item requires these fields:

| Field                  | Description                                                 |
| ---------------------- | ----------------------------------------------------------- |
| `Title`                | Name of the work item                                       |
| `AssigneeEmailAddress` | Email of the Karbon user responsible                        |
| `ClientKey`            | Key of the associated Contact, Organization, or ClientGroup |
| `ClientType`           | `Contact`, `Organization`, or `ClientGroup`                 |
| `StartDate`            | ISO 8601 datetime string (e.g., `2026-04-01T00:00:00Z`)     |

## Creating a Basic Work Item

```http
POST https://api.karbonhq.com/v3/WorkItems
Authorization: Bearer {token}
AccessKey: {key}
Content-Type: application/json

{
  "Title": "FY2026 Income Tax Return",
  "AssigneeEmailAddress": "marcus.okonkwo@example.com",
  "ClientKey": "7wPqXnT4mBjK",
  "ClientType": "Organization",
  "StartDate": "2026-04-01T00:00:00Z",
  "DeadlineDate": "2026-06-30T00:00:00Z"
}
```

A successful response returns the created work item including its generated `WorkItemKey`.

## Work Types and Statuses

Work types are tenant-specific. Fetch yours from `TenantSettings` before creating work:

```http
GET https://api.karbonhq.com/v3/TenantSettings
```

The response includes available `WorkTypes` and `WorkStatuses`. Use the exact string values when setting these fields on a work item.

The built-in `PrimaryStatus` values are:

| Value            | Meaning                            |
| ---------------- | ---------------------------------- |
| `Planned`        | Not yet started                    |
| `Ready To Start` | Ready to begin                     |
| `In Progress`    | Actively being worked on           |
| `Waiting`        | Blocked or awaiting external input |
| `Completed`      | Done                               |

## Setting Fees

Record the way the work item should be billed using the `FeeSettings` object:

```json
{
  "FeeSettings": {
    "FeeType": "FixedFee",
    "FeeValue": 1500.00
  }
}
```

```json
{
  "FeeSettings": {
    "FeeType": "TimeAndMaterials",
    "FeeValue": null
  }
}
```

```json
{
  "FeeSettings": {
    "FeeType": "NonBillable",
    "FeeValue": null
  }
}
```

Note: Hourly rates and time estimates are read-only and cannot be set via the API.

## Creating from a Work Template

Work templates pre-populate tasks, assignments, and settings — great for recurring work like tax returns or audits.

### Step 1: Find the template

```http
GET https://api.karbonhq.com/v3/WorkTemplates
Authorization: Bearer {token}
AccessKey: {key}
```

You can filter by title:

```http
GET /v3/WorkTemplates?$filter=Title eq 'FY Income Tax Return'
```

This returns a list of templates with their `WorkTemplateKey` values. You can also sort templates to find the most frequently used:

```http
GET /v3/WorkTemplates?$orderby=NumberOfWorkItemsCreated desc
```

### Step 2: Create the work item using the template key

Add `WorkTemplateKey` to your request body. The template will pre-populate tasks and other settings:

```http
POST https://api.karbonhq.com/v3/WorkItems
Authorization: Bearer {token}
AccessKey: {key}
Content-Type: application/json

{
  "Title": "FY2026 Income Tax Return",
  "AssigneeEmailAddress": "marcus.okonkwo@example.com",
  "ClientKey": "7wPqXnT4mBjK",
  "ClientType": "Organization",
  "StartDate": "2026-04-01T00:00:00Z",
  "DeadlineDate": "2026-06-30T00:00:00Z",
  "WorkTemplateKey": "2vBsCfGk9hJD"
}
```

## Filtering Existing Work Items

Before creating work, you may want to check if similar work already exists for a client:

```http
GET /v3/WorkItems?$filter=ClientKey eq '7wPqXnT4mBjK' and WorkType eq 'Tax'
```

Other useful filters:

```http
# Work assigned to a specific person
GET /v3/WorkItems?$filter=AssigneeEmailAddress eq 'marcus.okonkwo@example.com'

# In-progress work only
GET /v3/WorkItems?$filter=PrimaryStatus eq 'In Progress'

# Work starting after a date
GET /v3/WorkItems?$filter=StartDate ge 2026-01-01

# All work items created from a specific template
GET /v3/WorkItems?$filter=WorkTemplateKey eq '2vBsCfGk9hJD'
```

**Note:** `ClientKey`, `PrimaryStatus`, `WorkScheduleKey`, and `WorkTemplateKey` do not support `contains` — use `eq` only.

## Updating a Work Item

Use PUT to update a work item. PUT replaces the entire record — any fields you omit will be cleared. **Always GET the record first, apply your changes, then PUT it back** to avoid accidentally losing data:

```http
PUT https://api.karbonhq.com/v3/WorkItems/{WorkItemKey}
Authorization: Bearer {token}
AccessKey: {key}
Content-Type: application/json

{
  "Title": "FY2026 Income Tax Return",
  "AssigneeEmailAddress": "marcus.okonkwo@example.com",
  "ClientKey": "7wPqXnT4mBjK",
  "ClientType": "Organization",
  "StartDate": "2026-04-01T00:00:00Z",
  "DeadlineDate": "2026-06-30T00:00:00Z",
  "PrimaryStatus": "In Progress"
}
```

For partial updates, PATCH the work item with only the fields you want to change:

```http
PATCH https://api.karbonhq.com/v3/WorkItems/{WorkItemKey}
Authorization: Bearer {token}
AccessKey: {key}
Content-Type: application/json

{
  "Title": "Q2 review prep",
  "AssigneeEmailAddress": "alex@example.com"
}
```

PATCH accepts `Title`, `Description`, `StartDate`, `DueDate`, `DeadlineDate`, `AssigneeEmailAddress`, and `WorkType`. `AssigneeEmailAddress` must be an existing Karbon user and `WorkType` must be configured on the account — unknown values return a `400`. Sending any other property also returns a `400`; use PUT for broader updates.

### Handling concurrent updates

If two requests race to update the same work item (or any other resource), the later commit is rejected with a `409 Conflict`:

```json
{
  "error": {
    "code": "4020",
    "message": "The resource was modified by another request. Refetch the latest version and retry."
  }
}
```

When you receive a `409`, re-fetch the work item, reapply your change against the latest version, and submit again.

## Ending a Repeating Work Schedule

If a work item is linked to a Work Schedule (via `WorkScheduleKey`), you can stop the schedule from producing future work items by setting its `ScheduleEndDate`. Use PATCH so you don't need to GET and resubmit the full schedule:

```http
PATCH https://api.karbonhq.com/v3/WorkSchedules/{WorkScheduleKey}
Authorization: Bearer {token}
AccessKey: {key}
Content-Type: application/json

{
  "ScheduleEndDate": "2026-12-31T00:00:00Z"
}
```

Pass `null` for `ScheduleEndDate` to clear an existing end date and let the schedule continue indefinitely. The Work Schedules `PATCH` endpoint accepts `ScheduleEndDate` and `AssigneeUserKey`; for any other changes, use `PUT /v3/WorkSchedules/{WorkScheduleKey}`.

## Changing the Assignee on a Work Schedule

The Karbon user a Work Schedule assigns its generated work items to can be set through the API using `AssigneeUserKey` (the key of an existing Karbon user). It can be set on both `PUT` and `PATCH`:

```http
PATCH https://api.karbonhq.com/v3/WorkSchedules/{WorkScheduleKey}
Authorization: Bearer {token}
AccessKey: {key}
Content-Type: application/json

{
  "AssigneeUserKey": "3VQ8Qrq944NW"
}
```

Changing the assignee reassigns every incomplete work item in the schedule series; already-completed work items keep their original assignee.

A `PUT` that omits `AssigneeUserKey` — or sends it as `null` — leaves the current assignee unchanged, preserving behaviour for existing integrations. Like the Karbon UI, you cannot clear the AssigneeUserKey field.