|

Docs

Getting Started
Creating Forms
↳ See all 17 articles
Form Styling
Form Field Types
↳ See all 13 articles
Anti Spam Settings
Publishing Forms
Single Form Settings
AI Features
Global Settings
Integrations
↳ See all 16 articles
Troubleshooting
Developer Documentation
Action Hooks
↳ See all 18 articles
Filter Hooks
↳ See all 14 articles
JS Custom Events
Localization
FAQs
Accounts
/ Documentation /Developer Documentation/ SureForms Pro Native Integrations – Developer Guide (API Based)

SureForms Pro Native Integrations – Developer Guide (API Based)

Overview

SureForms Pro Native Integrations system lets you create custom integrations with third-party services using JSON configuration.

Key Features

JSON-only configuration – no PHP coding needed.
Multiple auth types – API key, Bearer token, Basic auth.
Dynamic dropdowns – populate from external APIs.
Field dependencies – chain API calls together.
Data transformation – format data for target APIs.

Note:

Once you are done with the Step-by-Step Tutorial, don’t forget to take a look at the Advanced Features section, as it is quite an important part of creating an advanced integration configuration.

Quick Start Tutorial

Use the available WordPress hook “srfm_pro_native_integrations_json_configs” provided by SureForms to add your integration – this is what we’ll focus on in this tutorial.

Step-by-Step Integration Creation

Step 1: Create the Integration Metadata

Start by defining your service’s basic information:

PHP
// In your plugin's initialization file
add_filter('srfm_pro_native_integrations_json_configs', 'add_my_custom_integration');

function add_my_custom_integration($json_configs) {
    $my_integration = [
        'integrations' => [
            [
                'integration' => [
                    'name' => 'My Service',
                    'icon' => 'https://myservice.com/icon.svg',
                    'website_url' => 'https://myservice.com',
                    'docs_url' => 'https://docs.myservice.com/api',
                    'category' => 'CRM',
                    'description' => 'Sync contacts with My Service'
                ],
                'provider' => 'generic',  // Always use 'generic' for JSON-based integrations
                // We'll add auth and actions in the next steps...
            ]
        ]
    ];
    
    json_configs[] = json_encode(my_integration);
    return $json_configs;
}

Step 2: Add Authentication

Choose your authentication method (most Services use one of these three):

Option A: API Key Authentication (Most Common)

PHP
'auth' => [
    'type' => 'api_key',
    'fields' => [
        [
            'key' => 'api_key',
            'label' => 'API Key',
            'type' => 'password',                               // Hides the key
            'required' => true,
            'placeholder' => 'Enter your API key',
            'description' => 'Find this in your account settings'
        ]
    ],
    'headers' => [
        'Authorization' => 'Bearer {{api_key}}',               // How to send the key
        'Content-Type' => 'application/json'
    ],
    'test_endpoint' => [
        'url' => 'https://api.myservice.com/user',            // Simple endpoint to test connection
        'method' => 'GET',
        'success_criteria' => [
            'status_code' => 200
        ]
    ]
],

Option B: Bearer Token Authentication

PHP
'auth' => [
    'type' => 'bearer',
    'fields' => [
        [
            'key' => 'token',
            'label' => 'Access Key',
            'type' => 'password',                               // Hides the token
            'required' => true,
            'placeholder' => 'Enter your access token',
            'description' => 'Find this in your app settings'
        ]
    ],
    'headers' => [
        'Authorization' => 'Bearer {{token}}',               // How to send the token
        'Content-Type' => 'application/json'
    ],
    'test_endpoint' => [
        'url' => 'https://api.myservice.com/user',            // Simple endpoint to test connection
        'method' => 'GET',
        'success_criteria' => [
            'status_code' => 200
        ]
    ]
],

Option C: Basic Authentication

