Updating the agent form remotely with update_fields

update_fields is the VICIdial Agent API function that writes new values into the customer information section on a logged-in Agent's screen. If an outside system knows more about the Lead than the agent currently sees — a corrected phone number, an email, a vendor code — update_fields pushes those values onto the live form so the agent works from the right data.

When you'd use it

The usual case is a screen-pop integration. Your CRM looks up the caller while the agent's Agent session is on the call, finds richer detail, and writes it back so the VICIdial form matches the CRM. Another is post-processing: a verification service confirms an address and you reflect that on the agent screen immediately. It's the counterpart to reading data out of the system — here you're pushing curated values in, field by field. You can also trigger the agent's script or form to reload in the same call so the new values show without the agent refreshing.

How the call works

sequenceDiagram
  participant App
  participant API as api.php
  participant V as VICIdial
  participant Agent
  App->>API: update_fields (agent_user, field=value...)
  API->>V: check agent has a lead on screen
  alt lead present and fields allowed
    V->>Agent: write fields into customer panel
    V-->>App: SUCCESS update_fields lead updated
  else no lead on screen
    V-->>App: ERROR agent_user does not have a lead on their screen
  end

VICIdial confirms the agent has a lead loaded, checks the API user is allowed to modify lead information, then writes only the fields you sent. It echoes the changes back so you can confirm exactly what landed.

Parameters

• agent_user — the login of the agent whose form you're updating. Required.
• Lead data — populate at least one. Fields include first_name, last_name, middle_initial, title, phone_number, phone_code, alt_phone, email, address1, address2, address3, city, state, province, postal_code, country_code, comments, source_id, vendor_lead_code, gender, date_of_birth, security_phrase, gmt_offset_now, rank, and owner. Only the fields you send are modified.
• Optional non-lead triggers — formreload, scriptreload, script2reload, emailreload, chatreload. These reload the matching panel, but still require a lead to be on the agent's screen.

An example call

http://server/agc/api.php?source=test&user=6666&pass=1234&function=update_fields&agent_user=6666&vendor_lead_code=1234567&address1=

A success echoes the write: SUCCESS: update_fields lead updated - 6666|1234|87498|vendor_lead_code='1234567',address1=''. Notice it shows every field it touched, including the empty address1, so you can verify nothing extra changed. The errors are precise: ERROR: agent_user does not have a lead on their screen - 6666|1234 when no lead is loaded, ERROR: user is not allowed to modify lead information - 6666|1234 for a permission miss, and ERROR: no fields have been defined - 6666 if you forgot to send any field at all.

Gotchas

Two things trip people up. First, there must be a lead on the agent's screen — update_fields has nothing to write to mid-pause or between calls. Second, most special characters are rejected; single quotes are allowed, but throwing arbitrary punctuation into a field will get it stripped or refused, so sanitize before you send. If you only want to refresh a panel and not change data, the related refresh_panel function does that without a lead being required. For where update_fields fits in the bigger picture, see the VICIdial API and AGI overview, and for how it differs from the data-side update calls read Non-Agent API vs Agent API.

update_fields is the cleanest way to keep the agent's view in sync with whatever system owns your customer data. If you want a managed VICIdial box that provisions in under 40 seconds to wire your CRM into, see our plans.