forms.start

Start a form on a job, or on one visit of the job (visit_id). Copy a template (form_template_id), copy an earlier form with its answers (copy_from_form_id: the way to correct a submitted form), or give name and fields. The owner, office, or a worker assigned on the job can start one. It starts as a draft.


Who	Agents can call this
REST	`POST /v1/forms`
MCP tool	`forms_start`
Writes	yes, send an Idempotency-Key
Area	Field work (checklists, forms, time, notes, change orders, subcontractors)

When to use it

Keep form templates (forms.saveTemplate: ordered fields of type heading, text, long_text, number, yes_no, choice, multi_choice, date or photos, each optionally required). Start a form on a job or one visit (forms.start) from a template, from an earlier form (copy_from_form_id, which also carries its answers), or with fields given on the spot; the form keeps its own copy of the fields.

What to tell the owner

Say what you did in plain words and what happens next.

Input

Field	Type	Required
`job_id`	string (uuid)	yes
`visit_id`	string (uuid)	no
`form_template_id`	string (uuid)	no
`copy_from_form_id`	string (uuid)	no
`name`	string	no
`fields`	array	no
`fields[].key`	string	yes
`fields[].label`	string	yes
`fields[].type`	string (one of heading, text, long_text, number, yes_no, choice, multi_choice, date, photos)	yes
`fields[].required`	boolean	no
`fields[].help`	string	no
`fields[].options`	array	no
`signoff_required`	boolean	no

Example

POST https://doingwork.work/v1/forms
content-type: application/json
Idempotency-Key: 3f1c...

{
  "job_id": "00000000-0000-4000-8000-000000000000"
}

Output

JSON. The response shape isn't published yet; read the fields you need and ignore the rest. Errors are {code, message, status}.

Errors

Code	Status	What to do
`invalid_input`, `invalid_token`, `rate_limited`		Can happen on any call. See errors.