Formy REST API: tokens, abilities, endpoints and errors

Every endpoint on this page is relative to https://formy.co.il/api. Send and accept JSON: set Accept: application/json and, on requests with a body, Content-Type: application/json. There is no version segment in the path.

The API has two groups of routes:

• /open/..., the product's own API: workspaces, forms and form integrations. A token reaches only the routes listed under [abilities](#abilities).
• /external/..., small, stable endpoints for automation platforms and scripts: validate a token, list workspaces, forms and fields, subscribe a Make webhook, and send a document for signature. They are documented on Automation endpoints and Signing requests.

Where a path has {form}, you can pass the form's numeric ID or its slug (the last part of its public link, formy.co.il/forms/<slug>). {workspace} is the workspace's numeric ID.

A personal access token acts as the person who created it, in every workspace that person belongs to. Abilities narrow what the token may do; the person's role in each workspace still applies on top, so a token belonging to a read-only member cannot edit anything in that workspace.

Create a token

1. In Formy, open your account settings and the גישה ל-API tab.
2. Click יצירת API Access Token חדש.
3. Give it a name under שם that says what will use it, such as CRM sync.
4. Under הרשאות, keep only what that integration needs. All five abilities are ticked when the dialog opens.
5. Click יצירת API Access Token and copy the token with העתקת ה-Token. It is shown once.

The same tab lists your tokens with their abilities and deletes them. A deleted token stops working at once and answers 401. Tokens do not expire on their own, so delete the ones you no longer use and keep a separate token for each integration.

Send it

curl https://formy.co.il/api/external/validate \
  -H "Authorization: Bearer $FORMY_TOKEN" \
  -H "Accept: application/json"

{
  "name": "Dana Cohen",
  "email": "dana@example.com"
}

A token is its number, a |, and 48 letters and digits, such as 123| followed by the rest. Store it as a secret: anyone who has it can do everything its abilities allow, as you.

Formy decides access per route. Each route a token can call needs one ability, either of two, or both of two, as listed below. A token without the ability gets 403. A route that is not on this list answers 404 to every token, so that a token cannot discover what exists.

Older tokens may also carry workspace-users-read or workspace-users-write. No route checks either one, and the dialog no longer offers them.

Workspaces

Forms

Form integrations

Automation endpoints

These operations exist in the product but only for a person signed in to Formy in a browser. A token gets 404 for each of them, even with every ability. That is deliberate, but it means a 404 here is about permission, not a typo in the path.

• Read, list, update or delete responses (submissions)
• Export responses, and poll an export's status
• A response's PDF or file links
• Delete a form, empty the trash, duplicate a form or move it to another workspace
• Delete or leave a workspace
• Add or remove members, change a role, resend or cancel an invitation
• Contacts, bulk send, signing-round controls, folders, statistics and the response summary

To get responses into another system, use a webhook (every completed response, signed, retried for a day), Make or Google Sheets. To download them yourself, export from the responses table: see responses and exports.

GET /open/workspaces lists every workspace you belong to, with its members and their roles. GET /external/workspaces returns the short form an automation dropdown needs; see Automation endpoints.

curl https://formy.co.il/api/open/workspaces \
  -H "Authorization: Bearer $FORMY_TOKEN" -H "Accept: application/json"

To create one, POST /open/workspaces/create with a name (required) and an optional emoji for its icon. Your plan sets how many workspaces you can have; over the limit the call answers with a [plan-limit error](#errors). PUT /open/workspaces/{workspace} takes the same two fields and replaces both, so send the emoji again if you want to keep it.

curl -X POST https://formy.co.il/api/open/workspaces/create \
  -H "Authorization: Bearer $FORMY_TOKEN" -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"name": "Clinic intake"}'

GET /open/forms returns every form in every workspace you belong to, in one unpaginated list. For one workspace, GET /open/workspaces/{workspace}/forms is paginated and accepts:

GET /open/forms/{form} returns the whole definition: settings, properties (the fields, each with its id, type and name), definition_revision and etag. A token with only manage-integrations can read it too, so an integration can look up the form it serves.

Create and update

POST /open/forms creates a form from a definition. It needs workspace_id, title and properties, plus the presentation settings the editor saves (visibility, language, theme, presentation_style, width, size, border_radius, dark_mode, color, uppercase_labels, no_branding, transparent_background). The definition format is the editor's own, so the reliable way to build one is to read a form you made in the editor and change it.

PUT /open/forms/{form} replaces the definition. Send the whole definition back with the expected_revision you read, or an If-Match header with its ETag; see [revisions](#revisions). Plan limits apply exactly as in the editor: a setting your plan does not include is removed rather than saved, and the response lists what was removed under plan_strip_warnings. The response also carries the new definition_revision and etag.

Smaller writes have their own routes: PATCH /open/dashboard/forms/{form}/visibility with visibility (public or draft) and PATCH /open/dashboard/forms/{form}/rename with title, both with expected_revision. POST /open/forms/{slug}/restore takes a form out of the trash. Deleting a form is not available to tokens.

Everything on a form's אינטגרציות tab is an integration: email, Slack, Google Sheets, a webhook and the rest. With manage-integrations you can manage them by API. A webhook is the one most often created by code:

curl -X POST https://formy.co.il/api/open/forms/service-agreement/integrations \
  -H "Authorization: Bearer $FORMY_TOKEN" -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "integration_id": "webhook",
    "status": "active",
    "data": {
      "webhook_url": "https://example.com/hooks/formy",
      "webhook_secret": "a-long-random-secret-value",
      "webhook_headers": { "X-Api-Key": "your-own-key" }
    },
    "logic": null
  }'

status is active or inactive. logic holds the conditions under which the integration runs, the same ones as מתי האינטגרציה תרוץ? in the product; null runs it on every response. The webhook's own rules (HTTPS only, a public address, a secret of at least 12 characters, at most 10 custom headers) are on the webhooks page.

The response, and GET .../integrations, return each integration with its settings, including the webhook's secret and custom headers. Treat a token with manage-integrations as able to read them.

PUT .../integrations/{integration} changes the settings with the same body, PUT .../integrations/{integration}/status pauses or resumes it, and DELETE removes it. GET .../integrations/{integration}/events returns its delivery history, the same list the product shows under אירועים קודמים.

Every saved form has a definition_revision, a number that goes up on each save, and an etag built from it. A write that changes a form must say which revision it was based on, as expected_revision in the body or as If-Match: <etag>. If both are sent, they must agree.

Creating a form needs no revision; the response carries the first one. A signing request also checks the revision, as expected_form_revision, so a document is never sent from a form that changed under you.

Errors are JSON with a message, in Hebrew except for the missing-ability 403. Validation errors (422) add an errors object keyed by field, and revision errors add a code.

{
  "message": "נדרשת התחברות."
}

{
  "message": "Invalid ability provided."
}

{
  "message": "המשאב המבוקש לא נמצא."
}

{
  "type": "plan_limit",
  "code": "workspaces",
  "feature": "workspaces",
  "limit": 1,
  "current": 1,
  "target_plan": "pro",
  "message": "…",
  "context": null
}

Limits are counted per person (all of a person's tokens together) and per minute:

Responses carry X-RateLimit-Limit and X-RateLimit-Remaining. Over the limit you get 429 with Retry-After, the seconds to wait. The MCP server has its own limits.