Skip to content
AM

Declaring custom fields for your tenant

Substrate field declarations are currently an integration-admin workflow. InBlack does not yet provide a tenant settings page or an MCP tool for creating them.

Before you declare a field

Confirm three things:

  1. The data does not already have a native field.
  2. The target is one of the supported substrate entity types.
  3. Your integration can authenticate to the tenant-scoped Accounting API.

The supported physical targets are crm_contact, crm_company, crm_activity, commerce_order, commerce_product, commerce_fulfillment, and marketing_campaign.

Submit the complete schema

POST /api/entity-schema accepts the full proposed field list for one entity type. It is not a single-field append operation. Preserve existing declarations when adding a field.

Each declaration includes a snake-case name, a type, and optional required, default, validation, and indexed values. Supported types are text, rich_text, number, money, date, boolean, picklist, multi_select, reference, and formula.

Ask your integration administrator to review the response before changing records. It reports whether the change is additive or breaking and which schema version became active.

Handle breaking changes

Removing a field, changing a type, narrowing options, adding a requirement, or changing a formula/reference creates a breaking schema version. Existing values are not reinterpreted silently.

After activation, run POST /api/entity-schema/backfill until it returns has_more: false. Review the coerced and voided counts. A voided value could not satisfy the new declaration and must be corrected from the backfill audit record if it is still needed.

Index only proven query fields

text, number, money, date, boolean, and picklist can be promoted with indexed: true. The limit is eight promoted fields per schema. Use promotion for established filter and sort needs, not as a default on every field.

Commerce fields are separate

For product-group-specific catalog attributes, use the Commerce field-definition UI instead. Those definitions do not create substrate fields and do not synchronize with them.

See Custom fields for the exact API body and validation contract.