VICIdial custom fields: dynamic tables, APIs and migration safety

Start with the list, not a guessed column

Fast answer: each VICIdial list (a named lead collection) can have one custom-field set, with definitions in vicidial_lists_fields and values in a dynamically created custom_<list_id> table. An API is an application programming interface: inspect both tables on the target before reading, importing, or changing data.

This is a schema decision deep dive, not an exact Admin UI how-to. Names, types, options and defaults are generated at runtime, and the demonstrated system has source support but its custom-fields feature flag is disabled. Source presence is evidence of implementation, not proof that a target has enabled or configured it.

Terms are defined in vicidial-terminology-for-complete-beginners.

• Prerequisite: use an authorized read-only database account and an inactive synthetic test list.
• Non-goal: do not alter production definitions, values, imports or schema from this article.
• Record revision, database engine/version, timezone and authorized test-list ID.
• Capture sanitized SHOW CREATE TABLE and SHOW INDEX output.

Design fields as an interface contract

Choose stable field names, bounded values and explicit required/default behavior before an import template or downstream integration exists. A label is for people; a field name becomes a dependency for loaders, forms, exports and any approved API client.

Use the card below in a change ticket before creating a test field. FIELD_NAME is a stable machine-readable name, TYPE is the approved input type, and SENSITIVE is a data-classification decision. Success is a complete, owner-approved card; a blank owner, retention rule or allowed value means stop before configuration.

Avoid placing secrets, payment data, health data or free-form sensitive notes into call URLs or casually exported custom fields. Document ownership, retention and masking before a field becomes operationally relied upon.

• Validate label, field name, type, options, length and default in a test list.
• Test agent display and approved webform/script consumers.
• Have the privacy owner approve any sensitive-data purpose.

FIELD_NAME: preferred_contact_windowTYPE: SELECTALLOWED_VALUES: morning | afternoonSENSITIVE: noOWNER: operationsRETENTION: approved policy reference

Prove the write path with synthetic data

Use the documented Non-Agent API function and target revision rather than constructing parameter names from a database column. API behavior, permissions and output modes vary by function; a successful HTTP response is not enough evidence of the intended custom-field write.

Start on an inactive test list with a synthetic lead, then verify the standard lead record, the matching custom row and the agent-facing result. URL-encode values at the client boundary and treat plain-text ERROR responses as failures even when a requested format is JSON.

SHOW CREATE TABLE vicidial_lists_fields;SHOW CREATE TABLE custom_<LIST_ID>;SHOW INDEX FROM custom_<LIST_ID>;

Make list copies and renumbers real migrations

Copying a list or changing its list ID changes the schema relationship as well as lead membership. Inventory definitions, values, import mappings, exports, callbacks, campaign eligibility and any external consumer before moving a production population.

Build a deterministic mapping from old list and field names to new list and field names. Rehearse the mapping on synthetic data, compare non-sensitive counts and field null rates, and stop if the target schema differs from the approved plan.

• Freeze or isolate the test population during the rehearsal.
• Validate an import, an API update and an agent edit after migration.
• Keep the original list untouched until acceptance is complete.

Back up both halves and define the stop point

A lead-table backup without the dynamic table, definitions and mappings is incomplete. Take a restorable, access-controlled backup and verify restoration into an isolated environment before a broad alteration or migration.

Stop and roll back when schema comparison, expected counts, sample reads or agent rendering disagree. Independent verification means a reviewer who did not perform the change compares the approved mapping, backup evidence and sanitized before/after totals.

• Include definitions, custom tables and relevant loader mappings in backup scope.
• Record evidence state: source present, demo enabled/disabled, or independently tested.
• Run equivalent tests on every production revision and list family before rollout.