Forms

The Forms API covers the whole life of a form: authoring and publishing it, delivering it to a specific recipient, collecting a response from a browser or your own application, and reading the reporting behind it. Two different kinds of endpoint appear here, and the difference matters:

Kind	Path shape	Who calls it	Authentication
Management	`/api/v2/accounts/{accountId}/forms/...`	Your backend	A scoped API key
Respondent	`/api/v2/forms/{publicCode}/...`	The person filling the form	None; the form’s own code and session

Respondent endpoints are deliberately unauthenticated so a browser can reach them. They are rate limited per form and per client, and a submission is bound to the published version it was served from.

All Forms operations are listed together under Forms in the API reference. Start with the path shape: account-scoped routes are for your backend; public-code routes are for the respondent experience. If you build forms only inside HueChat, the app already performs both flows and you do not need to call these endpoints yourself.

Before you start

Forms is a plan feature. If it is not enabled for the account, every management endpoint answers 402 with {"code": "plan_disabled", "feature": "forms"} rather than 403. Ask your HueChat contact to enable Forms & Surveys on the plan before integrating.

Create a scoped API key in HueChat → Account → Developer API with the least it needs. Key creation, rotation and usage remain inside the authenticated app:

Scope	Use it for
`forms:read`	List forms, read a definition, versions, assets
`forms:write`	Create, edit, publish, close, archive, restore, rotate the public link, upload assets, manage invitations
`contacts:read`	Required together with `forms:write` to issue an invitation for a contact
`reports:read`	Required together with `forms:read` for reports, responses, invitation reporting and CSV export
`ai_agents:write`	Required together with `forms:write` to generate a form through an AI agent

The lifecycle

A form is always in one of four states, and the API moves it between them:

draft

POST /forms creates it. PATCH /forms/{formId} edits the definition as often as you like. Nothing is publicly reachable yet.

published

POST /forms/{formId}/publish freezes the current definition as an immutable version and returns the public link. Editing afterwards creates the next version; responses already in flight keep the version they were served.

closed

POST /forms/{formId}/close stops new responses. The link still resolves and explains that the form is closed.

archived

POST /forms/{formId}/archive removes it from the working list. POST /forms/{formId}/restore brings it back. Responses are retained.

POST /forms/{formId}/publish returns the form’s public_code and the URL built from it. A published form can be shared two ways:

A public link, the same for everyone: https://app.huechat.ai/to/{publicCode}.
An invitation, issued per recipient with POST /forms/{formId}/invitations.

An invitation is a bearer link. It identifies the contact it was issued for, so the response is attributed to that customer and can prefill their known fields.

Anyone holding an invitation link can open it. Forwarding it passes that attribution along with it, so do not treat an invitation as proof of identity for sensitive prefill or profile updates. Use POST /forms/{formId}/invitations/{invitationId}/revoke to withdraw one, and POST /forms/{formId}/rotate-link to invalidate every existing link to a form at once.

Collecting a response

A respondent client goes through the same three calls your own web page would:

# 1. Load the published form. Returns the definition and a signed session.
#    Add ?invite=<token> when opening an invitation link.
curl https://app.huechat.ai/api/v2/forms/{publicCode}

# 2. Optionally record progress as the person moves through it. type is one of
#    viewed, started, question_seen, question_answered, exited.
curl -X POST https://app.huechat.ai/api/v2/forms/{publicCode}/events \
  -H "Content-Type: application/json" \
  -d '{"session_id":"...","type":"question_seen","question_id":"q1"}'

# 3. Submit. The server replays the form's own rules before accepting.
curl -X POST https://app.huechat.ai/api/v2/forms/{publicCode}/responses \
  -H "Content-Type: application/json" \
  -d '{"session_id":"...","idempotency_key":"a-key-you-generate","answers":{"q1":"Yes"}}'

idempotency_key is required. Retrying a submission with the same key returns the original result instead of recording a second response, so a network retry is safe. Submission is not a blind write. The server re-evaluates the form’s branching and scoring server-side, so a client that skips a required question or posts an answer the rules do not allow is rejected. For an invitation, pass its token as ?invite= when loading the form and as invite in each body. POST /forms/{publicCode}/prefill then returns the fields the account has consented to prefill for that contact; it requires session_id, invite and an explicit opt_in.

Respondent rate limits

Each respondent operation is limited per form, per client, per minute. The limits are deliberately tight, because these endpoints are unauthenticated:

Operation	Per minute
Open a form	120
Record an event	240
Fetch an asset	240
Submit a response	60
Request schedule slots	60
Prefill from an invitation	30
Upload a file or AI answer	10
Book a schedule slot	5

Over the limit returns 429. See rate limits for the general retry guidance.

Reporting

Endpoint	Returns
`GET /forms/{formId}/reports`	Performance summary, device breakdown, question reach and drop-off
`GET /forms/{formId}/responses`	Individual responses, paginated
`GET /forms/{formId}/invitations`	Invitation lifecycle: issued, opened, responded, revoked
`GET /forms/{formId}/responses/export.csv`	The same responses as CSV

All four need forms:read and reports:read.

Appointment reminders

A published form can be attached to an appointment reminder rule, so each reminder carries a link for that specific recipient. The reminder endpoints live under appointments; the form-related fields appear on POST and PUT /appointments/reminders. Each delivery gets its own private invitation, and the reminder can stop once the recipient has responded.

Files and scheduling

Assets. POST /forms/{formId}/assets uploads branding or question media. Respondents upload to POST /forms/{publicCode}/assets, and files uploaded by a respondent are private to the account.
Scheduling. A form can include a booking step: POST /forms/{publicCode}/schedule/slots lists availability and POST /forms/{publicCode}/schedule/book books one, returning a signed receipt.

Generating a form with AI

POST /forms/ai/generate drafts a form from a prompt, and GET /forms/ai/generation-usage reports the monthly allowance. Generation is capped per account per month; the usage endpoint tells you what is left before you spend an attempt. A generated form always arrives as a draft for a person to review and publish.

Get started

Working with the API

Integrate

Before you start

The lifecycle

Collecting a response

Respondent rate limits

Reporting

Appointment reminders

Files and scheduling

Generating a form with AI

​Before you start

​The lifecycle

​Publishing and sharing

​Collecting a response

​Respondent rate limits

​Reporting

​Appointment reminders

​Files and scheduling

​Generating a form with AI

Before you start

The lifecycle

Publishing and sharing

Collecting a response

Respondent rate limits

Reporting

Appointment reminders

Files and scheduling

Generating a form with AI