Manage compliance custom fields

When to use this. Compliance custom fields are admin-level definitions that extend the data model for certificates, institutes, and quality topics. You create a field once — choosing its type, allowed values, and whether it is mandatory or internal-only — and it then appears on every relevant record across your organisation. Use these endpoints to automate that setup, keep field definitions in sync with an ERP, or bulk-update a field library as regulations evolve.

The workflow

Custom fields are standalone definitions: create them, optionally deactivate or soft-delete them when they are no longer needed, and list them to build filter UIs or validate incoming data.

Create the field definitions

POST /api/compliance-custom-fields with an array of one or more field definitions. A single call creates all fields in one all-or-nothing transaction. Choose the type carefully — it cannot be changed after creation. For dropdown fields, pass allowedValues in the same request.

Retrieve a specific field

GET /api/compliance-custom-fields/{id} to fetch a single definition by its ID, including its current allowed values and active property flags.

List and filter fields

GET /api/compliance-custom-fields to page through all definitions. Filter by type, state, IsMandatory, or InternalOnly to build admin UIs or validate that an ERP code (userDefinedId) already exists before creating a duplicate.

Update or retire fields

PUT /api/compliance-custom-fields/{id} for a full replacement (including a new allowed-value list). To retire a field, either set state: inactive to hide it from new records, or DELETE /api/compliance-custom-fields/{id} to soft-delete it. Use the bulk PUT /api/compliance-custom-fields to mix updates and deletes in a single transaction.

Walkthrough

Create an allowedValue field called Facility Country with three options. The body is an array — one or many fields are created in a single all-or-nothing transaction.

curl -X POST "https://service.my.delogue.com/api/compliance-custom-fields" \
  -H "Accept: application/json" \
  -H "X-Auth-Token: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
  {
    "name": "Facility Country",
    "userDefinedId": "FAC-COUNTRY",
    "type": "allowedValue",
    "position": 3,
    "state": "active",
    "internalOnly": false,
    "isMandatory": true,
    "isMultiLine": false,
    "isSortByAllowedValueId": false,
    "maxChar": null,
    "allowedDecimals": 0,
    "parentCustomFieldId": null,
    "allowedValues": [
      {
        "id": null,
        "value": "China",
        "userDefinedId": "CN",
        "isDefaultValue": false
      },
      {
        "id": null,
        "value": "Bangladesh",
        "userDefinedId": "BD",
        "isDefaultValue": false
      },
      {
        "id": null,
        "value": "Turkey",
        "userDefinedId": "TR",
        "isDefaultValue": true
      }
    ]
  }
]'

