← All action domains

Forms

32 operations. Call each with POST https://app.chirply.io/api/v1/actions/<name> and a bearer token; the response is { "data": { "action", "summary", "result" } }. A read badge means the operation changes nothing; write requires the credential’s write scope.

Archive form

forms.archivewriteconfirm

Retire a finished form. Every partial and completed response is KEPT, the form id does not change, and any workflow pointed at it stays connected — nothing is deleted. What changes is two things: it leaves the main Forms list for the Archived tab, and its public link stops accepting submissions and serves the form's closing message instead of the form. Use forms.restore to bring it back as a draft.

Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.

Also answers to retire this form, file this form away, close this form for good.

Parameters

FieldTypeRequiredDescription
idstring (uuid)requiredThe form to archive. A live form is taken offline by this.

Example

curl -X POST https://app.chirply.io/api/v1/actions/forms.archive \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool forms_archive at https://app.chirply.io/api/mcp, same bearer token, same input.

Create form

forms.createwrite

Create a new draft standalone form from a built-in starting point. This does not publish it or contact anyone.

Parameters

FieldTypeRequiredDescription
namestringrequiredThe internal name shown in the form library.
starter"lead" | "feedback" | "quiz" | "application" | "blank"optionalThe built-in starting structure to copy. Default: "lead"
folder_idstring (uuid)optionalOptional: file the new form in this Forms-page folder (from forms.list_folders). Omit to leave it unfiled.

Example

curl -X POST https://app.chirply.io/api/v1/actions/forms.create \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Example"
  }'
Test with your API key

Over MCP the same operation is the tool forms_create at https://app.chirply.io/api/mcp, same bearer token, same input.

New form folder

forms.create_folderwrite

Create a folder on the Forms page to file forms in. Give `parent_id` to make it a sub-folder of a top-level folder (folders go one level deep, so the parent must not itself be a sub-folder). Names are unique among siblings, ignoring case. Creating a folder changes no form and contacts no one; file forms in it with forms.move_to_folder.

Also answers to make a folder for my forms, add a forms folder, create a subfolder for forms.

Parameters

FieldTypeRequiredDescription
namestringrequiredThe folder's name as shown on the Forms page, e.g. "Client onboarding".
parent_idstring (uuid)optionalOptional: a TOP-LEVEL folder id (from forms.list_folders) to put this one inside. Omit for a top-level folder.

Example

curl -X POST https://app.chirply.io/api/v1/actions/forms.create_folder \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Example"
  }'
Test with your API key

Over MCP the same operation is the tool forms_create_folder at https://app.chirply.io/api/mcp, same bearer token, same input.

Delete form

forms.deletewriteconfirm

Permanently delete a form and every partial and completed response it collected. This cannot be undone.

Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.

Parameters

FieldTypeRequiredDescription
idstring (uuid)requiredThe form to permanently delete.

Example

curl -X POST https://app.chirply.io/api/v1/actions/forms.delete \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool forms_delete at https://app.chirply.io/api/mcp, same bearer token, same input.

Delete form folder

forms.delete_folderwriteconfirm

Delete a folder from the Forms page. NO FORM IS DELETED: forms filed directly in a sub-folder move up to its parent folder, forms filed directly in a top-level folder become Unfiled, and a top-level folder's sub-folders become top-level folders with their forms still inside. Every form keeps its link, responses and status. The folder itself cannot be restored, though it can be recreated and refilled.

Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.

Also answers to remove a forms folder, get rid of this form folder.

Parameters

FieldTypeRequiredDescription
idstring (uuid)requiredThe folder to delete (from forms.list_folders).

Example

curl -X POST https://app.chirply.io/api/v1/actions/forms.delete_folder \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool forms_delete_folder at https://app.chirply.io/api/mcp, same bearer token, same input.

Duplicate form

forms.duplicatewrite

Create a private draft copy of a form's questions, rules, settings, and design. Responses are not copied and nothing is published.

Parameters

FieldTypeRequiredDescription
idstring (uuid)requiredThe form to copy.
namestringoptionalOptional name for the copy.

Example

curl -X POST https://app.chirply.io/api/v1/actions/forms.duplicate \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool forms_duplicate at https://app.chirply.io/api/mcp, same bearer token, same input.

Export responses CSV

forms.export_responsesread

Export a form's responses as CSV text, byte-for-byte what the Results screen's Export CSV button downloads: a header row of Status, Started, Completed, Score followed by one column per question (statement blocks are skipped because nobody answers them), then one row per response. Multi-select answers are joined with '; ' and an uploaded file shows as its filename. Columns follow the DRAFT question list, so a question added since a response came in appears as an empty column for that row. Returns the CSV as a string for you to save — nothing is emailed or uploaded anywhere. This only reads data.

Parameters

FieldTypeRequiredDescription
form_idstring (uuid)requiredThe form whose responses to export.
status"partial" | "completed"optionalExport only responses with this completion status. Omit to export both, which is what the app's button does.
limitintegeroptionalMost recent responses to include, newest first (1-5000). The app's own screen shows 500. Default: 500