PHP
'auth' => [
    'type' => 'basic_auth',
    'fields' => [
        [
            'key' => 'username',
            'label' => 'Username',
            'type' => 'text',
            'required' => true
        ],
        [
            'key' => 'password',
            'label' => 'Password', 
            'type' => 'password',
            'required' => true
        ]
    ],
    'headers' => [
        'Authorization' => 'Basic {{base64(username:password)}}',
        'Content-Type' => 'application/json'
    ],
    'test_endpoint' => [
        'url' => 'https://api.myservice.com/auth/test',
        'method' => 'GET',
        'success_criteria' => [
            'status_code' => 200
        ]
    ]
],

Step 3: Create Your First Action

An “action” is what happens when a form is submitted (like “Add Contact” or “Create Task”):

PHP
'actions' => [
    [
        'name' => 'Add Contact',                             // Action name shown to users
        'description' => 'Add a new contact to My Service',  // Brief description
        'provider' => 'generic',
        'endpoint' => [
            'url' => 'https://api.myservice.com/contacts',   // API endpoint
            'method' => 'POST',                              // HTTP method
            'headers' => [
                'Authorization' => 'Bearer {{api_key}}',     // Use the auth from Step 2
                'Content-Type' => 'application/json'
            ],
            'payload_type' => 'json'                         // Send data as JSON
        ],
        'fields' => [
            // We'll add fields in Step 4...
        ]
    ]
]

Step 4: Add Fields

Define what data to collect from the form to map with the action. This field’s object will go in the actions object. These fields will be visible in the Single Form Settings workflow creation, from where you can map them with the form fields.

PHP
'fields' => [
    [
        'key' => 'name',                                     // Field identifier
        'label' => 'Full Name',                             // Label shown to users
        'type' => 'text',                                   // Input type
        'required' => true,                                 // Is this field required?
        'placeholder' => 'Enter contact name',
        'description' => 'The contact\'s full name'
    ],
    [
        'key' => 'email',
        'label' => 'Email Address',
        'type' => 'email',
        'required' => true,
        'placeholder' => '[email protected]'
    ],
    [
        'key' => 'status', 
        'label' => 'Contact Status',
        'type' => 'dropdown',
        'options' => [
            ['label' => 'Active', 'value' => 'active'],
            ['label' => 'Inactive', 'value' => 'inactive']
        ],
        'default' => 'active'
    ]
]

Dynamic Fields (Advanced)

Dynamic fields populate their options by calling external APIs.

Simple Dynamic Dropdown

PHP
[
    'key' => 'list_id',
    'label' => 'Select List',
    'type' => 'select-async',                    // Options loaded from API
    'required' => true,
    'placeholder' => 'Choose a list'
],

// Add this to your action configuration:
'apis' => [
    'lists' => [
        'url' => 'https://api.myservice.com/lists',
        'method' => 'GET',
        'headers' => [
            'Authorization' => 'Bearer {{api_key}}'
        ],
        'response_type' => 'select_options',
        'map' => [
            'data' => 'lists',           // Array path in API response
            'label' => 'name',           // Display this to user
            'value' => 'id'              // Store this value
        ],
        'target_fields' => ['list_id']   // Populate this field
    ]
]

How it works:

  1. User opens the dropdown
  2. System calls your API
  3. API response gets mapped to dropdown options
  4. User sees the list names, but the list IDs are stored
🎉 You Did It

Congratulations! You now have a working integration.

Your complete integration should look like this. Complete Basic Example:

