# Create and manage forms with an AI agent

An agent with its own key can create the forms a Space needs, change their settings and fields, pause them and delete the ones nobody has answered. Every change is checked, limited and logged, and a person can still edit the same form in the dashboard form builder.

Available

## Give an agent access

1. Create an [agent key](https://bynefit.com/docs/agent-keys). It starts in test mode.
2. The agent asks for `write:forms` with `POST /dash/api/v1/agent/access-requests` and a `reason`. Reading forms needs `read:forms`, which a key can be created with.
3. The key owner, a manager or admin of the Space, approves it on the key page. It takes effect at once.
4. To let the agent write for real, the owner moves the key from test mode to live. In test mode every write is a dry run.

If the owner stops being a manager or admin, the whole key switches off.

## The calls

All calls are under `/dash/api/v1`, take the key as a Bearer token and only see forms in the key's own Space. A form from another Space answers `404`.

| Call | What it does |
| --- | --- |
| `GET /forms`, `GET /forms/{id}` | Read. For an agent key the single form also carries its `status`, `url`, `short_url` and `fields`. |
| `POST /forms` | Create a form. Body: `name`, and optionally `description`, `form_type` (`standard` or `lead`), `auth_mode` (`none`, `email_otp` or `bynli_login`), `confirmation_message` and `fields`. Supports `Idempotency-Key`. |
| `PATCH /forms/{id}` | Change `name`, `description`, `form_type`, `auth_mode`, `confirmation_message`, `status` (`active` or `paused`), `autoresponder_subject` or `autoresponder_body`. |
| `DELETE /forms/{id}` | Delete a form that has no submissions. |
| `POST /forms/{id}/fields` | Add a field. |
| `PATCH /forms/{id}/fields/{field_id}` | Change a field. |
| `DELETE /forms/{id}/fields/{field_id}` | Delete a field. |
| `POST /forms/{id}/fields/{field_id}/move` | Body `{"direction": "up"}` or `"down"`. |

Every write answers with the form: its `id`, `slug`, the public page `url` (`/forms/{space}/{slug}`), the `short_url` and its `fields`. The slug is made from the name when the form is created and does not change when the form is renamed, so shared links keep working.

## Fields

A field takes a `label` and an `input_type`, and optionally `required`, `placeholder` and `help_text`.

- **Types.** text, textarea, email, tel, number, date, dropdown, checkbox, radio, section_header, hidden.
- **Dropdown and radio** need `options`: a list of 1 to 50 strings of 1 to 100 characters. An option may contain commas.
- **Hidden** needs `value`: the text every submission carries.
- **Section header** shows a heading and collects nothing.
- **Label** is 1 to 150 characters.

**Create a form with fields (bash)**

```
curl -X POST -H "Authorization: Bearer $BYNEFIT_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: contact-form-1" \
  -d '{"name": "Contact us", "form_type": "lead", "fields": [
        {"label": "Your email", "input_type": "email", "required": true},
        {"label": "Topic", "input_type": "dropdown", "options": ["Sales", "Support", "Press, media"]}
      ]}' \
  https://bynefit.com/dash/api/v1/forms
```

Each form also reports `accepting_responses`, `notify_emails`, `redirect_url`, `opens_at`, `closes_at`, `max_responses` and `closed_message`. These are set by a person in the dashboard; an agent key can read them but not change them.

## Notifications and availability

A person sets these in the dashboard under Forms, Settings. They are not changed through an agent key.

- **Notify by email.** Up to 5 addresses, each a member of the Space. Each response sends them an email with the answers, up to 30 responses an hour per form, so only list people who may see them.
- **Redirect.** After the confirmation message the person is sent to a full `https://` address on any site you choose, or a path like `/thanks` on a form embedded in your hosted site. Redirects are not followed inside an embedded iframe: the Continue link opens the page instead.
- **Open and close.** A form accepts responses only between the two times. Times are stored in UTC and shown in your time zone.
- **Response limit.** The form stops accepting responses once it has this many. Everyone past the limit sees the closed message. A paused form is not reachable by visitors at all: its page answers as not found.

## Starting engagements from a form

Set `engagement_type` to the key of one of the Space's [engagement types](https://bynefit.com/docs/manage-engagement-types) (or `null` to stop). Each submission then also starts an engagement of that type in its first step, with the type's default items, and the Space is alerted as for any new request. The respondent gets an email explaining that they follow it by signing in with Bynefit using the same address. If the form asks for an email code first, that verified address is used. The engagement joins their account only when they sign in with a verified email that matches, and one that already belongs to someone is never moved. A registration form cannot start engagements. If the engagement cannot be created the response is still saved and flagged *Follow-up needed*.

## Limits and safety

- **Registration forms.** They create user accounts from public submissions, so an agent cannot create one, switch a form to one, or change or delete one. The owner does that in the dashboard.
- **Submissions.** An agent cannot read, change or delete them with this permission. A form that has submissions cannot be deleted by an agent: pause it instead.
- **Size.** At most 60 fields on a form and 100 forms in a Space for an agent.
- **Name.** 1 to 120 characters.
- **Ceiling.** 1,000 live writes a day per key by default, which the key's owner can raise to 10,000. It is a safety ceiling against a runaway agent; each write also costs units. It comes back at midnight, server time.
- **Test mode.** A key in test mode, or any call with `"dry_run": true` (or `?dry_run=true` on a `DELETE`), is validated and answers `200` with `"dry_run": true`. Nothing is written and no budget is used.
- **Log.** Every live change is recorded in the Space activity log with the key, form id and action. Form content is never logged.

## Errors

| Status | `error` | What to do |
| --- | --- | --- |
| 403 | `insufficient_scope` | The key lacks the permission. Request it and have the owner approve. |
| 400 | `invalid_id` | Use a `frm_` id from `GET /forms`. |
| 404 | `not_found`, `field_not_found` | The form or field is not in this Space. |
| 409 | `form_has_submissions` | Pause the form instead of deleting it. |
| 409 | `registration_form_owner_only` | Registration forms are changed by the owner in the dashboard. |
| 409 | `too_many_fields`, `form_limit_reached` | Remove a field or a form first. |
| 413 | `body_too_large` | Send a smaller body. |
| 422 | `invalid_body`, `invalid_name`, `invalid_label`, `invalid_input_type`, `invalid_options`, `invalid_value`, `invalid_form_type`, `invalid_auth_mode`, `invalid_status`, `invalid_direction`, `invalid_fields`, `too_many_fields`, `unknown_field`, `nothing_to_change` | Fix the value the message names. Nothing was written. |
| 422 | `registration_not_allowed` | An agent cannot create or switch to a registration form. |
| 429 | `agent_write_budget_spent` | Wait for midnight, server time. |
| 429 | `agent_limits_unavailable` | The write limits could not be checked, so nothing was changed. Try again in a minute. |
| 500 | `form_write_failed` | Nothing was changed. Try again, and quote the `request_id` if it repeats. |
| 405 | `method_not_allowed` | Use the method in the calls table. |

Quote the `request_id` from any error when you contact support.

## What exists and what does not

- [Read community resources](https://bynefit.com/docs/resources-read) - List and filter community resources with a developer key. JSON, cursor paging. (Available)
- [Submit a resource for review](https://bynefit.com/docs/resources-submit) - Propose a new entry. A moderator reviews it before it goes live. (Available)
- [Partner events](https://bynefit.com/docs/partner-events) - Partners send their own product events from a page, a server or an app, and read the totals back. Bynefit turns it on per partner. (By approval)
- [Hosted sites runtime](https://bynefit.com/docs/sites-runtime-api) - Events, resources, media, forms and page views for a hosted site, with no key. (Available)
- [Read and edit hosted site files](https://bynefit.com/docs/manage-site-files) - An agent key lists a Space's sites and reads, replaces and deletes their files, with versions, secret scanning and a daily write ceiling. The key owner approves the permission. (Available)
- [Create and manage forms](https://bynefit.com/docs/manage-forms) - An agent key creates forms for a Space, changes their settings and fields, pauses them and deletes unanswered ones, with a daily write ceiling and a test mode. Registration forms and submissions stay out of reach. The key owner approves the permission. (Available)
- [Engagement types and stages](https://bynefit.com/docs/manage-engagement-types) - A Space defines its own kinds of client work with ordered stages inside the existing statuses. Managers edit them on the Engagements page, and an agent key reads and manages them with a daily write budget and a test mode. The key owner approves the permissions. (Available)
- [Client portal API](https://bynefit.com/docs/client-portal-api) - A signed-in client reads their own engagements, documents and messages; a practice manager runs the pipeline. (Available)
- Engagements through an API key or a webhook - Read engagements from your own server, or hear about a change, without a person signed in. (Planned)
- [Every docs page as Markdown](https://bynefit.com/docs/ai-agents) - Add ?format=md to any docs page, or send Accept: text/markdown. (Available)
- [llms.txt index](https://bynefit.com/docs/ai-agents) - A short index of the docs for tools that read llms.txt, at /docs?format=llms. (Available)
- [OpenAPI spec](https://bynefit.com/docs/ai-agents) - An OpenAPI 3.1 description of the v1 API, with the error envelope and security schemes, at /docs?format=openapi. (Available)
- [Agent skill and integration brief](https://bynefit.com/docs/agent-skill) - An installable SKILL.md and a paste-in brief, generated from the same code as the spec. (Available)
- [Agent keys](https://bynefit.com/docs/agent-keys) - A key made for an AI agent: read-only to start, short-lived, test mode first, every call logged, and the owner approves anything more. (Available)
- Request id and docs link on every error - Every error body carries an id to quote to support and a link to the page that explains it. (Planned)
- [Test keys and a sandbox](https://bynefit.com/docs/test-mode) - Keys that only touch sample data, ready at once with no review, so a first attempt cannot break anything. (Available)
- [Idempotency-Key on writes](https://bynefit.com/docs/authentication) - Retry a v1 write without doing it twice: the first answer is replayed for 24 hours, per key. (Available)
- [Status page](https://bynefit.com/docs/status) - Live state, 90-day uptime and incident history for the API, sign-in, webhook delivery, the widget, hosted sites and email. Atom and JSON feeds. (Available)
- [Docs MCP server](https://bynefit.com/docs/docs-mcp) - Read-only search of these docs from an AI tool. (Available)

---

Source: https://bynefit.com/docs/manage-forms
Checked against the live API on October 18, 2026.