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 Every hook below ships in the free edition (and therefore also in Pro). Hooks that belong to Pro-only features — payments, PDF documents, licensing, and the Pro integrations (HubSpot, Salesforce, Twilio) — are intentionally not covered by this 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).

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:

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.

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:

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.

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:

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.

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

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:

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.

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.

do_action(
    'formatrica_debug_log',
    string $message
);

Example:

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.

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.

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

Example:

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.

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.

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, …).

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

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.

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.

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

Example:

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:

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:

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.

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.

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.

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

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.

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.

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

Example:

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

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

---

Support & Contributing

• Documentation: https://docs.nexusplugins.com/products/formatrica
• Support Forum: https://support.nexusplugins.com/products/formatrica

---

Last Updated: July 15, 2026 Plugin Version: 1.1.2