Example

curl -X POST https://app.chirply.io/api/v1/actions/forms.export_responses \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "form_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool forms_export_responses at https://app.chirply.io/api/mcp, same bearer token, same input.

Form drop-off

forms.funnelread

Get a form's drop-off funnel — the same numbers as the Drop-off card on the form's Results screen. It counts browser VISITS (one per response session, on the hosted link or embedded on a site; crawlers excluded) that first opened the published form inside the window, and how many of those visits went on to reach each stage: `viewed` (the form loaded), `started` (the first key press, tap or answer), one `step_completed` stage per page of a multi-step form (the last page has none — finishing it is `submitted`), and `submitted` (a completed response was stored). Each stage returns `sessions`, `kept_percent` (share of the previous stage, capped at 100), `from_start_percent` (share of all visits) and `dropped`. A visit counts at every stage it reached, even if it reached it after the window ended. Filter by the visit's `source` (utm_source, else the platform or site it came from; an empty string means direct), `landing_page` (host and path the form was filled in on — the host page for an embed), `campaign` (utm_campaign) or `channel` (a one-word verdict such as meta_ads, google_ads, organic_search, direct). `options` lists every value seen in the window with its visit count; those are the valid filter values. Only visits since progress tracking shipped are counted, and responses sent through forms.submit_response are not browser visits, so they never appear here — forms.stats has the lifetime totals. This only reads data.

Also answers to form funnel, form abandonment, form drop off, form conversion funnel, where people quit the form.

Parameters

FieldTypeRequiredDescription
form_idstring (uuid)requiredThe form to report on.
sincestring (date-time)optionalStart of the window, inclusive, as an ISO 8601 timestamp: visits that first opened the form at or after this moment. When both since and until are omitted the window is the last 30 days, which is what the Results screen opens on.
untilstring (date-time)optionalEnd of the window, exclusive, as an ISO 8601 timestamp. Omit for 'up to now'.
all_timebooleanoptionalTrue to ignore since/until and report every visit ever recorded for this form. Default: false
sourcestringoptionalOnly visits from this source, exactly as listed in `options.sources[].value` (lower-case utm_source, or the referring platform or site). An empty string selects direct visits.
landing_pagestringoptionalOnly visits where the form was filled in on this page, exactly as listed in `options.landing_pages[].value` — host and path with no query string, e.g. "example.com/offer-b". Use it to compare landing page variants.
campaignstringoptionalOnly visits tagged with this utm_campaign, as listed in `options.campaigns[].value`. An empty string selects visits with no campaign.
channelstringoptionalOnly visits classified into this channel, as listed in `options.channels[].value` — for example meta_ads, google_ads, organic_search, referral_site or direct.

Example

curl -X POST https://app.chirply.io/api/v1/actions/forms.funnel \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "form_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool forms_funnel at https://app.chirply.io/api/mcp, same bearer token, same input.

Open a form

forms.getread

Fetch one standalone form in full: its draft question definition, behavior settings, design theme, and the separate published snapshot visitors currently see. The `definition.questions[].id` values in the result are what a response's `answers` object is keyed by, so this is where you get them before submitting an answer — and `definition`/`settings`/`theme` here are exactly the objects forms.update expects back, so read this first whenever you intend to edit one. This only reads data.

Parameters

FieldTypeRequiredDescription
idstring (uuid)requiredThe form's id.

Example

curl -X POST https://app.chirply.io/api/v1/actions/forms.get \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool forms_get at https://app.chirply.io/api/mcp, same bearer token, same input.

Open response

forms.get_responseread

Fetch one form response with its answers, completion status, score, outcome, and linked CRM contact — what the full-response page shows when a row on the form's Results tab is opened. `answers` is the raw stored object keyed by question id (choice answers are option VALUES, consent is a boolean). `formatted_answers` is the same response made readable: every answered question in the form's own order with its wording (`question`) and the answer as text (`answer` — choice labels instead of values, 'Agreed' or 'Did not agree' for consent, a file's name and size), never truncated; a multi-select also lists `items`, a file answer carries `file`, and an answer to a question since removed from the form is kept with `removed: true`. `form_name` names the form. This only reads data.

Parameters

FieldTypeRequiredDescription
idstring (uuid)requiredThe response id.

Example

curl -X POST https://app.chirply.io/api/v1/actions/forms.get_response \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool forms_get_response at https://app.chirply.io/api/mcp, same bearer token, same input.

List forms

forms.listread

List the account's standalone forms, surveys, quizzes, and applications, newest first. This only reads data.

Parameters

FieldTypeRequiredDescription
limitintegeroptionalMax rows to return (1–100). Default: 25
offsetintegeroptionalRows to skip. Default: 0
status"draft" | "published" | "archived"optionalOnly forms with this status.
kind"form" | "survey" | "quiz"optionalOnly forms of this kind.
querystringoptionalText to match in the form name or description.
folderstringoptionalOnly forms filed in this Forms-page folder: a folder id from forms.list_folders, or 'unfiled' for forms in no folder. A top-level folder also returns the forms in its sub-folders, exactly like opening it on the Forms page. Each form's own folder is its folder_id (null = unfiled).

Example

curl -X POST https://app.chirply.io/api/v1/actions/forms.list \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "limit": 25,
    "offset": 0
  }'
