Home

February 8, 2024

The February 8, 2024 Karbon API release includes two changes:

  1. API access can be configured to allow access to Hidden and Private contacts.
  2. The DeadlineDate property has been added to the WorkItems API endpoint - this makes it possible to set, retrieve and update a deadline date on a Work Item.

API access to Hidden and Private contacts

Each Karbon API application can now be configured to enable access to Hidden and/or Private contacts. Enabling either or both of these settings will return contacts and associated data (such as WorkItems) in Karbon API responses, where previously a 404 would be returned.

NOTE: This configuration change must be requested via Karbon Support and be approved by an administrator in the connected Karbon account. You can make this request by reaching out to support directly, or via the issue form.

Where a single API application is connected to multiple Karbon accounts, each Karbon account has its own unique settings, i.e. Karbon Account A can have access to Hidden Contacts, whilst Karbon Account B has neither access to Hidden nor Private Contacts.

Deadline Date

NOTE: Whilst this API change is available to all API users, as at the time of writing the changes to the Karbon Application are only available to firms enrolled in the Deadlines BETA, this means that Deadline Dates you set using the API may not be visible in Karbon. You can read more about the Deadlines BETA in our January 2024 release notes.

  1. POST WorkItem, PUT WorkItem
  2. PATCH WorkItem
  3. GET a list of WorkItems, sorting and filtering the list
  4. GET a single Work Item

POST WorkItem and PUT WorkItem

Endpoint: https://api.karbonhq.com/v3/WorkItems

When used with POST and PUT methods, this end point now allows you to optionally specify a DeadlineDate property.

Valid values for DeadlineDate are null or an ISO8061 datestamp or timestamp, e.g. 2024-01-01 or 2024-01-01T00:00:00Z.

Example use case

You want to create a Work Item with a DeadlineDate of February 1, 2024.

Include the following JSON object in the request payload:

"DeadlineDate": "2024-02-01"

Making a POST request to: https://api.karbonhq.com/v3/WorkItems

PATCH WorkItem

Endpoint: https://api.karbonhq.com/v3/WorkItems

When used with PATCH methods, this end point now allows you to update only the DeadlineDate property, avoiding the need to update the whole Work Item record.

As per the POST and PUT requests, valid values for DeadlineDate are null or an ISO8061 date stamp or time stamp, e.g. 2024-01-01 or 2024-01-01T00:00:00Z.

Example use case

You want to create a Work Item with a DeadlineDate of February 2, 2024.

Use the following JSON as the complete request payload:

{"DeadlineDate": "2024-02-02"}

Making a PATCH request to: https://api.karbonhq.com/v3/WorkItems/{WorkItemKey}

GET WorkItems

Endpoint: https://api.karbonhq.com/v3/WorkItems

When used with GET method, this end point will return a DeadlineDate property for each Work Item returned.

Example use case

You want to retrieve a list of WorkItems with a DeadlineDate on or after March 1, 2024. The list should be sorted with by DeadlineDate ascending (dates are ordered from March 1, 2024 into the future) https://api.karbonhq.com/v3/WorkItems?$filter=DeadlineDate ge 2024-03-01&$orderby=DeadlineDate

This will return a JSON response with a list of work items as the payload, including the DeadlineDate property for each Work Item returned. {"DeadlineDate": "2024-03-01T00:00:00Z"}

GET WorkItem Endpoint: https://api.karbonhq.com/v3/WorkItems/{WorkItemKey}

When used with GET method, this end point will return a DeadlineDate property for the supplied WorkItemKey. This will be null if no DeadlineDate is set.

Example use case

You want to retrieve a Work Item and its DeadlineDate

Endpoint: https://api.karbonhq.com/v3/WorkItems/{WorkItemkey}

This will return a JSON response with a work item as the payload, including the DeadlineDate property with the date represented as an ISO8601 timestamp: "DeadlineDate": "2024-03-01T00:00:00Z"