Answers and typed questions

Each item in a submission’s needs and in /requirements has a key and an answer.type:

Type	Send	Tidied to
`text`	Any text	As sent
`number`	`120` or `1,200`	`1200`
`money`	`$1,200,000`	`1200000`
`percent`	`35` or `35%`, 0 to 100	`35%`
`yes_no`	`yes` / `no` / `y` / `n`, optionally with a short explanation	`Yes — fenced and gated`
`choice`	One of `answer.options` (any case)	The option as written
`date`	`2026-12-15` or `12/15/2026`	`2026-12-15`
`file`	Not an answer: upload a document

PATCH /submissions/{id}/answers
{ "answers": [ { "key": "hours", "value": "11am to midnight, 7 days" },
               { "key": "capacity", "value": "120" } ],
  "fields":  { "annual_payroll": 640000, "years_in_business": 12 } }

{ "answered": ["hours", "capacity"], "rejected": [], "unmatched": [], "upload_instead": [],
  "fields_filled": ["annual_payroll", "years_in_business"], "fields_kept": [],
  "needs": [ "… what's still open …" ] }

How answers are handled

One answer per key fills every open request item and checklist item with that key.
Answers are marked “received from the agent” for a broker to verify, and a note with every answer is added to the file.
Answers that don’t fit the type come back in rejected with the reason and aren’t saved.
Keys not asked on this file come back in unmatched (they’re still kept in the file note).
Document items need an upload; answering them with text says so in upload_instead.
fields only fill blanks: annual_revenue, annual_payroll, tiv, years_in_business, subcontractor_costs, naics_code, class_description, operations_description, requested_limits, prior_carrier, expiring_premium, target_premium. Anything already on file is kept and listed in fields_kept.

Answer in plain sentences

When the answers come from a person, not a form, send them as message and Valjean maps them to the open items:

PATCH /submissions/{id}/answers
{ "message": "Seats 120, open 11 to midnight every day. Payroll is $640K and they've been in business 12 years." }

{ "answered": ["capacity", "hours"], "fields_filled": ["annual_payroll", "years_in_business"],
  "from_message": { "answers": [ { "key": "capacity", "value": "120" }, { "key": "hours", "value": "11am to midnight, 7 days" } ],
                    "fields": ["annual_payroll", "years_in_business"], "not_understood": [] },
  "…": "… the rest as above …" }

Only what the message says is used: nothing is guessed. Anything it can’t place comes back in from_message.not_understood.
What’s read goes through the same type checks as answers sent by key, and a broker confirms it all the same way.
You can mix: anything you also send by key in answers or fields wins over what was read from the message.
409 ai_off means plain-sentence answers aren’t switched on for your account yet; send answers by key. 503 ai_unavailable means try again shortly.

What underwriters will ask

GET /submissions/{id}/flags runs the checks Valjean’s brokers see on the file, such as payroll given as one lump sum, no answer on whether subcontractors are insured, gaps or stale loss runs, and large losses without detail. Each flag comes with a plain question to answer now:

{ "flags": [ { "key": "loss_runs_gap", "severity": "high",
               "title": "Loss runs cover 3 of the 5 years needed",
               "question": "Can you send currently valued loss runs for the two earlier years…?" } ] }

It’s read-only and drawn only from your own file. Answering ahead of time (by key, as a message, or with an upload) usually saves a round trip with the market.