Build a FormBharo Voice Agent from Your Form Fields

FormBharo lets you turn any form — paper intake sheets, web surveys, clinical questionnaires — into a voice agent that asks questions out loud and saves the answers. This guide walks through the full process: mapping fields, adding a script, configuring conditional branches, and publishing.

Create a draft agent

Start by sending a POST /api/v1/agents request with at minimum a title and a questions array. The API returns a new agent in draft state along with its agent_id, which you’ll use in every subsequent request.

curl -X POST {FORMBHARO_URL}/api/v1/agents \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Clinic intake",
    "questions": [
      {
        "id": "full_name",
        "label": "What is your full name?",
        "response_type": "string"
      },
      {
        "id": "date_of_birth",
        "label": "What is your date of birth?",
        "response_type": "date"
      }
    ]
  }'

import requests

response = requests.post(
    "{FORMBHARO_URL}/api/v1/agents",
    headers={"Authorization": "Bearer <api-key>"},
    json={
        "title": "Clinic intake",
        "questions": [
            {
                "id": "full_name",
                "label": "What is your full name?",
                "response_type": "string",
            },
            {
                "id": "date_of_birth",
                "label": "What is your date of birth?",
                "response_type": "date",
            },
        ],
    },
)

agent = response.json()
agent_id = agent["agent_id"]

Map each field to a question type

Every question needs a response_type that tells FormBharo how to parse and store the caller’s spoken answer. Choose the type that matches the original form field.

`response_type`	What it stores	Extra options
`string`	Free-text answer	—
`number`	Numeric value	`number_format: "integer"` or `"decimal"`
`date`	Date, stored as `DD-MM-YYYY`	—
`boolean`	Yes/no answer	`boolean_labels` to customise the spoken options
`single-select`	One choice from a list	`options[]` — required
`multi-select`	One or more choices from a list	`options[]` — required

For single-select and multi-select, pass options as an array of strings. The agent reads the list aloud and maps the caller’s answer to the closest matching option.For number, omit number_format if the caller might say either integers or decimals; set it to "integer" or "decimal" when you know the expected format.

Add scripts

Scripts give the agent its opening and closing lines. Set them inside a scripts object on the agent body.

scripts.intro — What the agent says at the very start of the call, before the first question. Use this to greet the caller and explain the purpose of the call.
scripts.outro — What the agent says when all required questions have been answered and the call is complete.
scripts.outro_incomplete — What the agent says when the call ends before all questions are answered (for example, the caller hangs up early).

You cannot set outro_incomplete without also setting outro. Both must be present if you want to customise the incomplete ending.

{
  "scripts": {
    "intro": "Hi, I'm calling on behalf of City Clinic to complete your intake form. This will only take a couple of minutes.",
    "outro": "That's everything I need. Thank you for your time — we'll see you at your appointment.",
    "outro_incomplete": "It looks like we ran out of time. Our team will follow up to collect the remaining details."
  }
}

Add conditional branches

Branches let you skip or show groups of questions based on a caller’s earlier answer. The flow works in two parts:

Declare the branch — add an entry to the top-level branches array. Give it a unique id and a condition that references a question id and a rule.
Tag questions — set branch_id on every question that belongs to the branch. Those questions are only asked if the condition evaluates to true at runtime.

A condition supports three fields:

Field	Type	Meaning
`field`	string	The `id` of the question whose answer is evaluated
`equals`	string	Branch is active when the answer exactly matches this value
`present`	boolean	Branch is active when the answer is any non-empty value

present takes priority over equals. If both are set on the same condition, present is evaluated and equals is ignored.

Use equals to branch on a specific value (for example, only proceed if the caller answered “yes”). Use present to branch whenever the caller gave any answer at all, regardless of what it was.

{
  "branches": [
    {
      "id": "has_insurance",
      "condition": {
        "field": "insurance_status",
        "equals": "yes"
      }
    }
  ],
  "questions": [
    {
      "id": "insurance_status",
      "label": "Do you have health insurance?",
      "response_type": "boolean"
    },
    {
      "id": "insurance_provider",
      "label": "Who is your insurance provider?",
      "response_type": "string",
      "branch_id": "has_insurance"
    },
    {
      "id": "policy_number",
      "label": "What is your policy number?",
      "response_type": "string",
      "branch_id": "has_insurance"
    }
  ]
}

{
  "branches": [
    {
      "id": "has_referral",
      "condition": {
        "field": "referral_source",
        "present": true
      }
    }
  ],
  "questions": [
    {
      "id": "referral_source",
      "label": "Were you referred by someone?",
      "response_type": "string"
    },
    {
      "id": "referral_name",
      "label": "What is the name of the person who referred you?",
      "response_type": "string",
      "branch_id": "has_referral"
    }
  ]
}

Configure screening

Use end_call_values to end a call early when a caller gives a disqualifying answer. Supply an array of strings; if the agent records any of those exact values, it ends the call immediately and marks the conversation screened_out. Screened-out calls count as successes, not failures.

{
  "end_call_values": ["no", "not interested", "already completed"]
}

Screened-out calls appear in analytics separately from fully completed calls, so you can track the size of the disqualified cohort without it inflating your failure rate.

Publish

When your agent is ready, publish it with PUT /api/v1/agents/{agent_id}. Send the complete agent body — not just the changed fields — as the request body. The API validates the configuration and returns the published agent on success.

curl -X PUT {FORMBHARO_URL}/api/v1/agents/AGENT_ID \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Clinic intake",
    "questions": [ ... ],
    "scripts": { ... },
    "branches": [ ... ]
  }'

import requests

agent_body = {
    "title": "Clinic intake",
    "questions": [...],
    "scripts": {...},
    "branches": [...],
}

response = requests.put(
    f"{FORMBHARO_URL}/api/v1/agents/{agent_id}",
    headers={"Authorization": "Bearer <api-key>"},
    json=agent_body,
)

if response.status_code == 400:
    print("Validation failed:", response.json()["validation_issues"])
else:
    print("Published:", response.json())

If validation fails, the API returns 400 with a validation_issues array describing each problem. Fix every issue before retrying — partial saves are not supported.

Preview changes before saving

Before you publish a new version, you can review exactly what will change by calling POST /api/v1/agents/{agent_id}/diff-preview with the proposed agent body. The response contains an array of diff lines, each with a type field:

Type	Meaning
`add`	Line present in the new version but not the current one
`remove`	Line present in the current version but not the new one
`context`	Unchanged line shown for context
`hunk`	Separator between diff sections
`meta`	Header information about the diff

Use this endpoint in CI pipelines or review tools to catch unintended changes before they reach a live agent.

curl

curl -X POST {FORMBHARO_URL}/api/v1/agents/AGENT_ID/diff-preview \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Clinic intake", "questions": [ ... ] }'

See Agent Configuration for every field, Question Types for per-type options, and Branching for the full branch rules.

Get Started

Core Concepts

Guides

Reference

Build a FormBharo Voice Agent from Your Form Fields

Preview changes before saving

​Preview changes before saving

Preview changes before saving