How to set custom fields when you add a lead by API

Turn on custom_fields in the add_lead call and pass your own list-specific data alongside the standard name and phone fields.

VICIdial's standard lead has slots for name, address, phone, and email, but your business probably tracks more than that: a policy number, a quote amount, a referral code. Custom fields hold that extra data, and the add_lead call from the Non-Agent API can fill them in as it inserts the record (Application Programming Interface) Non-agent API.

A custom field is an extra column you define on a list so agents and reports can store data that does not fit the built-in slots Custom field. Each field has a label, and that label is the key you use in the API URL. The field belongs to a specific lead list, the named bucket of records a campaign dials Lead list.

Flip the switch, then pass the field

Custom field handling is off by default. You turn it on with custom_fields=Y. After that, you add each field to the URL using its exact label. If your field's label is favorite_color, you append &favorite_color=blue. There is no separate setup in the API call; VICIdial reads the labels defined on the list and matches them.

curl "https://your-server/vicidial/non_agent_api.php?source=mycrm&user=6666&pass=1234&function=add_lead&phone_number=7275551212&phone_code=1&list_id=999&custom_fields=Y&favorite_color=blue"

On a clean run you get two lines back: the normal lead-added success, then a notice that the custom values went in:

SUCCESS: add_lead LEAD HAS BEEN ADDED - 7275551111|6666|999|193716|-4
NOTICE: add_lead CUSTOM FIELDS VALUES ADDED - 7275551111|1234|101

When custom values quietly do not save

flowchart TD
  A[add_lead request] --> B{custom_fields=Y?}
  B -- No --> C[Notice: custom fields disabled]
  B -- Yes --> D{Fields defined on list?}
  D -- No --> E[Notice: no custom fields for list]
  D -- Yes --> F{Field labels match?}
  F -- No --> G[Notice: no fields defined]
  F -- Yes --> H[Custom field values added]

The notices tell you exactly why nothing saved. CUSTOM FIELDS DISABLED means you forgot custom_fields=Y. NO CUSTOM FIELDS DEFINED FOR THIS LIST means the list ID you targeted has no custom fields set up yet. NO FIELDS DEFINED means you turned the flag on but did not pass any matching labels.

Notice that custom field problems come back as notices, not hard errors. The lead still gets added; only the custom values are skipped. That is easy to miss if you only check whether the call succeeded, so read the second line of the response, not just the first. Treat the CUSTOM FIELDS VALUES ADDED notice as your real confirmation that the extra data landed.

Custom fields are where your loader carries data straight out of your own system. If you are pushing records from a customer database, your contact relationship manager, the software your team uses to track customers (CRM), can map its columns to VICIdial field labels CRM. Pass each one as a URL parameter on the same add_lead call, and the agent sees a quote amount or an account number on screen the moment the call connects, with no copy-paste in between.

Leave entry_list_id alone. The API lets you override it, but doing so points custom data at the wrong list and can break custom fields entirely. The documentation flags it as a know-what-you-are-doing setting for a reason. When custom_fields is set to Y, the override will not work anyway.

One more habit: spaces in values need a plus sign. Send &notes=needs+a+call+back, not raw spaces. The same encoding rule applies to standard fields like address and city.

If you have not loaded a lead by API before, walk through how to push a lead with add_lead first. For the wider map of API and AGI functions, read the VICIdial API and AGI overview.

Carrying your own data fields into the dialer is what makes scripts and reports useful. Every VICIfast plan gives you a fully API-enabled VICIdial box in under a minute, ready to take your custom fields on the first call.