Test with your API key

Over MCP the same operation is the tool forms_list at https://app.chirply.io/api/mcp, same bearer token, same input.

List a contact's form submissions

forms.list_contact_responsesread

List every standalone form ONE contact has completed, newest first — the contact record's Forms tab. Each response carries `form_id`, `form_name`, `submitted_at`, `score` (with `scored` saying whether the form actually scores answers — on a plain lead form the number is meaningless), `outcome` for a scored quiz, and `formatted_answers`: every answered question in the form's own order with its wording and a readable answer (choice labels instead of option values, 'Agreed' for a ticked consent box, a file's name and size), never truncated, keeping answers to questions since removed from the form with `removed: true`. Every response linked to the contact is included, however old. Unfinished (partial) responses are never linked to a contact, so they are not listed here — read those per form with forms.list_responses, and the raw answers of one response with forms.get_response. This only reads data.

Also answers to what forms has this contact filled in, show a contact's form answers, form responses for a contact.

Parameters

FieldTypeRequiredDescription
limitintegeroptionalMax rows to return (1–100). Default: 25
offsetintegeroptionalRows to skip. Default: 0
contact_idstring (uuid)requiredThe contact whose completed form responses to list.

Example

curl -X POST https://app.chirply.io/api/v1/actions/forms.list_contact_responses \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool forms_list_contact_responses at https://app.chirply.io/api/mcp, same bearer token, same input.

List form folders

forms.list_foldersread

List the folders on the Forms page, each with how many forms are filed in it. Folders go one level deep: a top-level folder may hold sub-folders (`parent_id` is null for a top-level folder and names the parent for a sub-folder). `active_forms` counts forms on the Active tab (draft and live) and `archived_forms` those on the Archived tab; `active_total` adds a top-level folder's sub-folders to its own count, which is the number its chip shows. Also returns how many forms are in no folder (`unfiled`). This only reads data.

Also answers to show my form folders, how are my forms organised, which folders do I have on forms.

Parameters

No parameters — POST an empty body.

Example

curl -X POST https://app.chirply.io/api/v1/actions/forms.list_folders \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{}'
Test with your API key

Over MCP the same operation is the tool forms_list_folders at https://app.chirply.io/api/mcp, same bearer token, same input.

List responses

forms.list_responsesread

List partial or completed responses for a form, including answers, score, outcome, and linked CRM contact. This only reads data.

Parameters

FieldTypeRequiredDescription
limitintegeroptionalMax rows to return (1–100). Default: 25
offsetintegeroptionalRows to skip. Default: 0
form_idstring (uuid)requiredThe form whose responses to list.
status"partial" | "completed"optionalOnly responses with this completion status.

Example

curl -X POST https://app.chirply.io/api/v1/actions/forms.list_responses \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "form_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool forms_list_responses at https://app.chirply.io/api/mcp, same bearer token, same input.

Response session path

forms.list_session_eventsread

List the progress events one visit to a form recorded, oldest first — the path behind one row of the Drop-off card: `viewed` (with where the visit came from: channel, source, campaign, landing page, and whether the form was embedded), `started`, each `step_completed` (with its 1-based step number and the id and wording of the page's first question) and `submitted`. Identify the visit by `response_id` (any response from forms.list_responses, which carries the same session) or by `session_id` (a response's `session_id`). A visit that never interacted has only `viewed`; responses sent through forms.submit_response have no events. This only reads data.

Also answers to form session events, form visit path, form progress events.

Parameters

FieldTypeRequiredDescription
form_idstring (uuid)requiredThe form the visit belongs to.
response_idstring (uuid)optionalA response to this form; its session's events are returned. Give this or session_id.
session_idstringoptionalThe visit's session id, exactly as a response's `session_id` shows it. Give this or response_id.

Example

curl -X POST https://app.chirply.io/api/v1/actions/forms.list_session_events \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "form_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool forms_list_session_events at https://app.chirply.io/api/mcp, same bearer token, same input.

Move forms to a folder

forms.move_to_folderwrite

File one or more forms in a folder on the Forms page, or take them out of every folder with `folder_id: null` (they then show under Unfiled). Moving changes only where the form is filed: its link, responses, status and "Edited" date stay exactly as they were.

Also answers to put these forms in a folder, file this form, unfile a form, organise my forms into folders.

Parameters

FieldTypeRequiredDescription
form_idsarray of (string (uuid))requiredThe forms to move (ids from forms.list), up to 200 at a time.
folder_idstring (uuid) (or null)requiredThe destination folder id (from forms.list_folders), or null to take the forms out of every folder.

Example

curl -X POST https://app.chirply.io/api/v1/actions/forms.move_to_folder \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "form_ids": [
      "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
    ],
    "folder_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool forms_move_to_folder at https://app.chirply.io/api/mcp, same bearer token, same input.