PHP
function add_brevo_integration($json_configs) {
    $my_integration = [
        'integrations' => [
            [
                // Step 1: Integration Metadata
                'integration' => [
                    'name' => 'My Service',
                    'icon' => 'https://myservice.com/icon.svg',
                    'website_url' => 'https://myservice.com',
                    'docs_url' => 'https://docs.myservice.com/api',
                    'category' => 'CRM',
                    'description' => 'Sync contacts with My Service'
                ],
                'provider' => 'generic',
                
                // Step 2: Authentication
                'auth' => [
                    'type' => 'api_key',
                    'fields' => [
                        [
                            'key' => 'api_key',
                            'label' => 'API Key',
                            'type' => 'password',
                            'required' => true,
                            'placeholder' => 'Enter your API key',
                            'description' => 'Find this in your account settings'
                        ]
                    ],
                    'headers' => [
                        'Authorization' => 'Bearer {{api_key}}',
                        'Content-Type' => 'application/json'
                    ],
                    'test_endpoint' => [
                        'url' => 'https://api.myservice.com/user',
                        'method' => 'GET',
                        'success_criteria' => [
                            'status_code' => 200
                        ]
                    ]
                ],
                
                // Step 3 & 4: Actions and Fields
                'actions' => [
                    [
                        'name' => 'Add Contact',
                        'description' => 'Add a new contact to My Service',
                        'provider' => 'generic',
                        'endpoint' => [
                            'url' => 'https://api.myservice.com/contacts',
                            'method' => 'POST',
                            'headers' => [
                                'Authorization' => 'Bearer {{api_key}}',
                                'Content-Type' => 'application/json'
                            ],
                            'payload_type' => 'json'
                        ],
                        'fields' => [
                            [
                                'key' => 'name',
                                'label' => 'Full Name',
                                'type' => 'text',
                                'required' => true
                            ],
                            [
                                'key' => 'email',
                                'label' => 'Email Address',
                                'type' => 'email',
                                'required' => true
                            ]
                        ]
                    ]
                ]
            ]
        ]
    ];
    
    json_configs[] = json_encode(my_integration);
    return $json_configs;
}

Advanced Features

Field Dependencies

Make one field depend on another (like “Select Folder” then “Select List in Folder”):

PHP
'fields' => [
    [
        'key' => 'folder_id',
        'label' => 'Select Folder',
        'type' => 'select-async',
        'exclude_from_payload' => true      // Don't send this to the API
    ],
    [
        'key' => 'list_id', 
        'label' => 'Select List',
        'type' => 'select-async',
        'dependent_on' => 'folder_id',      // Only load after folder is selected
        'placeholder' => 'First select a folder'
    ]
],

'apis' => [
    'folders' => [
        'url' => 'https://api.myservice.com/folders',
        'target_fields' => ['folder_id'],
        'dependencies' => []                // Loads immediately
    ],
    'lists' => [
        'url' => 'https://api.myservice.com/folders/{{folder_id}}/lists',  // Uses selected folder
        'target_fields' => ['list_id'],
        'dependencies' => ['folder_id']     // Waits for folder selection
    ]
]

Data Transformation

Your form data needs to be restructured before sending to the API. Here are the available transformation types:

  • Nested Object Creation

Group multiple fields into a nested object structure:

PHP
'payload_transformation' => [
    'enabled' => true,
    'transformations' => [
        [
            'type' => 'nested_object',
            'target' => 'custom_fields',                    // Group fields under this key
            'source_pattern' => '*',                       // Include all fields
            'exclude_fields' => ['email', 'name']         // Except these main fields
        ]
    ]
]

Before: {“email”: “[email protected]”, “name”: “John”, “company”: “Acme”, “phone”: “555-0123”}
After: {“email”: “[email protected]”, “name”: “John”, “custom_fields”: {“company”: “Acme”, “phone”: “555-0123”}}

  • Array Conversion

Convert comma-separated strings or single values into arrays:

PHP
[
    'type' => 'array_conversion',
    'field' => 'tags',                                 // Source field
    'target' => 'tag_list',                           // Target field (optional)
    'delimiter' => ',',                               // String delimiter
    'description' => 'Convert comma-separated tags to array'
]

Before: “tag1, tag2, tag3” → After: [“tag1”, “tag2”, “tag3”]

  • Tag Array Conversion

Convert simple tags into complex tag objects with metadata:

PHP
[
    'type' => 'tag_array_conversion',
    'source_field' => 'tags',                         // Source field with tags
    'target_structure' => 'tags',                     // Target array name
    'tag_format' => [                                 // Template for each tag object
        'name' => '{{tag_name}}',
        'status' => 'active'
    ]
]

Before: “tag1,tag2” → After: [{“name”: “tag1”, “status”: “active”}, {“name”: “tag2”, “status”: “active”}]

  • Field Format Transformations

Apply formatting rules to specific fields (dates, strings, etc.):

