Skip to main content
When a call completes, FormBharo stores answers in two companion objects: form_data holds the raw values, and form_status records whether each question was answered, skipped, or never reached. Always read form_status alongside form_data — never rely on truthiness alone.

​
form_data: the values

The keys in form_data are question names. Each question has a name field set when the agent is configured; if you leave it blank, FormBharo generates one from the question wording. Use these names when mapping answers into your own system. The type of each value depends on the response_type configured for the question: A question that the caller actively declined to answer is stored as null — it is not omitted from the object. A missing key and a null value mean different things; see form_status below for how to tell them apart.

​
form_status: the per-field state

form_status has the same keys as form_data. Each value is one of three strings:
  • answered — the agent captured a valid answer for this question. The corresponding form_data value is the answer.
  • skipped — the question was asked but no answer was captured (the caller said nothing, declined, or it timed out). The corresponding form_data value is null.
  • empty — the question has not been reached yet, or its branch was never activated during the call. The corresponding form_data value is null.
Read form_status, not the truthiness of form_data. The values 0, "", and false are all real answers — they are truthy in some languages and falsy in others, but they represent captured data. A null in form_data could be a skipped question or an empty one — only form_status tells you which.

​
Before any answers are saved

GET /api/v1/data/{agent_id}/{conversation_id} returns {} until the first answer is written to the call record. This happens when the first question is successfully answered during the conversation. If you poll this endpoint immediately after a call starts, expect an empty object and retry.

​
Correcting an answer

If an answer was captured incorrectly — for example, a name was misheard — you can patch it directly without re-running the call:
This route requires no API key. It is an open endpoint, so you can call it from client-side code or a webhook without exposing your credentials.
Send an updates object containing only the fields you want to change:
Sending null as a value marks that field as skipped in form_status. The response is the full updated form_data and form_status objects. FormBharo validates the new values against the question’s response_type before saving. If validation fails, you receive a 400 response with an invalid_fields object listing every field that did not pass:

​
Example: form_data and form_status together

Here is what a completed call record looks like when one question was answered, one was skipped, and one was never reached:
  • full_name and age were answered — use their form_data values directly.
  • referral_source was asked but the caller did not answer — form_data is null and form_status is skipped.
  • preferred_date was never reached, likely because the call ended or its branch was not triggered — form_data is null and form_status is empty.