Publish

forms.publishwriteconfirm

Publish the current draft as a new public snapshot at the form's hosted URL. Real visitors can immediately submit it, create CRM contacts, and trigger configured workflows.

Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.

Parameters

FieldTypeRequiredDescription
idstring (uuid)requiredThe form to publish.

Example

curl -X POST https://app.chirply.io/api/v1/actions/forms.publish \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool forms_publish at https://app.chirply.io/api/mcp, same bearer token, same input.

Restore to draft

forms.restorewrite

Take a form back out of the archive. It returns as a DRAFT, never straight to live: reopening a form to the public is a deliberate act, so nothing is published and the link keeps showing the closing message until someone calls forms.publish. Nothing about the responses, the id or the connected workflows changes.

Also answers to unarchive a form, bring a form back.

Parameters

FieldTypeRequiredDescription
idstring (uuid)requiredThe archived form to restore.

Example

curl -X POST https://app.chirply.io/api/v1/actions/forms.restore \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool forms_restore at https://app.chirply.io/api/mcp, same bearer token, same input.

Save form progress

forms.save_partial_responsewrite

Save a respondent's answers SO FAR as a partial (unfinished) response — what the public form does in the background while someone is still typing, so a half-filled form is not lost. Deliberately quiet: unlike forms.submit_response this creates NO CRM contact and starts NO workflows, so nothing is emailed, texted, called or billed. The response is stored against your session_id and is upserted, so calling this repeatedly with the same session_id updates the same row as the person progresses; finish with forms.submit_response using that SAME session_id and the partial becomes the completed response. Required questions are not enforced until then. The form must be published. Note that the app only auto-saves partials when the form's 'Save partial responses' setting is on, whereas this capability — like the public route behind it — writes one either way.

Parameters

FieldTypeRequiredDescription
form_idstring (uuid)requiredThe published form being filled in.
session_idstringrequiredA caller-generated key identifying THIS respondent's sitting. Keep it identical across every save for the same person, then reuse it on forms.submit_response so the partial is completed rather than duplicated.
answersmap of string → objectrequiredThe respondent's answers, keyed by QUESTION ID (the `id` field of each question in the form's definition — get them from forms.get or forms.get_share_links, never guess). A hidden/text/email/phone/date answer is a string, a number/rating/scale answer is a number, a consent answer is a boolean, a single_choice or dropdown answer is the chosen option's `value` (not its label), a multiple_choice answer is an array of those values, and a file answer is the object returned by forms.upload_response_file. A hidden field may also be keyed by its `parameterName` instead of its id — {"consent_version":"2026-11-13"} — and the id wins when both are sent. Other keys that do not match a question are discarded. Example: {"q_1":"jane@example.com","q_2":"11_plus","q_3":"Our follow-up is a mess","q_4":["email","sms"],"q_5":{"path":"org/form/session/q_5/1699-brief.pdf","name":"brief.pdf","size":10240,"type":"application/pdf"}}

Example

curl -X POST https://app.chirply.io/api/v1/actions/forms.save_partial_response \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "form_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11",
    "session_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11",
    "answers": {}
  }'
Test with your API key

Over MCP the same operation is the tool forms_save_partial_response at https://app.chirply.io/api/mcp, same bearer token, same input.

Closing message

forms.set_closed_messagewrite

Set what the form's public link says once it stops taking answers — after Unpublish, or after Archive. Visitors who already hold the link see this instead of a 'not found' page, under the account's own branding, and submissions are still refused. Changing it takes effect immediately and does NOT republish the form: the closing message is read from the draft settings precisely so a closed form can be re-worded without accidentally reopening it. Harmless on a live form — it simply sits unused until the form is closed.

Also answers to closing message, what the form says when it is closed, paused form message.

Parameters

FieldTypeRequiredDescription
idstring (uuid)requiredThe form to set the closing message on. Works whether the form is live, draft or archived.
closed_titlestringoptionalThe heading on the closed page, e.g. 'This assessment is closed'. Leave out to keep the current one.
closed_messagestringoptionalThe paragraph under the heading — the place to say when it reopens, or where to go instead, e.g. 'We reopen on Monday; email hello@example.com if it is urgent.' Leave out to keep the current one.

Example

curl -X POST https://app.chirply.io/api/v1/actions/forms.set_closed_message \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool forms_set_closed_message at https://app.chirply.io/api/mcp, same bearer token, same input.

Hidden field

forms.set_hidden_fieldwrite