PHP
[
    'type' => 'field_format',
    'field_rules' => [
        [
            'fields' => ['BIRTHDAY', 'DOB', '*BIRTHDAY*'],    // Field patterns to match
            'format_type' => 'date',                          // Type of formatting
            'input_formats' => ['Y-m-d', 'm/d/Y', 'd/m/Y'],   // Accepted input formats
            'output_format' => 'm/d',                         // Required output format
            'validation_regex' => '^\\d{1,2}\\/\\d{1,2}$'     // Validation pattern
        ]
    ]
]

Supported Format Types: date, string, number.

  • Structure Conversion

Transform simple fields into complex nested structures with auto-detection:

PHP
[
    'type' => 'structure_conversion',
    'conversions' => [
        [
            'fields' => ['ADDRESS', '*ADDRESS*'],            // Fields to transform
            'target_structure' => [                          // Target structure template
                'addr1' => '{{auto_detect_original:addr1}}',
                'city' => '{{auto_detect_original:city}}',
                'state' => '{{auto_detect_original:state}}',
                'zip' => '{{auto_detect_original:zip}}'
            ],
            'use_original_form_data' => true,               // Use original form field names
            'auto_detect' => [                              // Auto-detection patterns
                'addr1' => ['address-line-1', 'street-address', 'street'],
                'city' => ['city', 'town'],
                'state' => ['state', 'province', 'region'],
                'zip' => ['zip', 'postal-code', 'postcode']
            ],
            'fallback_to_field_value' => true              // Use field value if detection fails
        ]
    ]
]
  • Conditional Field Addition

You can combine multiple transformation types in a single configuration:

PHP
'payload_transformation' => [
    'enabled' => true,
    'transformations' => [
        [
            'type' => 'array_conversion',
            'field' => 'tags',
            'delimiter' => ','
        ],
        [
            'type' => 'nested_object',
            'target' => 'merge_fields',
            'source_pattern' => '*',
            'exclude_fields' => ['email', 'list_id', 'tags']
        ]
    ]
]

Advanced: URL Processing

Some APIs (like Mailchimp) need dynamic URLs based on your credentials:

PHP
'test_endpoint' => [
    'url' => 'https://{{datacenter}}.api.mailchimp.com/3.0/',
    'url_processing' => [
        'datacenter_extraction' => [
            'enabled' => true,
            'source_field' => 'api_key',           // Extract from this field
            'pattern' => '-([a-z0-9]+)$',          // Regex to find datacenter
            'replacement_token' => '{{datacenter}}' // Replace this in URL
        ]
    ]
]

Example: In the API key abc123-us1 datacenter is us1, so URL becomes https://us1.api.mailchimp.com/3.0/

Field Types Reference

Basic Field Types

TypePurposeExample
textSimple text inputName, address
emailEmail with validationEmail address
passwordHidden text inputAPI keys, passwords
numberNumeric inputAge, quantity
textareaMulti-line textDescription, notes
dropdownStatic optionsStatus, priority
select-asyncDynamic single-selectChoose one list
multi-select-asyncDynamic multi-selectChoose multiple tags

Static Dropdown Example

PHP
[
    'key' => 'priority',
    'label' => 'Priority Level',
    'type' => 'dropdown',
    'options' => [
        ['label' => 'High', 'value' => 'high'],
        ['label' => 'Medium', 'value' => 'medium'],
        ['label' => 'Low', 'value' => 'low']
    ],
    'default' => 'medium'
]

Common Questions

Integration Loading Process

Third-Party Integrations: Added via WordPress hooks

  • Use the srfm_pro_native_integrations_json_configs filter

Must include the integrations wrapper array in the JSON structure

Brevo Integration Complete Example

