# June 24, 2026 

** June 24, 2026 Karbon API release adds read-only Teams endpoints, an ExternalKey filter on Contacts, the UserDefinedIdentifier field on the Organizations list, and makes the Work Schedule assignee writable. **
---

## Read Teams and their members

Two new read-only endpoints expose your tenant's team structure.

`GET /v3/Teams` returns a paged list of teams, sorted by name. It supports `$filter` on `Name` (using `eq`), `$top`, and `$skip`.

```
GET /v3/Teams?$filter=Name eq 'Audit'
```

`GET /v3/Teams/{TeamKey}` returns a single team including its members.

```
GET /v3/Teams/2Nw8tnxwQCVf
```

```json
{
  "TeamKey": "2Nw8tnxwQCVf",
  "Name": "Audit",
  "Description": "Audit and assurance team",
  "ParentTeamKey": null,
  "Members": [
    { "Key": "3VQ8Qrq944NW", "Type": "User", "Name": "Alex Smith" },
    { "Key": "4WR9Srq055PX", "Type": "Team", "Name": "Audit — Melbourne" }
  ]
}
```

Each member has a `Type` of either `User` or `Team` (a team can contain sub-teams). Archived users are not returned. A request for a team key that does not exist returns `404 Not Found`.

Changing team membership is planned but not yet available through the API.

Adding, modifying and removing teams must be done via the Karbon UI.

## Set the assignee on Work Schedules

`AssigneeUserKey` is now writable on the Work Schedules update endpoints. Previously it was read-only and could only be set through the Karbon app.

```http
PATCH /v3/WorkSchedules/2LPSrkzbYrn4
Content-Type: application/json

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

The value must be the key of an existing Karbon user. It can be set on both `PUT` and `PATCH` requests.

Note that changing the value of AssigneeUserKey will change the Assignee on any incomplete Work Item in the Work Schedule series, complete Work Items will not be changed.

A `PUT` request that omits `AssigneeUserKey` — or sends it as `null` — leaves the current assignee unchanged, preserving behaviour for existing integrations. As per the Karbon UI - an Assignee cannot be removed once added.

## UserDefinedIdentifier returned on Organizations

`GET /v3/Organizations` now returns the `UserDefinedIdentifier` field on each organization, both in the list response and when retrieving a single organization. This matches the behaviour already available on `/v3/Contacts`.

```json
{
  "@odata.type": "#KarbonService.OrganizationSummaryDTO",
  "OrganizationKey": "2Nw8tnxwQCVf",
  "FullName": "Sample Company",
  "UserDefinedIdentifier": "ACME-001",
  "ContactType": "Client",
  "LastModifiedDateTime": "2026-06-18T10:15:30Z"
}
```

## Filter Contacts by External Key

A `GET` request to `/v3/Contacts` now supports filtering by `ExternalKey`. The `ExternalKey` value is the identifier from an integrated external system — for example, the Client ID from XPM, the Contact ID from Xero, or the Intuit Customer ID from QuickBooks Online.

```
GET /v3/Contacts?$filter=ExternalKey eq '123987456'
```

This returns only Contacts whose external key matches the provided value. Only the `eq` operator is supported.

The following external keys are supported:

| Integration | ExternalKey value |
|---|---|
| XPM | API v3.0 Client ID |
| Xero | Contact ID |
| QuickBooks Online Accountant | Intuit Customer ID |
| ProConnect | Intuit Customer ID |

**Note:** External keys are not guaranteed to be unique across connected systems. If multiple integrations are enabled in Karbon, this filter may return multiple results.