Service fields

GET /v1/catalog-services/fields

Returns the catalog service field reference with labels, types, write flags and dictionaries of allowed values, plus the fields available for aggregation and the operations available in a batch request.

The reference contains 28 static service fields. Pass ?iblockId=<catalog ID> to also receive catalog properties of the form propertyNNN when Bitrix24 returns the dynamic field metadata successfully. Get the catalog ID from GET /v1/catalogs. Property values arrive in the GET /v1/catalog-services/:id response; their names and types are also available from GET /v1/catalog-product-properties.

The dateCreate, timestampX, dateActiveFrom, and dateActiveTo fields are not accepted in filter: the request returns 400 UNKNOWN_FILTER_FIELD before calling Bitrix24. These dates remain available in select and responses.

Parameters

Examples

curl — personal key

curl "https://vibecode.bitrix24.com/v1/catalog-services/fields?iblockId=25" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

curl "https://vibecode.bitrix24.com/v1/catalog-services/fields?iblockId=25" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

const res = await fetch('https://vibecode.bitrix24.com/v1/catalog-services/fields?iblockId=25', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data } = await res.json()
console.log('Fields:', Object.keys(data.fields).length)

JavaScript — OAuth application

const res = await fetch('https://vibecode.bitrix24.com/v1/catalog-services/fields?iblockId=25', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { success, data } = await res.json()

Response fields

data.fields is an object keyed by field name; each value contains the type, the write flags, a display label and — for fields with a fixed set of values — their dictionary. The set of keys is broken down in the table after the field list. data.aggregatable lists the fields for groupBy in aggregation. data.batch lists the operations available in a batch request.

¹ iblockId is writable on create only — in the reference it comes back with readonly: false and createOnly: true.

Field labels label and descriptions description arrive in English. Fields with a fixed set of values — previewTextType and detailTextType — also carry an enum dictionary: an array of { value, label }. Send value; label is meant for display.

Response example

Response without iblockId: static fields only, with the fields_partial warning.

{
  "success": true,
  "data": {
    "fields": {
      "id": {
        "type": "number",
        "readonly": true,
        "label": "Service identifier",
        "description": "Unique identifier of the catalog service."
      },
      "iblockId": {
        "type": "number",
        "readonly": false,
        "createOnly": true,
        "label": "Catalog ID",
        "description": "Catalog the service belongs to. Available values: GET /v1/catalogs. Set on create only — changing it via PATCH is rejected, a service cannot be moved between catalogs."
      },
      "type": {
        "type": "number",
        "readonly": true,
        "label": "Service type",
        "description": "Bitrix24 service type (7); set by Bitrix24 and read only."
      },
      "iblockSectionId": {
        "type": "number",
        "readonly": false,
        "nullable": true,
        "label": "Catalog section ID",
        "description": "Primary catalog section of the service; null when it is not linked to a section. Available values: GET /v1/catalog-sections."
      },
      "iblockSection": {
        "type": "object",
        "readonly": false,
        "writeOnly": true,
        "notReturned": true,
        "label": "Catalog sections",
        "description": "Array of catalog section IDs the service belongs to. Accepted on create and update only — on read the primary section arrives as the scalar iblockSectionId. Available values: GET /v1/catalog-sections."
      },
      "previewTextType": {
        "type": "string",
        "readonly": false,
        "label": "Preview text format",
        "description": "Format of previewText.",
        "enum": [
          { "value": "text", "label": "Plain text" },
          { "value": "html", "label": "HTML" }
        ]
      }
    },
    "aggregatable": [
      "iblockSectionId"
    ],
    "batch": [
      "create",
      "update",
      "delete"
    ]
  },
  "meta": {
    "warnings": [
      {
        "code": "fields_partial",
        "message": "Dynamic field metadata from Bitrix24 was unavailable; the response carries static schema fields only and some labels may be missing. Retry to obtain the complete set."
      }
    ]
  }
}

The example is trimmed to six fields — one each for the readonly and createOnly flags, the computed type, nullable, the writeOnly + notReturned pair and the enum dictionary. The static reference contains 28 fields; a successful response with iblockId contains the same static fields plus the catalog properties propertyNNN, and carries no fields_partial warning. For a catalog property, type arrives from Bitrix24 as is (productproperty), a multiple-value property carries multiple: true, and when Bitrix24 returned a value dictionary or a default, the keys values, items and default are present too.

Error response example

401 — the key was not passed:

{
  "success": false,
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key required. Pass via X-Api-Key header."
  }
}

Errors

For the full list of common API errors, see Errors.

Known specifics

Catalog properties require iblockId. Without a catalog ID, the response contains static fields and fields_partial. With ?iblockId=<catalog ID>, a successful Bitrix24 response adds propertyNNN properties to the reference and the warning is absent. If Bitrix24 does not return the dynamic fields, the static response with the warning is preserved.

Some fields are not returned in the list by default. The symbolic code code, the external code xmlId, the sort order sort, the VAT rate vatId, the texts, the images and the propertyNNN properties are not returned in the GET /v1/catalog-services response without an explicit ?select=. List the names you need in select to get them in the list. The single-service response, GET /v1/catalog-services/:id, always returns them.

See also

• List services
• Create a service
• Get a service
• Catalog product properties
• Catalog products
• API reference