Docs

Appearance

Formatrica

Get Formatrica

Formatrica - Public API Documentation ​

Version: 1.1.2 Last Updated: 2026-07-15

This document describes the public WordPress hook API (do_action / apply_filters) available in the Formatrica plugin.

Scope note This reference covers submission, email, and integration hooks and filters. For payments, draft saving, AI, and licensing HTTP endpoints, see the REST API reference.

Table of Contents ​

  1. Actions (Hooks)
  2. Filters

Actions (Hooks) ​

Form Submission Lifecycle ​

formatrica_before_submission ​

Fires before a form submission is processed (before validation and sanitization).

php
do_action(
    'formatrica_before_submission',
    int $form_id,
    array $form,
    array $request_data,
    array $context
);

Parameters:

  • $form_id (int) - Form ID
  • $form (array) - Form configuration (includes fields, settings, title, etc.)
  • $request_data (array) - Raw POST data
  • $context (array) - Submission context (ip_address, user_agent, etc.)

Example:

php
add_action('formatrica_before_submission', function($form_id, $form, $data, $context) {
    // Log submission attempt
    error_log("Form {$form_id} ({$form['title']}) submission from IP: {$context['ip_address']}");
}, 10, 4);

formatrica_after_submission ​

Fires after a submission is successfully processed.

php
do_action(
    'formatrica_after_submission',
    int $form_id,
    array $sanitised,
    array $result,
    array $form,
    array $context
);

Parameters:

  • $form_id (int) - Form ID
  • $sanitised (array) - Sanitized submission data (field values)
  • $result (array) - Processing result with keys:
    • success (bool) - Whether submission succeeded
    • message (string) - Success/error message
    • data (array) - Contains submission_id (int|null) and fields (array)
    • email (array) - Email delivery result
  • $form (array) - Form configuration
  • $context (array) - Submission context (ip_address, user_agent, etc.)

Example:

php
add_action('formatrica_after_submission', function($form_id, $sanitised, $result, $form, $context) {
    // Access submission ID (null if storage disabled)
    $submission_id = $result['data']['submission_id'] ?? null;

    // Custom notification for specific form
    if ($form_id === 5) {
        wp_mail('admin@example.com', 'VIP Form Submitted', print_r($sanitised, true));
    }
}, 10, 5);

Integration Hooks ​

formatrica_integration_dispatch ​

Fires when a form has an enabled integration that core does not handle itself. Use it to implement custom integrations.

php
do_action(
    'formatrica_integration_dispatch',
    string $integration_id,
    array $settings,
    array $form,
    array $payload,
    array $context,
    array $field_meta
);

Parameters:

  • $integration_id (string) - The integration key as stored in the form config
  • $settings (array) - The integration's saved settings for this form
  • $form (array) - Form configuration
  • $payload (array) - Submitted field values
  • $context (array) - Submission context
  • $field_meta (array) - Field metadata (labels, types) for the submitted fields

Example - Custom CRM Integration:

php
add_action('formatrica_integration_dispatch', function($id, $settings, $form, $payload, $context, $meta) {
    if ($id !== 'my_custom_crm') {
        return;
    }

    wp_remote_post('https://mycrm.com/api/leads', [
        'body' => wp_json_encode($payload),
        'headers' => ['Authorization' => 'Bearer ' . $settings['api_key']],
    ]);
}, 10, 6);

formatrica_wp_post_created ​

Fires after the WordPress Post integration creates a post from a submission.

php
do_action(
    'formatrica_wp_post_created',
    int $post_id,
    array $form,
    array $payload
);

Parameters:

  • $post_id (int) - The created post ID
  • $form (array) - Form configuration
  • $payload (array) - Submitted field values

formatrica_webhook_failed ​

Fires when an outbound integration HTTP request fails (network error, non-2xx response, or blocked endpoint).

php
do_action(
    'formatrica_webhook_failed',
    array $error,
    array $form,
    array $payload
);

Parameters:

  • $error (array) - Error details with keys:
    • endpoint (string) - The requested URL
    • integration (string) - Integration key (e.g. webhook, slack, mailchimp)
    • error (string) - Error message
    • context (array) - Submission context
  • $form (array) - Form configuration
  • $payload (array) - Submitted field values

Example:

php
add_action('formatrica_webhook_failed', function($error, $form, $payload) {
    wp_mail(
        get_option('admin_email'),
        'Form integration failed',
        sprintf('%s failed for %s: %s', $error['integration'], $error['endpoint'], $error['error'])
    );
}, 10, 3);

User Registration ​

formatrica_user_registered ​

Fires after a user-registration form creates a WordPress user.

php
do_action(
    'formatrica_user_registered',
    int $user_id,
    array $data
);

Parameters:

  • $user_id (int) - The new user's ID
  • $data (array) - The form submission data

Logging ​

formatrica_debug_log ​

Fires whenever the plugin emits a debug/diagnostic message. Nothing is written anywhere by default — attach a listener to route messages to your own logger.

php
do_action(
    'formatrica_debug_log',
    string $message
);

Example:

php
add_action('formatrica_debug_log', function($message) {
    if (defined('WP_DEBUG') && WP_DEBUG) {
        error_log('[Formatrica] ' . $message);
    }
});

Filters ​

Submission Processing ​

formatrica_submission_request ​

Filter the raw request data before validation and sanitization.

php
apply_filters(
    'formatrica_submission_request',
    array $request_data,
    int $form_id,
    array $form,
    array $context
);

formatrica_sanitized_submission ​

Filter the sanitized field values after validation, before storage, email, and integrations run.

