Custom Fields API

A custom field (cbcfc_...) is a field your organization defines on top of Coverbase’s built-in ones: a risk exception owner, an internal tier, a review date. This API lets an integration discover which fields exist and read the values set on your records. Values are returned on vendors, services, and assessments. Use GET /v1/custom-fields first to learn the config_id, type, and allowed options behind each value. All endpoints are org-scoped to the API key. See API conventions for shared behavior.

Method	Path
`GET`	`/v1/custom-fields`
`POST`	`/v1/custom-fields/values`

Definitions themselves are managed in the Coverbase dashboard. This API reads them, and reads or writes the values set against your records.

List custom field definitions

GET

GET /v1/custom-fields

Query parameters

string

Only return fields that apply to this object type. One of vendor, service, assessment, control, eval, contract, task, review, engagement. An unrecognized value returns 422.

boolean

Include fields your organization has disabled. Default false.

Example request

cURL

curl -X GET "https://sandbox.api.coverbase.app/v1/custom-fields?target=vendor" \
  -H "Authorization: Bearer ak_live_xxx"

Example response

{
  "items": [
    {
      "id": "cbcfc_4f2a9c1b7d3e0a6b8c5d2e9f1a4b7c0d",
      "field_name": "Risk Exception Owner",
      "field_type": "user",
      "enabled": true,
      "applies_to": ["vendor"],
      "options": [],
      "created_at": 1749168000,
      "updated_at": 1749168000
    },
    {
      "id": "cbcfc_8b1e4a7d0c3f6a9b2e5d8c1f4a7b0e3d",
      "field_name": "Exception Status",
      "field_type": "select",
      "enabled": true,
      "applies_to": ["vendor", "engagement"],
      "options": [
        { "label": "Open", "color": "amber" },
        { "label": "Closed", "color": "green" }
      ],
      "created_at": 1749168000,
      "updated_at": 1752019200
    }
  ],
  "total": 2
}

Response fields

string

The field’s config_id (cbcfc_...). This is the value that appears as config_id on each custom field value.

string

The display name your organization gave the field. Names can be renamed at any time, so match on id rather than field_name.

string

One of string, number, boolean, date, user, select, multiselect. Determines the shape of value wherever this field appears.

boolean

Whether the field is currently in use. Disabled fields are excluded unless you pass include_disabled=true, and their values never appear on records.

string[]

The object types this field can be set on.

object[]

For select and multiselect, the allowed label values (each with an optional color). Empty for every other type.

Where values appear

Set values are returned as a custom_fields array on these endpoints:

Endpoint	Values included
`GET /v1/vendors/{vendor_id}`	Always, for the vendor and each nested service
`PATCH /v1/vendors/{vendor_id}`	Always
`GET /v1/vendors`	Only when `include_custom_fields=true`
`PATCH /v1/vendors/{vendor_id}/services/{service_id}`	Always
`GET /v1/assessments/{assessment_id}`	Always

Listing vendors leaves values out by default so paging stays cheap; pass include_custom_fields=true when you need them.

Create responses return an empty custom_fields array, since a record has no values at the moment it is created.

Example

cURL

curl -X GET "https://sandbox.api.coverbase.app/v1/vendors?include_custom_fields=true&limit=50" \
  -H "Authorization: Bearer ak_live_xxx"

