{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/beel-es/json-schema/beel-es-custom-field-list-response-schema.json",
  "title": "CustomFieldListResponse",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/beel-es-companycustomfields-api-openapi.yml#/components/schemas/CustomFieldListResponse",
  "allOf": [
    {
      "$ref": "#/$defs/SuccessResponse"
    },
    {
      "type": "object",
      "properties": {
        "data": {
          "type": "object",
          "required": [
            "custom_fields"
          ],
          "properties": {
            "custom_fields": {
              "type": "array",
              "items": {
                "$ref": "#/$defs/CustomField"
              }
            }
          }
        }
      }
    }
  ],
  "$defs": {
    "CustomField": {
      "type": "object",
      "description": "A custom field of the company's invoices, with the options that apply to the query that returned it.",
      "required": [
        "id",
        "key",
        "label",
        "show_on_pdf",
        "suggest_values",
        "is_archived",
        "options"
      ],
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid",
          "description": "Unique identifier of the custom field."
        },
        "key": {
          "$ref": "#/$defs/CustomFieldKey"
        },
        "label": {
          "type": "string",
          "minLength": 1,
          "maxLength": 100,
          "description": "Name people see next to the value, on screen and, if `show_on_pdf`, on the PDF."
        },
        "show_on_pdf": {
          "type": "boolean",
          "description": "Whether the PDF of the invoice prints this field, in a block of its own under the notes. It applies to invoices saved from then on: an invoice keeps the setting it was saved with."
        },
        "suggest_values": {
          "type": "boolean",
          "description": "Whether the field offers the values already used as options. With `true`, saving an invoice reuses an equivalent option or adds the value as a new one. With `false`, for a value that changes on every invoice such as an order number, the invoice stores the text as sent (without leading and trailing spaces), no option is created, and `options` comes back empty. Turning it off deletes no option: the existing ones are kept, can still be listed and managed under `GET /v1/companies/{company_id}/custom-fields/{key}/options`, and are offered again when it is turned back on."
        },
        "is_archived": {
          "type": "boolean",
          "description": "An archived field cannot be added to new invoices and is left out of listings unless `include_archived=true`. Invoices that already carry it keep it."
        },
        "options": {
          "type": "array",
          "description": "The options of this field that apply to the query: the common ones plus, when the query names a `customer_id`, the ones of that customer. Archived options appear only with `include_archived=true`. Always empty when `suggest_values` is `false`. To page through every option of the field, of every customer, use `GET /v1/companies/{company_id}/custom-fields/{key}/options`.",
          "items": {
            "$ref": "#/$defs/CustomFieldOption"
          }
        }
      }
    },
    "CustomFieldKey": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "pattern": "^[a-z0-9_]{1,64}$",
      "description": "Identifier of the custom field within the company, chosen when the field is created: lowercase letters, digits and `_`, up to 64 characters. It never changes. BeeL. gives it no meaning of its own."
    },
    "CustomFieldOption": {
      "type": "object",
      "description": "A value of a custom field, offered when filling it in. An option belongs to one customer or, without `customer_id`, is common to every customer of the company.",
      "required": [
        "id",
        "value",
        "customer_id",
        "is_archived"
      ],
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid",
          "description": "Unique identifier of the option."
        },
        "value": {
          "type": "string",
          "minLength": 1,
          "maxLength": 255,
          "description": "Text of the option, exactly as it is shown and copied onto an invoice."
        },
        "customer_id": {
          "type": [
            "string",
            "null"
          ],
          "format": "uuid",
          "description": "Customer the option belongs to, or `null` for an option common to every customer. It is set when the option is created and never changes."
        },
        "is_archived": {
          "type": "boolean",
          "description": "An archived option is no longer offered and is left out of listings unless `include_archived=true`. Invoices that already carry its text keep it."
        }
      }
    },
    "ResponseMeta": {
      "type": "object",
      "properties": {
        "timestamp": {
          "type": "string",
          "format": "date-time"
        },
        "request_id": {
          "type": "string"
        }
      }
    },
    "SuccessResponse": {
      "type": "object",
      "description": "The envelope every successful JSON response of the BeeL. API is wrapped in. There are no\nbare resources in v1 and none are planned: the payload always hangs off `data`.\n\n- A **single resource** is an object in `data`.\n- A **collection** hangs off a named key inside `data`, together with its `pagination`,\n  also inside `data` — `data: {invoices: [...], pagination: {...}}`.\n- A collection carries `pagination` unless its operation declares itself a **closed\n  catalogue**: a fixed, bounded list with nothing to page through. The declaration is\n  explicit in the operation; a missing `pagination` is never something to infer.\n- `GET /v1/accounts` pages by cursor (`data: {accounts: [...], next_cursor}`). It is a\n  documented variant of pagination, not another envelope.\n\nPutting the array straight into `data` with `pagination` as its sibling is the shape a v2\nwould adopt; v1 is not being flipped to it.\n",
      "required": [
        "success",
        "data"
      ],
      "properties": {
        "success": {
          "type": "boolean"
        },
        "data": {
          "description": "The payload. An object for a single resource; an object holding the named collection\n(and its `pagination`) for a listing. Never a bare array at this level in v1.\n"
        },
        "meta": {
          "$ref": "#/$defs/ResponseMeta"
        }
      }
    }
  }
}