Answer Validation Rules: Enforce Format on Any Question

You can attach a validation object to any question to enforce the format of the answer. Validation runs in two places: during the call (triggering a retry if the answer doesn’t match), and when you manually correct an answer via PATCH /api/v1/agents/{agent_id}/conversations/{conversation_id}/form_data.

Validation object structure

Add a validation key to any question object and set its type to one of the rule names below. Some rules accept additional parameters in a rules sub-object.

{
  "validation": {
    "type": "<rule-name>",
    "rules": { ... }
  }
}

For rules that take no parameters (such as date), you can omit rules entirely.

Available rules

phone_number — 10-digit Indian phone number

Validates that the answer is a 10-digit Indian mobile or landline number.Parameters:

Key	Type	Description
`digits`	integer	The required digit count. Pass `10` for standard Indian numbers.

Behaviour:

Strips leading +91, 91, or 0 prefixes before counting digits.
Rejects numbers where all digits are the same (e.g., 9999999999).

{
  "validation": {
    "type": "phone_number",
    "rules": { "digits": 10 }
  }
}

min_length — minimum character count

Requires the answer to be at least a given number of characters long.Parameters:

Key	Type	Description
`min_length`	integer	The minimum number of characters required.

{
  "validation": {
    "type": "min_length",
    "rules": { "min_length": 5 }
  }
}

exact_num_digits — exact digit count

Requires the answer to contain exactly the specified number of digits, ignoring non-digit characters.Parameters:

Key	Type	Description
`digits`	integer	The exact number of digits required.

{
  "validation": {
    "type": "exact_num_digits",
    "rules": { "digits": 6 }
  }
}

number_range — numeric range

Requires the numeric answer to fall within a specified range. You can supply one or both bounds.Parameters:

Key	Type	Description
`min`	number	The minimum allowed value (inclusive). Optional.
`max`	number	The maximum allowed value (inclusive). Optional.

{
  "validation": {
    "type": "number_range",
    "rules": { "min": 0, "max": 120 }
  }
}

date — valid DD-MM-YYYY date

Requires the answer to be a valid calendar date in DD-MM-YYYY format.Parameters: None.

{
  "validation": {
    "type": "date"
  }
}

date_format — alias for date

An alias for the date rule. Behaves identically — use whichever name feels clearer in your configuration.Parameters: None.

{
  "validation": {
    "type": "date_format"
  }
}

date_today_or_past — today or earlier

Requires the answer to be a valid DD-MM-YYYY date that is today or in the past. Useful for fields like date of birth or symptom onset date.Parameters: None.

{
  "validation": {
    "type": "date_today_or_past"
  }
}

date_future — strictly after today

Requires the answer to be a valid DD-MM-YYYY date that is after today. Useful for appointment or follow-up dates.Parameters: None.

{
  "validation": {
    "type": "date_future"
  }
}

regex — custom regular expression

Validates the answer against a regular expression you define. Include a message to tell the agent (and the caller) what format is expected.Parameters:

Key	Type	Description
`pattern`	string	A valid regular expression.
`message`	string	A human-readable error message shown when the pattern does not match.

{
  "validation": {
    "type": "regex",
    "rules": {
      "pattern": "^[A-Z]{2}[0-9]{6}$",
      "message": "Must be two capital letters followed by six digits"
    }
  }
}

free_text — natural-language LLM rule

Describes a validation rule in plain English, enforced by the LLM during the call. Use this for rules that are difficult to express as a pattern — for example, requiring a valid Indian state name.Parameters:

Key	Type	Description
`description`	string	A plain-language description of what constitutes a valid answer.

{
  "validation": {
    "type": "free_text",
    "rules": { "description": "Must be a valid Indian state name" }
  }
}

The free_text rule is only enforced during the live call. It is not checked when you manually patch form data via PATCH /api/v1/.../form_data. Use a regex or other structural rule if you need server-side enforcement on manual edits.

Failure response

When validation fails during a PATCH /api/v1/agents/{agent_id}/conversations/{conversation_id}/form_data request, you receive HTTP 400. The response body identifies every field that failed:

{
  "error": "Validation failed",
  "invalid_fields": {
    "phone": {
      "value": "999",
      "normalized_value": "999",
      "error": "Must be 10 digits",
      "source": "phone_number"
    }
  }
}

object

A map of field names to failure details. Each entry describes one field that failed validation.

Show Fields in each invalid_fields entry

any

The raw value you submitted.

any

The value after any pre-processing (e.g., stripping a country code prefix from a phone number). This is the value the rule actually tested.

string

A human-readable explanation of why the value failed.

string

The rule type that rejected the value — e.g., "phone_number" or "number_range".

Nothing is saved if any field fails validation. Fix all reported fields and resubmit the entire patch.

Get Started

Core Concepts

Guides

Reference

Answer Validation Rules: Enforce Format on Any Question

Validation object structure

Available rules

Failure response

​Validation object structure

​Available rules

​Failure response

Validation object structure

Available rules

Failure response