March 18, 2024

The March 18, 2024 Karbon API release includes a new API endpoint to retrieve account specific information about Work Types, Contact Types and Work Statuses

1. GET Tenant Settings

GET TenantSettings

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

When used with GET method, this end point will return a collection of valid options for Work Types (used with WorkItem endpoints), Contact Types (used with Contacts and Organizations endpoints) and Work Statuses (used when setting or updating the PrimaryStatus and SecondaryStatus properties of WorkItems)

Refer to the TenantSettings API documentation for a full example of the response from this endpoint.

Example use case

You want to integrate a CRM system with Karbon: creating contact records in Karbon when you sign a new client and adding onboarding work.
You need:

• a list of valid Contact Types so that your API integration can perform a mapping of types from your CRM system to the ContactTypes used in Karbon

• a list of valid Work Types so that your API integration can assign the correct WorkType to the onboarding WorkItems

Making a call to https://api.karbonhq.com/v3/TenantSettings will return a JSON response with a collection of ContactTypes and a collection of WorkTypes , e.g.

{
"ContactTypes": [{"name": "Client", "ContactTypeKey": "3Qk8VS4LHyMb"}, ...],
"WorkTypes": [{"Name": "Accounting", "WorkTypeKey": "nTlQkTQnNz7", "AvailableStatuses": {...}}, ...]
}

Notes:

Values for Primary Work Statuses are controlled across all Karbon accounts - only Secondary status types can be edited.

Within Karbon, admin users can specify which Secondary statuses apply to which Work Types - meaning some statuses may not be valid for use with specific Work Types. The WorkTypes collection in the API response includes an applicable Primary status names and Secondary status keys. This allows API consumers to perform validation of a combination of Primary and Secondary statuses for a specific Work Type.

Because the names for items in the ContactTypes and WorkTypes collections are editable they are provided along with a Key. This key will remain unchanged even if the name is changed.