February 8, 2024
The February 8, 2024 Karbon API release includes two changes:
API access can be configured to allow access to Hidden and Private contacts.
The DeadlineDate property has been to the WorkItems API endpoint - this makes it possible to set, retrieve and update a deadline date on a WorkItem.
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 Work Items) 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, using Issue form linked here or in the header of this page.
Where a single API application is connected to multiple Karbon accounts, each Karbon account has it's 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.
POST
WorkItem,PUT
WorkItemPATCH
WorkItemGET
a list of WorkItems, sorting and filtering the listGET
a single WorkItem
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 WorkItem 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 aDeadlineDate
property for each WorkItem 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 WorkItem 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 aDeadlineDate
property for the supplied WorkItemKey. This will benull
if noDeadlineDate
is set.
Example use case
You want to retrieve a Work Item and it's DeadlineDate
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"