PHP
function add_brevo_integration($json_configs) {
    $integration = [
        'integrations' => [
            [
                'integration' => [
                    'name' => 'Brevo',
                    'icon' => 'https://cdn.brandfetch.io/idiSi980wS/w/1000/h/1000/theme/dark/icon.jpeg',
                    'website_url' => 'https://brevo.com',
                    'docs_url' => 'https://developers.brevo.com/reference/getting-started-1',
                    'category' => 'Email Marketing',
                    'description' => 'Add and manage contacts in Brevo'
                ],
                'provider' => 'generic',
                'auth' => [
                    'type' => 'api_key',
                    'fields' => [
                        [
                            'key' => 'api_key',
                            'label' => 'API Key',
                            'type' => 'password',
                            'required' => true,
                            'placeholder' => 'Enter your Brevo API key',
                            'description' => 'Copy your API v3 key from the SMTP & API page'
                        ]
                    ],
                    'headers' => [
                        'api-key' => '{{api_key}}',
                        'Content-Type' => 'application/json'
                    ],
                    'test_endpoint' => [
                        'url' => 'https://api.brevo.com/v3/account',
                        'method' => 'GET',
                        'success_criteria' => [
                            'status_code' => 200
                        ]
                    ]
                ],
                'actions' => [
                    [
                        'name' => 'Add/Update Contact',
                        'description' => 'Add a new contact or update an existing contact in Brevo',
                        'provider' => 'generic',
                        'endpoint' => [
                            'url' => 'https://api.brevo.com/v3/contacts',
                            'method' => 'POST',
                            'headers' => [
                                'Content-Type' => 'application/json',
                                'api-key' => '{{api_key}}'
                            ],
                            'payload_type' => 'json'
                        ],
                        'fields' => [
                            [
                                'key' => 'email',
                                'label' => 'User Email',
                                'type' => 'text',
                                'required' => true,
                                'placeholder' => '[email protected]',
                                'description' => 'If the contact already exists, it will be updated.'
                            ],
                            [
                                'key' => 'folder',
                                'label' => 'Select Folder',
                                'type' => 'select-async',
                                'required' => true,
                                'placeholder' => 'Select a folder',
                                'exclude_from_payload' => true     // UI-only field
                            ],
                            [
                                'key' => 'select_list',
                                'label' => 'Select List',
                                'type' => 'select-async',
                                'required' => true,
                                'placeholder' => 'Select a list',
                                'dependent_on' => 'folder'         // Depends on folder selection
                            ]
                        ],
                        'apis' => [
                            'folders' => [
                                'url' => 'https://api.brevo.com/v3/contacts/folders',
                                'method' => 'GET',
                                'headers' => [
                                    'api-key' => '{{api_key}}',
                                    'Content-Type' => 'application/json'
                                ],
                                'response_type' => 'select_options',
                                'map' => [
                                    'data' => 'folders',
                                    'label' => 'name',
                                    'value' => 'id'
                                ],
                                'target_fields' => ['folder'],
                                'dependencies' => []                // Loads immediately
                            ],
                            'lists' => [
                                'url' => 'https://api.brevo.com/v3/contacts/folders/{{folder}}/lists',
                                'method' => 'GET',
                                'headers' => [
                                    'api-key' => '{{api_key}}',
                                    'Content-Type' => 'application/json'
                                ],
                                'response_type' => 'select_options',
                                'map' => [
                                    'data' => 'lists',
                                    'label' => 'name',
                                    'value' => 'id'
                                ],
                                'target_fields' => ['select_list'],
                                'dependencies' => ['folder']        // Waits for folder selection
                            ]
                        ],
                        'payload_transformation' => [
                            'enabled' => true,
                            'transformations' => [
                                [
                                    'type' => 'nested_object',
                                    'target' => 'attributes',
                                    'source_pattern' => '*',
                                    'exclude_fields' => ['email', 'folder', 'select_list']
                                ],
                                [
                                    'type' => 'array_conversion',
                                    'field' => 'select_list',
                                    'target' => 'listIds'
                                ]
                            ]
                        ]
                    ]
                ]
            ]
        ]
    ];
    
    json_configs[] = json_encode(integration);
    return $json_configs;
}
Was this doc helpful?
What went wrong?

We don't respond to the article feedback, we use it to improve our support content.

Need help? Contact Support
%title %title
On this page
Scroll to Top