May 1, 2025

Create Custom Field Definition

A new Custom Fields API endpoint is now available to create custom field definitions via a call to

This allows clients to define new custom fields for use across the platform, including text, list, and multi-select field types.

Example Request:

JSONCopyCopied!
{
  "Name": "Example Custom Field",
  "Type": "Text",
  "IsVisibleToContacts": true,
  "IsVisibleToOrganizations": true
}

The following field types are currently supported:

• JSONCopyCopied!

  Text
  – Free-text input
• JSONCopyCopied!

  Number
  – Numeric value
• JSONCopyCopied!

  Date
  – Date value
• JSONCopyCopied!

  Boolean
  – True/false
• JSONCopyCopied!

  Colleague
  – Reference to a user profile
• JSONCopyCopied!

  ListSingleSelect
  – Single-select from a predefined list of options
• JSONCopyCopied!

  ListMultipleSelect
  – Multi-select from a predefined list of options

Fields created through this endpoint are specific to a single Karbon account and immediately available for assignment to Contacts and Organizations. Once created, field definitions are immutable and cannot be edited via public API. Custom field definitions can be deleted and re-created, but this will result in the loss of defined values on Contacts and Organizations.

Get Custom Field Definitions

The Custom Fields API can be queried to return all custom field definitions available to the current Karbon account using:

This endpoint returns metadata for each custom field, including its unique key, type, name, visibility settings, and available options (for list-based fields).

Example Response:

JSONCopyCopied!
{
  "@odata.context": "https://api.karbonhq.com/v3/$metadata#CustomFields",
  "@odata.count": 1,
  "value": [
    {
      "Key": "4qYlgxTD2vWH",
      "Name": "Example Custom Field",
      "Type": "Text",
      "IsVisibleToContacts": true,
      "IsVisibleToOrganizations": true,
      "ListOptions": []
    }
  ]
}

The options for List fields (i.e.

and ) are included in the ListOptions array - each entry must be a string. This endpoint supports OData query parameters for filtering, sorting, and pagination.

All field definitions returned are scoped to the current tenant and can be used when assigning or updating custom field values.

Update Custom Field Values

The Custom Field Values API can be used to update custom field values for a specific entity via:

This allows clients to assign or modify custom field values for a given Contact or Organization, including support for text, number, date, boolean, and list-based field types.

Example Request:

JSONCopyCopied!
{
  "EntityKey": "4qYlgxTD2vWH",
  "CustomFieldValues": [
    {
      "Key": "5zYFUxTB3BFa",
      "Name": "Example Custom Field",
      "Type": "Text",
      "Value": [
        "Updated value"
      ]
    }
  ]
}

Values must match the expected data type for the field definition. For list-based fields, the

array must contain one or more valid option keys.

Validation is enforced based on the field's type and configuration. If a value is invalid, the request will return a

with a descriptive message. Upon success, the field values are immediately updated and visible in the UI and relevant API responses.

Important: The entire set of values for a list field must be provided—partial updates will overwrite the supplied values and erase CustomValues that are not supplied.

Get Custom Field Values

The Custom Fields API can now be queried to retrieve all custom field values for a specific entity using:

Example Response:

JSONCopyCopied!
{
  "@odata.context": "https://api.karbonhq.com/v3/$metadata#CustomFieldValues/$entity",
  "EntityKey": "4qYlgxTD2vWH",
  "CustomFieldValueDTOs": [
    {
      "Key": "3LV59lQw56SC",
      "Name": "Example Custom Field",
      "Type": "Text",
      "Value": ["Example value"]
    }
  ]
}

Note: If the field has no value set, the Value property will return an empty array. For list-based fields, the Value array will contain the selected option key(s).

Delete Custom Field Definition

A custom field definition can be deleted by calling:

Note: This permanently removes the definition from the Karbon Account and prevents it from being used in future updates. This operation is irreversible and should only be used when the field is no longer needed.

Once deleted the field will no longer appear in the UI or API responses for definitions.

A

response is returned on successful deletion