Skip to content
On this page and tools
View as MarkdownOpen in ClaudeOpen in ChatGPTDownload OpenAPI specAPI changes feed
Available

Checked against the live API on October 18, 2026.

Report an error on this page

Forms

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. 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.

CallWhat 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 /formsCreate 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}/fieldsAdd 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}/moveBody {"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.

Create a form with fieldsbash
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.

Starting engagements from a form

Set engagement_type to the key of one of the Space's 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

Errors

StatuserrorWhat to do
403insufficient_scopeThe key lacks the permission. Request it and have the owner approve.
400invalid_idUse a frm_ id from GET /forms.
404not_found, field_not_foundThe form or field is not in this Space.
409form_has_submissionsPause the form instead of deleting it.
409registration_form_owner_onlyRegistration forms are changed by the owner in the dashboard.
409too_many_fields, form_limit_reachedRemove a field or a form first.
413body_too_largeSend a smaller body.
422invalid_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_changeFix the value the message names. Nothing was written.
422registration_not_allowedAn agent cannot create or switch to a registration form.
429agent_write_budget_spentWait for midnight, server time.
429agent_limits_unavailableThe write limits could not be checked, so nothing was changed. Try again in a minute.
500form_write_failedNothing was changed. Try again, and quote the request_id if it repeats.
405method_not_allowedUse the method in the calls table.

Quote the request_id from any error when you contact support.

What exists and what does not