Creating a New Work Item

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:

Creating a Basic Work Item

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:

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:

Setting Fees

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

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

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

{
  "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

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

You can filter by title:

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:

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:

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:

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

Other useful filters:

# 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

Note: ClientKey, PrimaryStatus, and WorkScheduleKey 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:

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 is supported but only for Description and DeadlineDate.