Kindly EditDocumentationTry the editor

Kindly Forms developer reference

Storage, permissions, PHP functions, REST routes, every hook and filter, and how to add field types and connections.

This page is for developers: how Kindly Forms stores forms and entries, its permission words, its REST routes, the PHP functions worth calling, every hook and filter, and how to add a field type or a connection. The source is includes/forms/ in the plugin. The builder and hub are plain JavaScript in assets/forms/ with no build step.

Storage#

A form is a post of type kindly_form. It is never public on its own address: it shows through the [kindly_form] shortcode, a page's Form element, or its landing page.

Where Holds
Post title and status The form's name. publish is open to visitors, draft is closed, trash is in the trash
Meta _kf_live The published definition, as JSON
Meta _kf_draft The builder's unpublished version, when there is one
Meta _kf_history Earlier versions for History (20 by default, filter kindly_forms_history_size)
Option kindly_forms_settings Site-wide settings (Kindly Edit > Forms > Settings). Read with kindly_forms_setting( 'dot.path', $default )
Option kindly_forms_connections Site-wide connection keys and accounts, per provider. Secrets never leave the server: REST answers show them as __kept__
Option kindly_forms_inventory Shared stock items

A definition is one JSON object: title, fields (a tree: columns, sections and groups hold their own fields), settings, notifications (emails) and feeds (connections). Every field is { id, type, name, ...settings }. Anything left out takes its default when read.

Entries and everything about them live in custom tables, named with the site's prefix plus kf_. kindly_forms_table( 'entries' ) returns the full name.

Table Holds
kf_entries One row per entry: form, serial number, status, favorite, user, source address, IP, browser, device, country, payment status and total, the answers as JSON, dates
kf_values Each answer again as its own row, indexed for filters and reports
kf_meta Entry notes, status changes, connection results and other entry history
kf_logs Activity and API logs, with secrets removed
kf_queue Connections waiting to be sent or tried again
kf_drafts Saved progress and partial entries
kf_views Daily views, starts and sends per form
kf_transactions, kf_subscriptions, kf_coupons Payments
kf_stock Stock held and used per entry

The tables are created and upgraded with dbDelta when the schema version (option kindly_forms_db) changes.

Permissions#

Every REST route, ability and screen checks kindly_forms_can( $what, $form_id ). The words and the WordPress capability each needs by default:

Word Allows Default capability
manage Opening Kindly Edit > Forms and the forms list edit_others_pages
edit Building and changing forms edit_others_pages
entries Reading entries and logs edit_others_pages
entries_edit Changing entries: status, notes, answers, approval, resending edit_others_pages
entries_delete Deleting entries edit_others_pages
reports Reports edit_others_pages
settings Site-wide settings and connections manage_options
payments Payments, refunds, coupons and payment settings manage_options

Settings > Managers gives named people chosen rights without changing their role. It never grants settings, so a manager can't widen anyone's access. The kindly_forms_can filter receives ( $ok, $what, $form_id, $user_id ) for your own rules.

PHP functions#

Function Does
kindly_forms_get( $id, $draft = false ) A form's definition with id, title, status, pending (has a draft) and modified. With $draft, the builder's unpublished version when there is one. null if missing
kindly_forms_create( $def, $status = 'publish' ) Makes a form from a definition. Returns its ID or a WP_Error
kindly_forms_save( $id, $def, $live = false, $label = '' ) Saves a definition as the draft, or straight live with $live. Adds a history entry
kindly_forms_publish( $id ), kindly_forms_discard( $id ) Puts the draft live, or drops it
kindly_forms_render( $id, $o = [] ) The form's HTML, as the shortcode prints it
kindly_forms_submit( $form_id, $in ) Runs the whole sending pipeline (checks, spam, entry, emails, connections, payment) for input shaped like a visitor's send. Returns { ok, message, ... }
kindly_forms_smart( $text, $ctx ) Replaces smartcodes such as {inputs.email} and {all_data}. See the smartcode reference
kindly_forms_entry_get( $id ), kindly_forms_entry_create( $row ), kindly_forms_entry_update( $id, $changes ) Read, add and change entries
kindly_forms_entries_query( $q ) A page of entries: [ $rows, $total ]. Keys: form, status, search, from, to, page, per, orderby, order, filters
kindly_forms_entry_note( $entry_id, $key, $value, $form_id ) Adds a note or history line to an entry
kindly_forms_log( $form, $entry, $kind, $component, $status, $title, $message ) Writes a line to the logs. $kind is activity or api; $status is success, failed or info
kindly_forms_setting( 'dot.path', $default ) A site-wide setting
kindly_forms_can( $what, $form_id ) The permission check above