Add a Hidden field to a form, or change one. A hidden field is a question visitors never see: its value is filled from outside the form and stored with each response like any other answer (Results, response details, the CSV export and the Form submitted workflow's values). The value comes from the URL parameter on the hosted link or in the embed code's address (`?consent_version=v3`), from the address of the page an embedded form sits on, or from a submission's answers (forms.submit_response, or POST /api/forms/<slug>/responses) under the field's question id or its URL parameter name; when none arrives, its default value is stored. Typical uses: the version of the consent wording someone agreed to, the campaign that brought them, an id from your own system. Hidden values are untrusted input — never proof of consent or identity — so a hidden field cannot fill a contact field or be required. Saves the DRAFT only: submissions store a new or changed field once the form is published again (forms.publish). Sends nothing and changes no contact.

Also answers to add a hidden field to a form, pre-filled form field, store utm source with form responses, store the consent version with every form response.

Parameters

FieldTypeRequiredDescription
form_idstring (uuid)requiredThe form to add the hidden field to, or whose hidden field to change. Works whether it is live, draft or archived.
question_idstringoptionalThe hidden field to change — its `id` from forms.get or forms.get_share_links. Omit to add a new hidden field at the end of the form.
namestringoptionalHow the field is labelled in Results, the CSV export and response details, e.g. 'Consent version'. A new field without one is named after its URL parameter, or 'Hidden field'. Leave it out to keep an existing field's name.
parameter_namestringoptionalThe URL parameter that fills it, e.g. consent_version or utm_source — read from the hosted link, the embed code's address and the embedding page, and also accepted as its answers key in a submission. An empty string removes it. Changing it on a live form stops links and websites that send the old name from filling it.
default_valuestringoptionalStored when no value arrives, e.g. the version of the consent wording the form shows. An empty string removes it; leave it out to keep the current one.

Example

curl -X POST https://app.chirply.io/api/v1/actions/forms.set_hidden_field \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "form_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool forms_set_hidden_field at https://app.chirply.io/api/mcp, same bearer token, same input.

Form language

forms.set_languagewrite

Set the language a form is shown in. It changes the words the form itself supplies around yours — Continue and Back, the progress line, required-field and error messages, the file and signature prompts, Sending… — and the language of the double opt-in confirmation email a ticked email consent question sends (written with the account's own wording for that language from Settings → Email preferences → Double opt-in, otherwise the standard wording in it); the consent record keeps the language too. It never translates anything the business wrote: the questions, the consent wording (recorded word for word as shown), the submit button and the thank-you message stay exactly as written, so a German version of a form is a copy (forms.duplicate) with German wording and this set to de. Saves the draft: visitors and new submissions follow it once the form is published again (forms.publish). Sends nothing.

Also answers to form in German, change the language of a form, translate a form's buttons, send the double opt-in email in German for this form.

Parameters

FieldTypeRequiredDescription
idstring (uuid)requiredThe form to change. Works whether it is live, draft or archived.
language"" | "en" | "en-GB" | "de" | "fr" | "es" | … 6 morerequiredThe form's language: en (English (US)), en-GB (English (UK)), de (German), fr (French), es (Spanish), nl (Dutch), it (Italian), sv (Swedish), da (Danish), nb (Norwegian), fi (Finnish) — or an empty string to follow the account's language (Settings → Business profile → Account language), which is the default.

Example

curl -X POST https://app.chirply.io/api/v1/actions/forms.set_language \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11",
    "language": ""
  }'
Test with your API key

Over MCP the same operation is the tool forms_set_language at https://app.chirply.io/api/mcp, same bearer token, same input.

Question mapping

forms.set_question_mappingwriteconfirm

Point one question at the CRM: which contact field its answer fills, whether a later submission may REPLACE what is already stored there, and — for a consent question — which marketing permission switches its latest answer controls. Configuration only; it writes nothing to any contact by itself, but it decides what every future submission of this form does. Mapping a consent question to a permission means a ticked box switches that channel on and an UNTICKED box switches it off and records a withdrawal, so the newest answer always wins — unless unticked_keeps_permission is on, in which case only a tick changes anything.

Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.

Also answers to map a form question to a contact field, make a consent box set email permission, overwrite contact fields from a form.

Parameters

FieldTypeRequiredDescription
form_idstring (uuid)requiredThe form that owns the question.
question_idstringrequiredThe question's `id` from the form's definition — read it with forms.get, never guess.
contact_field"first_name" | "last_name" | "email" | "phone" | "company" | ""optionalThe CRM field this answer fills. Only short-text, email and phone questions can carry one. Pass an empty string to unmap. Two questions cannot own the same field: the earlier one keeps it.
overwrite_contact_fieldbooleanoptionalOFF by default and that default is the safe one: the answer only fills the contact field when it is empty. ON makes every submission replace what is stored, which is what you want for a 'keep my details up to date' form. Accepted ONLY for first_name, last_name and company — a public form is unauthenticated, so letting it repoint an existing contact's email or phone would let anyone who knows an address redirect every future message to themselves.
explicit_consentbooleanoptionalConsent questions only. ON stores an untouched box as an explicit false instead of leaving the answer out, so 'declined' and 'never asked' stop being the same value. It also makes the question count as ANSWERED in your logic rules, which is why it is opt-in rather than automatic for forms that are already live.
permission_channelsarray of ("email" | "sms")optionalConsent questions only. The contact permission switches this question's LATEST answer controls: 'email' is Emails Allow, 'sms' is text messages. Ticked grants, unticked withdraws — both written to the same switch the unsubscribe center uses and both recorded on the contact with the date and the exact wording shown. Pass an empty array to stop the question controlling permission. Setting any channel forces explicit_consent on, because a withdrawal cannot be expressed by an answer that is not there — except with unticked_keeps_permission, which withdraws nothing.
unticked_keeps_permissionbooleanoptionalConsent questions with permission_channels only. ON: only a tick changes permission — an unticked box, or a submission that leaves the answer out (for example a forms API caller that omits unticked boxes), leaves the contact's existing permission exactly as it is, so a later submission never unsubscribes someone who already agreed. Use it for an optional newsletter box on a form people send for other reasons. OFF, the default: the newest answer wins and an unticked box withdraws. The builder labels it 'Unticked leaves permission as it is'.

Example

curl -X POST https://app.chirply.io/api/v1/actions/forms.set_question_mapping \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "form_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11",
    "question_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool forms_set_question_mapping at https://app.chirply.io/api/mcp, same bearer token, same input.

Save answers to the contact

forms.set_save_answerswrite

Turn a form's 'Save answers to the contact' setting on or off. When ON, every NEW completed response that is linked to a contact adds one internal note to that contact, titled 'Answers from <form name>', listing every answer in full and linking back to the response — so the answers travel with the contact record without a Form submitted workflow for each form. Nobody is emailed or texted by the note itself, but it is a real note: it shows in the contact's Notes and timeline, and any workflow listening for 'Note added' will run for it. Takes effect as soon as it is saved, without republishing, and applies only to responses completed afterwards — earlier responses already show on the contact's Forms tab and timeline (forms.list_contact_responses) and are not copied. Turning it off stops new notes; notes already written stay. Off by default.

Also answers to log form answers on the contact, copy form answers into a contact note, save form responses to the contact record.

Parameters

FieldTypeRequiredDescription
idstring (uuid)requiredThe form to change. Works whether it is live, draft or archived.
enabledbooleanrequiredtrue adds a note of every answer to the contact for each new completed response; false stops it. Notes already written are not removed.

Example

curl -X POST https://app.chirply.io/api/v1/actions/forms.set_save_answers \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11",
    "enabled": true
  }'