const res = await fetch("https://service.my.delogue.com/api/compliance-custom-fields", {
  method: "POST",
  headers: {
    "Accept": "application/json",
    "X-Auth-Token": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify([
  {
    "name": "Facility Country",
    "userDefinedId": "FAC-COUNTRY",
    "type": "allowedValue",
    "position": 3,
    "state": "active",
    "internalOnly": false,
    "isMandatory": true,
    "isMultiLine": false,
    "isSortByAllowedValueId": false,
    "maxChar": null,
    "allowedDecimals": 0,
    "parentCustomFieldId": null,
    "allowedValues": [
      {
        "id": null,
        "value": "China",
        "userDefinedId": "CN",
        "isDefaultValue": false
      },
      {
        "id": null,
        "value": "Bangladesh",
        "userDefinedId": "BD",
        "isDefaultValue": false
      },
      {
        "id": null,
        "value": "Turkey",
        "userDefinedId": "TR",
        "isDefaultValue": true
      }
    ]
  }
]),
});
const { data } = await res.json();

{
  "status": "success",
  "code": "compliance_custom_fields_created",
  "data": [
    {
      "id": 29100,
      "name": "Facility Country",
      "userDefinedId": "FAC-COUNTRY",
      "type": "allowedValue",
      "state": "active",
      "position": 3,
      "maxChar": null,
      "allowedDecimals": 0,
      "parentCustomFieldId": null,
      "parentCustomFieldName": null,
      "allowedValues": [
        {
          "id": 160001,
          "value": "China",
          "userDefinedId": "CN",
          "properties": []
        },
        {
          "id": 160002,
          "value": "Bangladesh",
          "userDefinedId": "BD",
          "properties": []
        },
        {
          "id": 160003,
          "value": "Turkey",
          "userDefinedId": "TR",
          "properties": [
            "defaultValue"
          ]
        }
      ],
      "properties": [
        "mandatory"
      ]
    }
  ]
}

The response returns the created fields with their assigned IDs. Hold onto each id — use it when updating, deleting, or linking child fields under a nestedAllowedValue parent.

Field reference

Fields that matter most when creating or updating a compliance custom field:

Field	What it means at Delogue
`allowedDecimals`	Number of decimal places for numeric-type fields. Defaults to 0 (integer).
`allowedValues`	Initial set of selectable options for allowedValue or nestedAllowedValue fields. Null or omitted creates the field with no options.
`internalOnly`	When true, the field is visible to brand users only and hidden from supplier users. Defaults to false.
`isMandatory`	When true, the field must be filled in. Defaults to false.
`isMultiLine`	When true, text-type fields render as a multi-line textarea. Defaults to false.
`isSortByAllowedValueId`	When true, allowed values are sorted by insertion order rather than alphabetically. Defaults to false.
`maxChar`	Maximum character length for text-type fields. Null to leave unrestricted.
`name`	Display name of the compliance custom field. Required.
`parentCustomFieldId`	ID of the parent compliance custom field. Required for nestedAllowedValue child fields; null for all other types.
`position`	Display order within the compliance custom fields panel. Required.
`state`	Initial lifecycle state. Defaults to active.
`type`	Field type: allowedValue, date, text, nestedAllowedValue, numeric, or divider. Required.
`userDefinedId`	Customer-defined identifier for the field, used in ERP integrations. Null to leave unset.

PUT /api/compliance-custom-fields/{id} is a full replacement. Omitting isMandatory or internalOnly lands them as false. The bulk PUT /api/compliance-custom-fields supports state: deleted per item to mix updates and soft-deletes in a single transaction.

For a partial update, PATCH /api/compliance-custom-fields/{id} accepts an RFC 6902 JSON Patch document (Content-Type: application/json-patch+json) and touches only the paths you send — e.g. /isMandatory, /internalOnly, /name, /state. Unlike the full-replace PUT, a flag you do not patch is left unchanged. /position is read-only and state cannot be set to deleted.

Breaking change. On PUT /api/compliance-custom-fields and PUT /api/compliance-custom-fields/{id}, the request booleans internalOnly, isMandatory, isMultiLine and isSortByAllowedValueId are now non-nullable — they can no longer be sent as null. Because PUT is a full replace, omitting any of them writes false. Integrations that previously omitted a flag to leave it untouched must now send its current value on every PUT (or switch to PATCH, which only changes the paths you send).

Roles & permissions

Managing compliance custom fields requires the compliance permission on a designer (brand) account. In practice, this means the user must hold the CompanyAdmin role (and optionally Compliance Admin) — supplier accounts cannot create or modify custom field definitions. Fields marked internalOnly: true are not shown to supplier users anywhere in the platform (Classic or 2.0), but they are always returned via this API regardless of the calling user’s role.

When things go wrong

Errors use the standard envelope (status: "error", a code, and error.details[]). See Errors & responses for the full list of codes and how to resolve them. Common cases for compliance custom fields:

Scenario	HTTP	`code`
`position` is non-null on update	400	`validation_error.not_allowed`
Required field (`name`, `type`, `position`) missing on create	400	`validation_error.required_field`
Field ID not found or belongs to another organisation	404	`resource_error.compliance_custom_field_not_found`
`parentCustomFieldId` references a non-existent field	404	`resource_error.compliance_custom_field_not_found`

What to call next

Compliance categories

Group certificates by category before applying custom fields.

Size ranges

Another admin-level definition: the size sets that styles and items reference.

Style categories

Organise styles with categories — a similar admin setup pattern.

Authentication

How to get and send your X-Auth-Token API key.

Getting Started

Concepts

Guides

Manage compliance custom fields

The workflow

Walkthrough

Field reference

Roles & permissions

When things go wrong

What to call next

Compliance categories

Size ranges

Style categories

Authentication

​The workflow

​Walkthrough

​Field reference

​Roles & permissions

​When things go wrong

​What to call next

Compliance categories

Size ranges

Style categories

Authentication

The workflow

Walkthrough

Field reference

Roles & permissions

When things go wrong

What to call next