php
apply_filters(
    'formatrica_sanitized_submission',
    array $sanitised,
    int $form_id,
    array $form,
    array $request_data,
    array $context
);

Example:

php
add_filter('formatrica_sanitized_submission', function($sanitised, $form_id) {
    // Normalise a phone field on form 7
    if ($form_id === 7 && isset($sanitised['phone'])) {
        $sanitised['phone'] = preg_replace('/[^0-9+]/', '', $sanitised['phone']);
    }
    return $sanitised;
}, 10, 2);

formatrica_min_submission_time ​

Filter the anti-bot minimum time (in seconds) a form must be on screen before a submission is accepted. Default 2.

php
apply_filters(
    'formatrica_min_submission_time',
    int $seconds,
    int $form_id
);

formatrica_recaptcha_v3_min_score ​

Filter the minimum reCAPTCHA v3 score a submission must reach. Default 0.5; scores below the threshold are rejected.

php
apply_filters(
    'formatrica_recaptcha_v3_min_score',
    float $threshold,
    int $form_id
);

formatrica_field_display_text ​

Filter a field value's plain-text display form before it is used in text-first outputs (plain-text emails, Slack messages, integration summaries). $meta is the field's submission metadata (name, label, type, value, …).

php
apply_filters(
    'formatrica_field_display_text',
    mixed $value,
    array $meta
);

File Uploads ​

formatrica_max_upload_size ​

Filter the maximum upload size in bytes for a file field. The default comes from the field's Max file size setting (1–50 MB, default 5 MB).

php
apply_filters(
    'formatrica_max_upload_size',
    int $max_size,
    array $field
);

formatrica_max_image_dimension ​

Filter the maximum image width/height in pixels for uploaded images. Default 4096.

php
apply_filters(
    'formatrica_max_image_dimension',
    int $max_dimension,
    array $field
);

formatrica_allowed_file_types ​

Filter the allowed MIME types for file uploads. Defaults: JPEG, PNG, GIF, WebP, PDF, DOC, DOCX, XLS, XLSX, TXT, CSV.

php
apply_filters(
    'formatrica_allowed_file_types',
    array $mime_types,
    array $field
);

Example:

php
add_filter('formatrica_allowed_file_types', function($types, $field) {
    $types[] = 'application/zip';
    return $types;
}, 10, 2);

Integration Payloads ​

Each outbound integration passes its request body through a filter before sending. All payload filters share the same signature:

php
apply_filters(
    'formatrica_{integration}_payload',
    array $body,
    array $form,
    array $payload,
    array $context,
    array $field_meta
);

Parameters:

  • $body (array) - The request body about to be sent to the service
  • $form (array) - Form configuration
  • $payload (array) - Submitted field values
  • $context (array) - Submission context
  • $field_meta (array) - Field metadata (labels, types)

formatrica_webhook_payload ​

Applies to Zapier, Make, and custom webhook requests.

Example:

php
add_filter('formatrica_webhook_payload', function($body, $form) {
    $body['site'] = home_url();
    return $body;
}, 10, 2);

formatrica_slack_payload ​

Applies to Slack notification messages.

formatrica_mailchimp_payload ​

Applies to Mailchimp subscribe requests.

formatrica_brevo_payload ​

Applies to Brevo contact requests.

formatrica_webhook_extra_headers ​

Filter the extra HTTP headers sent with an outbound webhook request. Default []. Return an associative header => value array; useful for authenticating webhook receivers.

php
apply_filters(
    'formatrica_webhook_extra_headers',
    array $headers,
    string $integration_id,
    array $settings
);

Email Rendering ​

formatrica_email_template_style ​

Filter the notification email's template style before the HTML body is built. Keys: accent (hex colour), font (CSS font stack), show_title (bool), show_metadata (bool), intro_text, footer_text. $options is the form's config options array.

php
apply_filters(
    'formatrica_email_template_style',
    array $style,
    array $options
);

formatrica_email_field_display_html ​

Override the pre-escaped HTML for a single field's value cell in the notification email table. Return null (default) for the standard escaped rendering, or an HTML string to replace it — the returned string is printed as-is, so escape it yourself.

php
apply_filters(
    'formatrica_email_field_display_html',
    ?string $html,
    array $field
);

Frontend Styling ​

formatrica_frontend_theme_css ​

Append extra CSS to the inline frontend theme stylesheet. Default ''.

php
apply_filters(
    'formatrica_frontend_theme_css',
    string $css
);

formatrica_theme_preset_class ​

Filter the CSS class applied to the form wrapper for the form's theme preset. Default '' (classic look). $preset is the preset id from the form's theme settings.

php
apply_filters(
    'formatrica_theme_preset_class',
    string $class,
    string $preset
);

WordPress Post Integration ​

formatrica_wp_post_args ​

Filter the wp_insert_post() arguments before the WordPress Post integration creates a post.

php
apply_filters(
    'formatrica_wp_post_args',
    array $postarr,
    array $form,
    array $payload,
    array $settings,
    array $context
);

Example:

php
add_filter('formatrica_wp_post_args', function($postarr, $form) {
    // Force specific category
    if ($form['id'] === 10) {
        $postarr['post_category'] = [5, 12];
    }
    return $postarr;
}, 10, 2);

Admin ​

formatrica_duplicate_title ​

Filter the title given to a duplicated form. Default: {original title} (Copy).

php
apply_filters(
    'formatrica_duplicate_title',
    string $title,
    array $original
);

Support & Contributing ​

Last Updated: July 15, 2026 Plugin Version: 1.1.2