Working with Custom Fields

Custom fields let you store additional structured data against Contacts and Organizations. They support several data types including free text, numbers, dates, booleans, lists, and references to Karbon users (Colleague fields).

Terminology note: In the Karbon API, Contact refers to what Karbon calls a Person in the UI. Organization means the same in both. Throughout this guide, “entity” means either a Contact (Person) or an Organization.

Field Types

Listing Custom Field Definitions

GET https://api.karbonhq.com/v3/CustomFields
Authorization: Bearer {token}
AccessKey: {key}

This returns all field definitions, including their Key values you’ll need to set values.

Creating a Custom Field Definition

POST https://api.karbonhq.com/v3/CustomFields
Authorization: Bearer {token}
AccessKey: {key}
Content-Type: application/json

{
  "Name": "Industry",
  "Type": "ListSingleSelect",
  "Options": ["Technology", "Healthcare", "Finance", "Legal", "Other"]
}

For a Colleague (user reference) field:

{
  "Name": "Client Partner",
  "Type": "Colleague"
}

Reading Custom Field Values for an Entity

GET https://api.karbonhq.com/v3/CustomFieldValues/3Nb8jKpL5tQR
Authorization: Bearer {token}
AccessKey: {key}

Where {EntityKey} is the ContactKey (a Person in Karbon) or OrganizationKey.

Response:

{
  "EntityKey": "3Nb8jKpL5tQR",
  "CustomFieldValues": [
    {
      "Key": "4rRS8QdFP5q7",
      "Name": "Industry",
      "Type": "ListSingleSelect",
      "Value": ["Technology"]
    },
    {
      "Key": "2hdBRYV62ZFp",
      "Name": "Client Partner",
      "Type": "Colleague",
      "Value": ["3v9YJmt55hLY"]
    }
  ]
}

Setting Custom Field Values

Warning: PUT replaces all custom field values for the entity. Any field you omit will be cleared. Always GET the current values first, apply your changes, then PUT the full set back.

PUT the entire set of custom field values for an entity:

PUT https://api.karbonhq.com/v3/CustomFieldValues/3Nb8jKpL5tQR
Authorization: Bearer {token}
AccessKey: {key}
Content-Type: application/json

{
  "EntityKey": "3Nb8jKpL5tQR",
  "CustomFieldValues": [
    {
      "Key": "4rRS8QdFP5q7",
      "Name": "Industry",
      "Type": "ListSingleSelect",
      "Value": ["Healthcare"]
    },
    {
      "Key": "2hdBRYV62ZFp",
      "Name": "Client Partner",
      "Type": "Colleague",
      "Value": ["3v9YJmt55hLY"]
    }
  ]
}

Resolving Colleague Field Values

Colleague fields store a UserKey, not a name. To resolve the user’s name:

GET https://api.karbonhq.com/v3/Users/3v9YJmt55hLY
Authorization: Bearer {token}
AccessKey: {key}

To find the right UserKey to assign, list users and filter:

GET /v3/Users?$filter=EmailAddress eq 'marcus.okonkwo@example.com'

Deleting a Custom Field Definition

Deleting a field definition removes the field and all its values from all entities:

DELETE https://api.karbonhq.com/v3/CustomFields/{CustomFieldKey}
Authorization: Bearer {token}
AccessKey: {key}

This is irreversible — confirm before deleting.