Test with your API key

Over MCP the same operation is the tool forms_set_save_answers at https://app.chirply.io/api/mcp, same bearer token, same input.

Form results

forms.statsread

Get the four headline numbers from a form's Results screen: how many times the public form was VIEWED, how many responses were completed, how many were left partial, and the conversion rate (completed as a percentage of views, rounded). forms.list_responses returns the responses but has no view count, so conversion cannot be worked out from it — this is the only place that number exists. Counts cover the form's whole lifetime. This only reads data.

Parameters

FieldTypeRequiredDescription
form_idstring (uuid)requiredThe form to report on.

Example

curl -X POST https://app.chirply.io/api/v1/actions/forms.stats \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "form_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool forms_stats at https://app.chirply.io/api/mcp, same bearer token, same input.

Submit response

forms.submit_responsewriteconfirm

Submit answers to a published form as a real completed response. This can create or update a CRM contact and immediately start any workflows listening for this form, which may send real email, SMS, or calls billed to the account.

Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.

Parameters

FieldTypeRequiredDescription
form_idstring (uuid)requiredThe published form receiving the response.
session_idstringrequiredA caller-generated idempotency key for this respondent session. Reusing one overwrites that person's earlier answers instead of adding a second response, so use a fresh random value per respondent.
answersmap of string → objectrequiredThe respondent's answers, keyed by QUESTION ID (the `id` field of each question in the form's definition — get them from forms.get or forms.get_share_links, never guess). A hidden/text/email/phone/date answer is a string, a number/rating/scale answer is a number, a consent answer is a boolean, a single_choice or dropdown answer is the chosen option's `value` (not its label), a multiple_choice answer is an array of those values, and a file answer is the object returned by forms.upload_response_file. A hidden field may also be keyed by its `parameterName` instead of its id — {"consent_version":"2026-11-13"} — and the id wins when both are sent. Other keys that do not match a question are discarded. Example: {"q_1":"jane@example.com","q_2":"11_plus","q_3":"Our follow-up is a mess","q_4":["email","sms"],"q_5":{"path":"org/form/session/q_5/1699-brief.pdf","name":"brief.pdf","size":10240,"type":"application/pdf"}}

Example

curl -X POST https://app.chirply.io/api/v1/actions/forms.submit_response \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "form_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11",
    "session_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11",
    "answers": {}
  }'
Test with your API key

Over MCP the same operation is the tool forms_submit_response at https://app.chirply.io/api/mcp, same bearer token, same input.

Unpublish

forms.unpublishwriteconfirm

Take a public form offline. Existing responses remain available, but its hosted link stops accepting new ones.

Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.