{
  "items": [
    {
      "id": "cbvndr_e448ba62882143f3ba0c140bb2e30162",
      "name": "Acme Supplier",
      "custom_fields": [
        {
          "config_id": "cbcfc_8b1e4a7d0c3f6a9b2e5d8c1f4a7b0e3d",
          "field_name": "Exception Status",
          "field_type": "select",
          "value": "Open"
        },
        {
          "config_id": "cbcfc_4f2a9c1b7d3e0a6b8c5d2e9f1a4b7c0d",
          "field_name": "Risk Exception Owner",
          "field_type": "user",
          "value": ["cbuser_3e6f9a2b5c8d1e4f7a0b3c6d9e2f5a8b"]
        }
      ]
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

Value types

value is typed by field_type:

`field_type`	`value` shape	Example
`string`	string	`"Renewal pending"`
`date`	string	`"2026-03-01"`
`select`	string, one of the field’s option labels	`"Open"`
`number`	number	`4`
`boolean`	boolean	`true`
`multiselect`	string array of option labels	`["PII", "PCI"]`
`user`	string array of user IDs (`cbuser_...`)	`["cbuser_3e6f..."]`

Resolve user IDs to names and emails through the Users API.

Set custom field values

POST

POST /v1/custom-fields/values

Sets one or more values on a single record. Only the fields you name change; anything already set and not listed is left alone. Writes are supported on the same records that return values: vendor, service, and assessment. A value can never be written somewhere it cannot be read back.

Body

string

required

vendor, service, or assessment.

string

required

The record to set values on. Must exist and belong to your organization, or the call returns 404.

object[]

required

One or more { "config_id": "cbcfc_...", "value": ... } entries. At least one is required, and a config_id may appear only once per request.

Note that you do not send field_type. The field’s own definition is authoritative, which is what stops a value being written into the wrong typed column.

Example request

cURL

curl -X POST "https://sandbox.api.coverbase.app/v1/custom-fields/values" \
  -H "Authorization: Bearer ak_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "target": "vendor",
    "object_id": "cbvndr_e448ba62882143f3ba0c140bb2e30162",
    "values": [
      { "config_id": "cbcfc_8b1e4a7d0c3f6a9b2e5d8c1f4a7b0e3d", "value": "Closed" },
      { "config_id": "cbcfc_4f2a9c1b7d3e0a6b8c5d2e9f1a4b7c0d", "value": ["cbuser_3e6f9a2b5c8d1e4f7a0b3c6d9e2f5a8b"] }
    ]
  }'

Example response

The record’s full custom_fields array after the write:

{
  "target": "vendor",
  "object_id": "cbvndr_e448ba62882143f3ba0c140bb2e30162",
  "custom_fields": [
    {
      "config_id": "cbcfc_8b1e4a7d0c3f6a9b2e5d8c1f4a7b0e3d",
      "field_name": "Exception Status",
      "field_type": "select",
      "value": "Closed"
    }
  ]
}

Clearing a value

Send null to empty a field. The field then drops out of custom_fields entirely, since only set values are returned.

{ "config_id": "cbcfc_8b1e4a7d0c3f6a9b2e5d8c1f4a7b0e3d", "value": null }

Validation

Every assignment in the request is checked before any of them is written, so a request naming one bad field changes nothing at all.

Status	When
400	A value’s type doesn’t match the field (`number` into a `string` field, and so on)
400	A `select` or `multiselect` value isn’t one of the field’s configured option labels
400	The field doesn’t apply to the given `target`, or has been disabled or archived
400	The same `config_id` appears twice in one request
404	The `object_id` or a `config_id` doesn’t exist in your organization

A write through this API behaves like a person editing the record in the dashboard: it takes precedence over values previously filled in by Coverbase’s automated extraction.

Behavior worth knowing

Only set values are returned. A record with nothing filled in returns an empty custom_fields array, and a field left blank on a record is omitted rather than returned with a null value.
Disabled and archived fields are hidden. Their values stay in Coverbase but never appear on API responses, so retiring a field cleanly removes it from your integration.
Match on config_id, not field_name. Display names are editable in the dashboard and change with no deploy.

Reading custom fields from an AI assistant

The Coverbase MCP server exposes the same data to AI assistants. Custom field values are already included in vendor, service, assessment, control, and engagement reads, and query_platform(kind="custom_fields") lists the definitions.

API Reference

Data Import & Export

Field reference

Reporting & Templates

Integration Workflows

AI, Agents, MCP

List custom field definitions

Query parameters

Example request

Example response

Response fields

Where values appear

Example

Value types

Set custom field values

Body

Example request

Example response

Clearing a value

Validation

Behavior worth knowing

Reading custom fields from an AI assistant

​List custom field definitions

​Query parameters

​Example request

​Example response

​Response fields

​Where values appear

​Example

​Value types

​Set custom field values

​Body

​Example request

​Example response

​Clearing a value

​Validation

​Behavior worth knowing

​Reading custom fields from an AI assistant

List custom field definitions

Query parameters

Example request

Example response

Response fields

Where values appear

Example

Value types

Set custom field values

Body

Example request

Example response

Clearing a value

Validation

Behavior worth knowing

Reading custom fields from an AI assistant