October 28, 2026

Segments (Preview)

This is a preview, available on request. Request access via the issue form. We don’t expect breaking changes, but the shape may evolve based on feedback.

Three new read-only endpoints return your shared Contact Segments and the clients in them:

GET https://api.karbonhq.com/v3/Segments/4fGh7JkL2mNp/Members?$top=100

{
  "@odata.count": 248,
  "@odata.nextLink": "https://api.karbonhq.com/v3/Segments/4fGh7JkL2mNp/Members?$skip=100",
  "value": [
    { "EntityKey": "7wPqXnT4mBjK", "EntityType": "Organization" },
    { "EntityKey": "RXq4mB32PXg", "EntityType": "Contact" }
  ]
}

Members are ordered by name and returned as a key and type only. Fetch full details from GET /v3/Contacts/{ContactKey} or GET /v3/Organizations/{OrganizationKey}. $top accepts up to 100; follow @odata.nextLink for the next page. Private and Hidden clients are only included when your app has the matching IncludePrivate/IncludeHidden permission.

Personal (unshared) Segments aren’t returned, and GET /v3/Segments doesn’t support $filter, $top or $skip.

Patch PrimaryStatus and SecondaryStatus on a Work Item

PATCH /v3/WorkItems/{WorkItemKey} now accepts PrimaryStatus and SecondaryStatus, so you can move a work item through its statuses without a full PUT:

PATCH https://api.karbonhq.com/v3/WorkItems/{WorkItemKey}

{
  "PrimaryStatus": "In Progress",
  "SecondaryStatus": "Send client requests"
}

• PrimaryStatus is required whenever SecondaryStatus is sent.
• Sending PrimaryStatus on its own clears the work item’s SecondaryStatus.
• SecondaryStatus must belong to the PrimaryStatus and be enabled for the work item’s WorkType. Valid values are listed under WorkStatuses in GET /v3/TenantSettings.

An invalid status returns a 400. Unlike PUT, PATCH never silently drops a SecondaryStatus that doesn’t apply to the work item’s WorkType.

LastModifiedDateTime on Work Items

GET /v3/WorkItems and GET /v3/WorkItems/{WorkItemKey} now return LastModifiedDateTime, the date and time the work item was last changed:

{
  "WorkItemKey": "4jgPTtcXxwC2",
  "Title": "FY2026 Income Tax Return",
  "LastModifiedDateTime": "2026-10-27T22:14:05Z",
  ...
}

LastModifiedDateTime is read-only, and can’t yet be used in $filter or $orderby.

Filing Deadline Dates on Work Schedules

POST and PUT on /v3/WorkSchedules now accept OnFilingDate for both ScheduleDueDateMethod and ScheduleDeadlineDateMethod, setting the date from one of your account’s filing deadlines. Each method takes two new properties:

POST https://api.karbonhq.com/v3/WorkSchedules

{
  "CreatedFromWorkItemKey": "4jgPTtcXxwC2",
  "RecurrenceFrequency": "Year",
  "ScheduleStartDate": "2027-01-01T00:00:00Z",
  "ScheduleDueDateMethod": "OnFilingDate",
  "ScheduleDueDateFilingDeadlineKey": "2kTn7wQpXc4R",
  "ScheduleDueDateResolveType": "FilingDeadline",
  "ScheduleDeadlineDateMethod": "OnFilingDate",
  "ScheduleDeadlineDateFilingDeadlineKey": "2kTn7wQpXc4R",
  "ScheduleDeadlineDateResolveType": "FilingDeadlineExtension"
}

The key and resolve type are required together when the method is OnFilingDate, and can’t be sent with any other method. On PUT, omitting the key on a schedule that already uses OnFilingDate keeps its existing filing deadline. GET /v3/WorkSchedules/{WorkScheduleKey} returns all four properties, null unless the matching method is OnFilingDate.

Companies House deadline methods are still not available through the API.

Refer to the API documentation for more information on work schedules.