Parameters

FieldTypeRequiredDescription
idstring (uuid)requiredThe form to take offline.

Example

curl -X POST https://app.chirply.io/api/v1/actions/forms.unpublish \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool forms_unpublish at https://app.chirply.io/api/mcp, same bearer token, same input.

Save form

forms.updatewrite

Save a form's draft name, description, question definition, behavior, or design. WHOLE-OBJECT REPLACEMENT: `definition`, `settings` and `theme` are each stored as a single JSON blob, so passing one REPLACES it outright — send a definition with two questions and a form that had ten now has two, and the eight you left out are gone along with any logic rules that referenced them. Never assemble one of these from just the parts the request mentioned; read the current object with forms.get, change what you need, and send the whole thing back. Fields you omit entirely are untouched. Published visitors keep seeing the prior snapshot until Publish is run, so a mistake here is recoverable right up until then.

Parameters

FieldTypeRequiredDescription
idstring (uuid)requiredThe form to update.
namestringoptionalNew internal form name.
descriptionstring (or null)optionalThe form's introduction, shown above the first question and used as the page's link-preview description, or null to clear it. Takes the same formatting as a question's description (line breaks, **bold**, *italic*, links, headings, lists); link previews show the plain words.
kind"form" | "survey" | "quiz"optionalNew experience type.
definitionmap of string → objectoptionalThe COMPLETE question definition, which REPLACES the stored one entirely — anything you leave out is deleted, so read the current value with forms.get and edit that rather than sending a fragment. Three keys. `questions` is an ordered array; each has `id` (stable string; answers are keyed by it, so never renumber an existing question), `type` (one of short_text, long_text, email, phone, number, single_choice, multiple_choice, dropdown, rating, scale, date, file, signature, consent, statement, hidden), `title`, and optionally `description`, `placeholder`, `required`, `page`, `min`/`max`, `lowLabel`/`highLabel`, `options` (for choice types: `{id,label,value,points}` — `points` is what a quiz scores), and `contactField` (one of first_name, last_name, email, phone, company — this is what makes a completed response create or update a CRM contact; email and phone questions map themselves by default). Question `title` and `description` values show on the public form with their line breaks and simple formatting: `**bold**`, `*italic*`, and links — a bare https URL, or `[words](https://address)` to show the words as the link (e.g. a consent box reading `…as described in our [privacy policy](https://example.com/privacy).`). Only http(s) addresses become links; nothing is ever treated as HTML. A `description` also takes blocks: a blank line starts a new paragraph, and a line starting `# `, `## ` or `### ` is a heading (largest to smallest), `- ` a bulleted item and `1. ` a numbered item. A `statement` question is a Text block — words with no answer: `title` is its heading (up to 300 characters) and `description` its text (up to 5,000 characters; every other question type keeps up to 1,000 characters of `description` as its hint). A `hidden` question is stored with answers but never rendered to visitors or counted in page progress. Optional `defaultValue` (blank by default, max 2000 characters) fills omitted answers; `parameterName` (blank by default, max 80 characters) reads that query parameter from a hosted link or embed host page. Submitted answers keyed by its question ID override the default, including an empty string; a submission may also key the value by its `parameterName` (for example consent_version), unless that name is another question ID. Hidden values are untrusted visitor input, not verified consent or identity; no contact mapping or required flag applies. `logic` is an array of show/hide rules: `{id,sourceQuestionId,operator,value,action,targetQuestionId}` where operator is equals, not_equals, contains, answered or not_answered. `outcomes` scores a quiz into a result: `{id,title,message,minScore,maxScore,redirectUrl}`. Example: {"questions":[{"id":"q_1","type":"email","title":"Your work email","required":true,"contactField":"email"},{"id":"q_2","type":"single_choice","title":"How big is your team?","options":[{"id":"opt_1","label":"1-10","value":"1_10","points":5},{"id":"opt_2","label":"11 or more","value":"11_plus","points":10}]},{"id":"q_3","type":"long_text","title":"What are you trying to fix?"}],"logic":[{"id":"rule_1","sourceQuestionId":"q_2","operator":"equals","value":"11_plus","action":"show","targetQuestionId":"q_3"}],"outcomes":[{"id":"outcome_1","title":"Great fit","message":"We will be in touch.","minScore":10}]}
settingsmap of string → objectoptionalThe COMPLETE behavior settings object, which REPLACES the stored one entirely — omitted keys fall back to defaults rather than keeping their current value, so read forms.get first. Keys: `submitLabel` (the submit button's wording), `successTitle` and `successMessage` (the thank-you screen), `redirectUrl` (send them to your own page instead), `showProgress`, `oneQuestionAtATime`, `savePartial` (keep half-finished answers), `allowMultiple` (let one person answer more than once), `collectContacts` (create/update CRM contacts from completed responses), `buttonAlignment` (left, center or full), `privacyText`, `closedTitle`/`closedMessage` (what the link says once the form is closed), `language` (the language the form is shown in — a code such as de; leave it out to follow the account language; forms.set_language changes just this) and `saveAnswersToContact` (true adds one internal note with every answer to the contact of each new completed response, labelled Save answers to the contact in the builder; only a literal true turns it on, and it takes effect on save without republishing; forms.set_save_answers changes just this one switch). Example: {"submitLabel":"Send response","successTitle":"You are all set","successMessage":"Thanks - your response has been received.","redirectUrl":"https://example.com/thanks","showProgress":true,"oneQuestionAtATime":false,"savePartial":true,"allowMultiple":true,"collectContacts":true,"buttonAlignment":"left","privacyText":"We never share your details.","saveAnswersToContact":false}
thememap of string → objectoptionalThe COMPLETE visual theme, which REPLACES the stored one entirely. The five colors are six-digit hex strings and anything else is ignored: `brand` (buttons and accents), `background` (the page behind the form), `surface` (the card), `text`, `muted`. Plus `radius` (none, soft or round) and `font` (clean, friendly or editorial). Example: {"brand":"#f45d48","background":"#f4f5f7","surface":"#ffffff","text":"#172033","muted":"#667085","radius":"soft","font":"clean"}

Example

curl -X POST https://app.chirply.io/api/v1/actions/forms.update \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool forms_update at https://app.chirply.io/api/mcp, same bearer token, same input.

Rename or move form folder

forms.update_folderwrite

Rename a folder on the Forms page and/or move it inside another top-level folder (`parent_id`), or back to the top level (`parent_id: null`). Fields you omit are left as they are. A folder that holds sub-folders stays at the top level. The forms filed in it go wherever it goes; no form changes.

Also answers to rename a forms folder, move a form folder into another folder.

Parameters

FieldTypeRequiredDescription
idstring (uuid)requiredThe folder to change (from forms.list_folders).
namestringoptionalIts new name.
parent_idstring (uuid) (or null)optionalA TOP-LEVEL folder id to put it inside, or null to make it a top-level folder. Omit to leave it where it is.

Example

curl -X POST https://app.chirply.io/api/v1/actions/forms.update_folder \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'
Test with your API key

Over MCP the same operation is the tool forms_update_folder at https://app.chirply.io/api/mcp, same bearer token, same input.

Upload response file

forms.upload_response_filewriteconfirm

Upload one file as the answer to a form question of type 'file' — the only way to answer that question type, since an answer to it is a stored file rather than text. Limits match the public form exactly: at most 10 MB, and only JPEG, PNG or WebP images, PDFs, plain text, or Word documents (.doc/.docx). THE SERVER DECIDES THE FILE'S TYPE, from the extension on `filename` plus the uploaded bytes' own signature — nothing you declare is stored or served, and a file whose contents do not match its extension (an HTML page named .png) is refused outright rather than filed away under the type it claimed. The file is written to the account's private form-uploads storage and STAYS THERE permanently, counting against the account's storage; there is no capability that deletes it. This does not answer the question by itself — take the object it returns and put it in `answers` under that question's id when you call forms.save_partial_response or forms.submit_response.

Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.

Parameters

FieldTypeRequiredDescription
form_idstring (uuid)requiredThe published form the file is being uploaded for.
session_idstringrequiredThe respondent session this file belongs to — the SAME value used for forms.save_partial_response and forms.submit_response.
question_idstringrequiredThe id of the question being answered. It must exist in the form's published definition and be of type 'file'.
filenamestringrequiredThe original file name, e.g. 'brief.pdf'. Its EXTENSION is load-bearing: it selects which format the upload is checked against — one of jpg, jpeg, png, webp, pdf, txt, doc, docx — and for an image or PDF the bytes must actually be that format or the upload is refused. A .txt or .doc whose bytes are not what the name promised is stored as a plain download instead of being refused, since a text file in an older Windows encoding is still a real text file. If the name carries no extension at all, or one not on that list, the bytes are read instead and the file is accepted only if they are one of those same formats. Also shown to staff reading the response and in the CSV export; unusual characters are replaced.
content_typestringoptionalADVISORY ONLY, and safe to omit. The type the file is stored and served as is derived from its own bytes, never from this value, so sending a wrong or malicious one changes nothing — it is neither stored nor echoed back. Accepted so existing integrations that send it keep working; read the `file.type` in the result for the type actually recorded.
content_base64stringrequiredThe file's bytes, base64-encoded (no data: URL prefix). Must decode to 10 MB or less.

Example

curl -X POST https://app.chirply.io/api/v1/actions/forms.upload_response_file \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "form_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11",
    "session_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11",
    "question_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11",
    "filename": "Example",
    "content_base64": "example"
  }'
Test with your API key

Over MCP the same operation is the tool forms_upload_response_file at https://app.chirply.io/api/mcp, same bearer token, same input.

The machine-readable version of this page is GET https://app.chirply.io/api/v1/actions?domain=forms — same operations, with full JSON Schemas. Authentication, errors and rate limits are covered in the API documentation home.