Shortcodes and addresses#

Shortcode Shows
[kindly_form id="12"] The form. title="yes" shows its title above it
[kindly_forms_results form="12" field="color" labels="yes" counts="yes"] Survey results of a published form, for one field or all of them
[kindly_forms_receipt] A payment receipt, on the receipt page a payment links to
[kindly_forms_payments] The signed-in person's own payments and subscriptions
[gravityform id="12"], [gravityforms id="12"] and the gravityforms/form block The Kindly form imported from Gravity form 12 with Show for [gravityform] shortcodes and blocks on (since 0.12.0). While Gravity Forms is active it still draws every form nobody imported

The site also answers a few addresses of its own: landing pages (a base path plus the form's slug, see Quizzes, landing pages and post forms), the answers page, signed PDF download links (kindly_pdf), save-and-continue links (?kf_resume=), a confirmation page opened with Fill smartcodes on that page (?kf_entry=, signed, never cached and not indexed; since 0.12.0), and admin-post.php actions for sending without JavaScript (kindly_forms_submit), email confirmation (kindly_forms_confirm), private file downloads (kindly_forms_file, kindly_forms_cloud_file), account verification (kindly_forms_verify_user), service sign-in (kindly_forms_oauth_start, kindly_forms_oauth) and canceling a subscription (kindly_forms_sub_cancel).

REST routes#

Everything the builder and hub show comes from these routes, under /wp-json/kindly-forms/v1. Signed-in requests use WordPress cookie authentication with the X-WP-Nonce header, or an application password. A form on a page sends as the signed-in person: for someone signed in, its script gets a nonce from the kindly_forms_nonce admin-ajax action (never cached, readable only by the site's own pages; a visitor gets an empty one) and renews it there if it expires while the page is open. No nonce is printed in the page, so cached pages are safe, and /token never hands one to a request that isn't already authenticated. "Who" names the permission word checked, for the form the request touches.

For visitors#

Method and route Who Does
GET /token?form=ID anyone A fresh anti-spam token for the form, and counts a start when asked (start=1)
POST /count?form=ID anyone Counts a view of a published form. The form's script sends it when analytics are on (count in data-kf-config), so cached pages count too; the server decides whether this visitor counts (not someone who can edit the form, not a bot)
POST /submit anyone Sends a form. Answers 200 when accepted, 422 with errors, 429 when rate limited
POST /upload anyone Uploads one file for an upload field before sending
POST /resume anyone Saves progress for save and continue, and emails the link when asked
POST /coupons/check anyone Checks a coupon against the form's order
POST /payments/webhook/{gateway} anyone A payment service's notice, verified by that service's signature
GET /payments/return anyone The return from a hosted checkout (signed)
POST /payments/confirm anyone The browser finished an on-page payment step (signed)

The token, send, upload and save answers are never cached. Nothing from the browser is believed about amounts or payment status: the payment service is asked.

Forms and the builder#

Method and route Who Does
GET /schema edit Field types and their settings, smartcodes, presets, countries, taxonomies, roles and pages, for the builder
GET /forms manage The forms list with entry, unread and view counts and the pages using each form. status, search
POST /forms { title?, template?, definition?, status? } edit A new form, blank, from a template or from a definition
GET /forms/{id} edit The form, with its draft when there is one
PUT /forms/{id} { definition?, live?, label?, modified?, force?, status? } edit Saves the draft (or live). With modified, refuses with 409 when someone else saved since
DELETE /forms/{id} edit Moves it to the trash. With force, deletes it and its entries (needs entries_delete)
POST /forms/{id}/publish, /discard, /duplicate, /restore, /untrash edit Publish the draft, drop it, copy the form, restore a version (at), or take it out of the trash
GET /forms/{id}/history edit Saved versions with who and when
POST /render edit The form's HTML for the builder's canvas or a preview
GET /templates edit The templates, flat and by category
GET /forms/export?ids= manage Form definitions as a JSON download
POST /forms/import edit A Kindly Forms, Fluent Forms or Gravity Forms JSON file. See Import and templates
GET /gravity/forms edit The site's own Gravity Forms forms (id, title, active, entry count, already imported), for From Gravity Forms (since 0.12.0)
POST /gravity/import { ids, shortcode?, entries? } edit Imports those Gravity forms with their add-on feeds. shortcode (on unless false) lets [gravityform] show the Kindly form; entries also copies their entries, only for people with entries_edit whom Gravity Forms lets view entries. 404 when Gravity Forms isn't on the site (since 0.12.0)

Entries, reports and logs#

Method and route Who Does
GET /entries?form=ID entries A page of entries with counts by status. status, search, from, to, page, per, orderby, order, payment, filters
GET /entries/{id} entries One entry with readable answers, notes, payments and the next and previous IDs. payments.subscriptionLive is true while one of its subscriptions hasn't ended. Marks it read unless peek
PUT /entries/{id} { status?, favorite?, values? } entries_edit Changes status or star, or edits answers (files and passwords stay as they were)
DELETE /entries/{id} entries_delete Deletes it for good. Its payments and subscriptions are kept and nothing is canceled with the payment service
POST /entries/{id}/note, /resend, /approve, /decline, /confirm entries_edit Adds a note, sends an email again, approves, declines, or confirms an unconfirmed entry by hand
POST /entries/bulk { ids, action } entries_edit read, unread, spam, trashed, restore, favorite, unfavorite, approve, decline, delete (needs entries_delete), feeds (runs connections again)
GET /export entries Entries as CSV, XLSX, ODS, JSON or a print page (a download)
POST /entries/import entries_edit A CSV or JSON file into a form's entries: a preview step, then a run with a column mapping
GET /reports reports Views, starts and sends per day, conversion, answers per choice, averages and payments
GET /logs, GET /logs/{id}, DELETE /logs entries, entries_delete Activity and API logs, secrets removed
GET /unfinished, DELETE /unfinished entries, entries_delete Saved progress and partial entries
GET /queue, POST /queue/{id}/retry, POST /queue/retry entries, entries_edit Connections waiting or failed, and trying them again
GET /prefs, PUT /prefs manage The person's own entries columns and page size per form
GET /users settings People to choose in Settings > Managers
GET /settings, PUT /settings settings Site-wide settings. Secrets show as __kept__ and keep their value when sent back that way

Connections#

Method and route Who Does
GET /connections settings Every provider and whether it is connected (no secrets)
GET /connections/{provider} settings Its values with secrets as __kept__, and sign-in links
PUT /connections/{provider}, DELETE /connections/{provider} settings Save and check, or disconnect
POST /connections/{provider}/test settings Check the saved connection again
GET /connections/{provider}/lists edit Choices from the service (lists, tags, boards), kept for 10 minutes
GET /connections/{provider}/map edit Mapping rows fetched from the service
POST /connections/{provider}/sample edit Sends made-up answers through one connection
GET /connections/{provider}/oauth settings The sign-in address to open

Stock, documents and payments#

Method and route Who Does
GET /inventory, POST /inventory edit Shared stock items with where they are used, and adding one
PUT /inventory/{slug} edit Renames it or changes its total
DELETE /inventory/{slug}, POST /inventory/{slug}/reset settings Removes it, or starts its count again
GET /forms/{id}/inventory edit What this form uses
GET /forms/{id}/pdf/setup edit What the Documents tab needs: starting points, fonts, paper sizes, defaults and recent entries
POST /forms/{id}/pdf/preview edit A preview of a document
GET /forms/{id}/entries/{entry}/pdf/{doc} entries One entry's document
POST /forms/{id}/entries/pdf entries Documents of several entries in one zip (up to 100, filter kindly_forms_pdf_zip_limit)
GET /payments/settings, PUT /payments/settings payments Payment settings, secrets as __kept__
GET /transactions, GET /subscriptions payments Lists
POST /payments/{tx}/refund, POST /payments/{tx}/status payments Refund, or change a payment's status by hand
POST /subscriptions/{id}/cancel payments Cancels a subscription
GET /coupons, POST /coupons, PUT /coupons/{id}, DELETE /coupons/{id} payments Coupons

Moving a page form#

GET and POST /wp-json/cantata-edit/v1/forms/{post}/{form}/convert turn an old page Form into a Kindly form. They need permission to edit the page and manage. See Moving an old page form.

AI abilities#

The kindly-forms/* abilities run through WordPress's own abilities routes, not this namespace. See AI and Kindly Forms.

Hooks and filters#

Every literal kindly_forms_ hook, by area. A name ending in {type}, {provider} or {event} is built from that value. Arguments are listed in order.

Forms, permissions and settings#

Hook Type Arguments Use
kindly_forms_can filter $ok, $what, $form_id, $user_id Grant or refuse a permission word
kindly_forms_normalize filter $clean, $def The cleaned definition before it is stored
kindly_forms_clean_feed_{provider} filter $clean, $feed Clean one provider's connection settings when a form is saved
kindly_forms_created action $id, $def A form was made
kindly_forms_saved action $id, $def, $live A form was saved (draft, or live)
kindly_forms_published action $id A draft went live
kindly_forms_history_size filter 20 How many versions History keeps
kindly_forms_settings_saved action $settings Site-wide or payment settings were saved
kindly_forms_schema filter $schema What GET /schema gives the builder
kindly_forms_canvas_css filter $urls Stylesheets the builder's canvas loads (the theme's, Kindly's element styles, the forms styles)
kindly_forms_templates_dirs filter $dirs Folders of template files
kindly_forms_templates filter $list The templates offered
kindly_forms_template filter $def, $key, $template The definition a template makes
kindly_forms_import_fluent_field filter null, $element, $ctx Return a Kindly field (or a list) for a Fluent Forms element
kindly_forms_import_fluent_definition filter $def, $item, $notes A Fluent Forms form after conversion
kindly_forms_import_gravity_definition filter $def, $form, $notes A Gravity Forms form after conversion (since 0.12.0)
kindly_forms_gravity_addons_on filter $registered Gravity add-ons counted as switched on, keyed by slug. A feed whose add-on isn't listed comes over switched off (since 0.12.0)
kindly_forms_import_max filter 20000 Most rows an entries import takes, also the most Gravity entries copied per form
kindly_forms_legacy_converted action $form_id, $post_id, $old_form An old page form was moved to Kindly Forms
kindly_forms_mcp_on filter $on Whether the AI abilities work

Fields and showing the form#

Hook Type Arguments Use
kindly_forms_field_types filter $types Add or change field types (see below)
kindly_forms_render_{type} filter null, $field, $ctx Return HTML to draw a field type yourself
kindly_forms_field_render filter $field, $ctx Change a field before it is drawn, or return a non-array to hide it
kindly_forms_field_choices filter $choices, $field, $ctx A field's choices, manual or dynamic
kindly_forms_source_rows filter $rows, $source, $ctx Rows a dynamic source found, before they become choices
kindly_forms_presets filter $presets Ready-made choice lists (US states, months, ages and more)
kindly_forms_countries filter $countries The country list
kindly_forms_file_groups filter $groups Upload file type groups. Executables are never accepted
kindly_forms_public_user_meta filter [ 'description', 'nickname' ] User meta a user source may show
kindly_forms_render_options filter $options, $id Options for drawing a form
kindly_forms_before_render filter $def, $options The definition about to be drawn
kindly_forms_rendered filter $html, $def, $options The finished HTML
kindly_forms_public_config filter $config, $def Settings handed to the visitor's browser
kindly_forms_enqueue action $needs Scripts and styles the page needs (date picker, phone, captcha)
kindly_forms_button_class filter $class The send button's class (the theme's button class by default)
kindly_forms_closed filter null, $def, $ctx Return [ code, message ] to close a form
kindly_forms_page_definition filter $def The form shown on its landing page or answers page
kindly_forms_webmcp filter true, $def Whether the form describes itself to visitors' AI assistants

Sending and entries#

Hook Type Arguments Use
kindly_forms_submit_definition filter $def, $input The definition a send is checked against
kindly_forms_collect_{type} filter null, $value, $field, $raw Return the cleaned value of a field type
kindly_forms_values filter $values, $def, $input All cleaned answers
kindly_forms_validate_{type} filter null, $value, $field, $values, $def Return an error message for a field type
kindly_forms_validate filter $errors, $values, $def, $input All errors, keyed by field name
kindly_forms_is_spam filter $spam, $def, $values, $input Mark a send as spam (kept quietly as spam)
kindly_forms_token_min_age filter 2 Seconds a token must be old before a send counts
kindly_forms_ip_headers filter [] Proxy headers to trust for the visitor's IP. None by default, since headers can be forged
kindly_forms_entry_row filter $row, $def, $input The entry about to be stored
kindly_forms_before_insert action $row, $def, $input Just before it is stored
kindly_forms_submitted action $entry, $def, $input An entry was stored (not for spam)
kindly_forms_refused action $def, $values, $reason A send was refused after its answers were read (spam when Akismet's answer is set to refuse); nothing was stored
kindly_forms_event action $event, $entry, $def Emails and connections ran for an event: submit, payment, confirmed, approved, declined, pending
kindly_forms_event_{event} action $entry, $def The same, for one event
kindly_forms_submit_result filter $result, $def, $entry What the visitor's browser gets back. For an entry waiting for an email confirmation or approval, $result['gate'] is unconfirmed or pending
kindly_forms_entry_status action $id, $new, $old An entry's status changed
kindly_forms_entry_deleting action $entry An entry is about to be deleted
kindly_forms_smartcode filter null, $group, $key, $ctx Return a value for your own smartcode
kindly_forms_report_choices filter $types Field types reported as counts per choice
kindly_forms_report_numbers filter $types Field types reported as averages

Emails#

Hook Type Arguments Use
kindly_forms_send_notification filter true, $email, $def, $entry Return false to skip one email
kindly_forms_notification_attachments filter $files, $email, $def, $entry Files attached to an email
kindly_forms_mail filter $message, $def, $entry, $kind A message about to be sent in the site's email layout: to, subject, body, from, reply-to, copies, attachments
kindly_forms_email_html filter null, $body, $subject, $def Return your own email layout
kindly_forms_notification_to_visitor filter $to_visitor, $email Whether an email goes to the person who filled in the form (it is then sent in their language)

Connections and file storage#

Hook Type Arguments Use
kindly_forms_feed_providers filter $providers Register a connection (see below)
kindly_forms_feed_failed action $feed, $entry, $def, $result A connection failed for good after its tries
kindly_forms_queue_spawn filter true Whether to start WordPress cron at once when a connection is queued
kindly_forms_notion_version filter '2026-03-11' The Notion API version sent
kindly_forms_openai_model filter '' The OpenAI model used by that connection
kindly_forms_clearout_message filter $message The message when an email address fails the Clearout check
kindly_forms_storage_ops filter $ops Each storage service's upload and link steps
kindly_forms_storage_chunk_size filter 8 MB, $provider Upload piece size
kindly_forms_storage_single_max filter $bytes, $provider Largest file sent in one request
kindly_forms_storage_s3_min_part filter 5 MB Smallest S3 part
kindly_forms_storage_time_budget filter $seconds Time one background run may spend uploading
kindly_forms_storage_open_seconds filter 300 How long a cloud file link made for a person works

Payments and stock#

Hook Type Arguments Use
kindly_forms_payments_on filter $on Whether payments are on for the site
kindly_forms_payment_gateways filter $gateways Register a payment gateway
kindly_forms_payment_conf filter $conf, $gateway A gateway's settings
kindly_forms_payment_form_settings filter $settings, $def A form's payment settings
kindly_forms_currencies filter $list Currencies offered
kindly_forms_payment_prepare filter [], $def, $values, $input The payment worked out before the entry is stored
kindly_forms_payment_order filter $payment, $def, $values The order: items, totals, coupons
kindly_forms_payment_start filter null, $def, $entry, $payment, $input The next step for the browser: a checkout or a card to confirm
kindly_forms_payment_result filter $result, $tx, $def, $entry What the browser gets after a payment step
kindly_forms_payment_paid action $entry, $tx, $def A payment succeeded
kindly_forms_payment_status action $tx, $status, $was A payment's status changed
kindly_forms_payment_refunded action $tx, $refund, $full A refund was made
kindly_forms_payment_reversed_statuses filter [ 'refunded', 'partially-refunded', 'canceled' ] Statuses a late success never overwrites
kindly_forms_payment_abandon_hours filter 24 Hours before an unfinished payment counts as abandoned
kindly_forms_payment_card_tries filter 10 Cards one network address may try in an hour on cards typed on the page
kindly_forms_payment_smart_custom filter '', $key, $ctx, $tx, $subscription Your own payment smartcodes
kindly_forms_subscription_payment action $subscription, $tx, $entry A subscription was charged again
kindly_forms_subscription_status action $subscription, $status A subscription's status changed
kindly_forms_payments_reset action none Payment settings were saved; cached gateway details should be dropped
kindly_forms_coupon_ok filter true, $coupon, $def, $subtotal Whether a coupon applies
kindly_forms_coupon_message filter $message, $reason, $coupon, $def, $subtotal The message when it doesn't
kindly_forms_stripe_shipping_countries filter $countries Countries Stripe Checkout asks shipping for
kindly_forms_square_notification_url filter $url Square's notification address
kindly_forms_authnet_arb_tries filter 6 Tries from cron to set up an Authorize.Net subscription that Authorize.Net wasn't ready to bill (E00040) before it is marked failing (since 0.12.0)
kindly_forms_authnet_arb_wait filter 5 Seconds between the tries made during the payment itself (since 0.12.0)
kindly_forms_inventory_release action $entry_id, $reason Gives an entry's stock back (fired on a failed payment)
kindly_forms_inventory_restore action $entry_id, $reason Takes it again (fired when a payment succeeds after all)

PDF documents#

Hook Type Arguments Use
kindly_forms_pdf_starters filter $starters, $def Starting points in the Documents tab
kindly_forms_pdf_fonts filter $fonts Fonts offered
kindly_forms_pdf_fallback_fonts filter [] Extra fonts for characters the bundled fonts lack, such as Chinese, Japanese or Korean
kindly_forms_pdf_papers filter $sizes Paper sizes, in points
kindly_forms_pdf_options filter $options The PDF engine's options
kindly_forms_pdf_html filter $html, $def, $doc, $entry The document's HTML before it becomes a PDF
kindly_forms_pdf_bytes filter $bytes, $def, $doc, $entry The finished PDF
kindly_forms_pdf_link_ttl filter $seconds, $def, $doc How long a download link works (the site's setting, 7 days by default)
kindly_forms_pdf_zip_limit filter 100 Most entries in one zip

Translation#

Hook Type Arguments Use
kindly_forms_i18n_engine filter $engine Which translation plugin is used
kindly_forms_lang_current, kindly_forms_lang_default filter $lang The current and default language
kindly_forms_lang_list filter $languages Languages offered
kindly_forms_lang_locale filter $locale, $lang The locale for a language
kindly_forms_i18n_field_keys filter $keys Field settings that are translated
kindly_forms_i18n_strings filter $strings, $def A form's words registered for translation
kindly_forms_i18n_registered action $form_id, $registered, $before They were registered
kindly_forms_translate filter $text, $context, $name, $form_id, $lang One translated text
kindly_forms_texts_in_page filter $on Whether the browser's words are written into the page (on with TranslatePress or Weglot)
kindly_forms_page_texts filter $texts, $def Those words

See Multilingual forms.

Posts and accounts#

Hook Type Arguments Use
kindly_forms_meta_key_allowed filter $ok, $key, $kind Whether an entry may write a post or user meta key. Protected and site-internal keys never are
kindly_forms_post_create_terms filter $create, $taxonomy Whether a post form may make new terms (tags yes, categories no, by default)
kindly_forms_registration_roles filter $roles Roles a registration form may give
kindly_forms_verify_email filter $body, $user, $link The account verification email
kindly_forms_user_registered action $user_id, $entry, $def, $feed A form made an account
kindly_forms_user_updated action $user_id, $entry, $def, $feed A form changed an account
kindly_forms_user_verified action $user_id Someone verified their account

Scheduled events#

Event Runs Does
kindly_forms_queue Once, right after a connection is queued Sends what is due, 25 at a time
kindly_forms_queue_retry Every 5 minutes Sends what is due and tries failed connections again; also sets up waiting Authorize.Net subscriptions
kindly_forms_authnet_arb_retry Once, a minute after Authorize.Net wasn't ready to bill a new subscription's card (since 0.12.0) Sets up the waiting Authorize.Net subscriptions, one try each
kindly_forms_daily Daily Deletes entries past a form's "delete after" days, unconfirmed entries past the site's "delete unconfirmed" days, old logs (60 days by default) and saved progress older than the form's "keep saved answers" days (30 by default); removes unclaimed temporary uploads and left-over PDF files; ends abandoned payments; sends the weekly summary on its day

Add a field type#

A field type is one definition that drives the builder's palette and settings, the drawing and the checking. Register it with kindly_forms_field_types:

add_filter( 'kindly_forms_field_types', function ( $types ) {
	$types['member_number'] = [
		'label'    => __( 'Member number', 'my-plugin' ),
		'group'    => 'advanced', // general, choice, advanced, layout, payment or post
		'icon'     => 'id-card',
		'tags'     => 'member club id card', // words the palette search finds it by
		'value'    => true, // it submits an answer
		'logic'    => true, // offer Show when
		'defaults' => [ 'label' => __( 'Member number', 'my-plugin' ), 'prefix' => 'M-' ],
		// shared settings by key, in order; the type's own ones come from 'own'
		'settings' => [ 'label', 'prefix', 'help', 'required', 'adminLabel', 'name', 'logic' ],
		'own'      => [
			'prefix' => [ 'label' => __( 'Starts with', 'my-plugin' ), 'control' => 'text' ],
		],
	];
	return $types;
} );

Set the flags your type needs: value (it submits an answer), choices, composite (an object of parts), children (it holds fields), logic (offer Show when), repeatable (it may sit in a repeating group) and one (only one per form). Any flag you leave out is filled in after the filter runs: value and logic default to on, the others to off, and group to advanced. Set 'value' => false for a type that only shows something. Then draw it, clean it and check it with the per-type filters:

add_filter( 'kindly_forms_render_member_number', function ( $html, $f, $ctx ) {
	$id = kindly_forms_input_id( $f, $ctx );
	return kindly_forms_wrap_open( $f, $ctx )
		. kindly_forms_label( $f, $ctx, $id )
		. '<input type="text"' . kindly_forms_input_attrs( $f, $ctx, $id ) . '>'
		. kindly_forms_help( $f, $ctx, $id ) . kindly_forms_error( $f, $ctx, $id )
		. '</div>';
}, 10, 3 );

add_filter( 'kindly_forms_collect_member_number', fn( $value, $v ) => strtoupper( sanitize_text_field( is_scalar( $v ) ? (string) $v : '' ) ), 10, 2 );

add_filter( 'kindly_forms_validate_member_number', function ( $error, $v, $f ) {
	return '' === $v || str_starts_with( $v, $f['prefix'] ?? 'M-' ) ? null : __( 'Member numbers start with M-.', 'my-plugin' );
}, 10, 3 );

Return null from a per-type filter to leave that step to Kindly. A field type registered this way is in the builder for everyone: nothing is gated.

Add a connection#

A connection is a provider registered with kindly_forms_feed_providers. Its site-wide keys (connect) appear under Connections; each form's feeds get its settings. Feeds run after the entry is stored. By default they go through the queue: the visitor isn't kept waiting, and a failure is tried again every 5 minutes, up to 4 times. Every call is logged with its request and response, secrets removed.

add_filter( 'kindly_forms_feed_providers', function ( $p ) {
	$p['club_desk'] = [
		'label'       => 'Club Desk',
		'group'       => 'crm', // crm, email, messaging, automation, data, payments, accounts or other
		'icon'        => 'users',
		'description' => __( 'Add new members to Club Desk.', 'my-plugin' ),
		'connect'     => [ 'key' => [ 'label' => __( 'API key', 'my-plugin' ), 'type' => 'password', 'required' => true ] ],
		'settings'    => [
			'email' => [ 'label' => __( 'Email', 'my-plugin' ), 'control' => 'text', 'required' => true, 'smart' => true ],
			'name'  => [ 'label' => __( 'Name', 'my-plugin' ), 'control' => 'text', 'smart' => true ],
		],
		'test' => fn( $c ) => '' !== ( $c['key'] ?? '' ) ? true : new WP_Error( 'key', __( 'Add the API key.', 'my-plugin' ) ),
		'send' => function ( $feed, $entry, $def, $c ) {
			$r = wp_safe_remote_post( 'https://api.example.org/members', [
				'headers' => [ 'Authorization' => 'Bearer ' . $c['key'], 'Content-Type' => 'application/json' ],
				'body'    => wp_json_encode( [ 'email' => $feed['map']['email'], 'name' => $feed['map']['name'] ] ),
			] );
			if ( is_wp_error( $r ) ) return $r;
			$code = wp_remote_retrieve_response_code( $r );
			return [ 'ok' => $code < 300, 'message' => 'Answered ' . $code, 'request' => [ 'email' => $feed['map']['email'] ], 'response' => wp_remote_retrieve_body( $r ) ];
		},
	];
	return $p;
} );

Settings marked smart take smartcodes; by the time send runs, $feed['map'] holds them filled in from the entry. send returns true, a WP_Error (an error with the code final is not tried again), or [ ok, message, request, response ] for the log. Other keys: map (a list of fields to fill, or a callable that fetches them from the service), lists (a callable for remote choices such as lists or tags), oauth, and async (false sends during the visitor's request).

About this page

Documents Kindly Edit 0.9.16. Source: includes/forms/*.php, includes/forms/payments/*.php, includes/forms/integrations/*.php. Theme choices and account permissions can change which controls appear.

Type a word or phrase to search the full documentation.