n8n Integration
Package: BASIC
1. General
n8n is an open-source automation platform that can be used to connect external systems and services with one another – without programming knowledge, but with the option of including your own code where needed. brainX provides an official Community Node, verified by n8n, through which brainX can be integrated directly into n8n workflows.
A step-by-step description of the n8n integration is available in the video brainX + n8n: How every landing-page lead lands in the CRM instantly | Deep Dive Part 7 on the brainX YouTube channel. The example workflow shown in the video is available for download in the video description.
In brainX + n8n: from contact form to lead and appointment – step by step | Deep Dive Part 8, the workflow from Part 7 is extended with a brainX-internal automation (sales notification, appointment creation, confirmation email to the lead).
2. brainX Community Node in n8n
The brainX Community Node is officially verified by n8n and is actively maintained by brainX. It can be found in n8n under Integrations → search for “brainX".
The node mirrors the capabilities of the brainX REST API in a user-friendly, no-code-compatible form and makes it possible to read, create, update and link brainX records from within n8n.
3. Authentication (Credentials)
The connection between n8n and brainX is established via Credentials in n8n. The following details are required:
- Base URL – the URL of the brainX instance (e.g.
https://meine-brainx-domain) - Username – the username with which the user logs in to brainX
- API password – a specially generated API password (not the normal login password)
The API password is generated in brainX under My Preferences and is intended exclusively for API access. It is not the same as the user's login password. Further information on generating the API password can be found on the REST API page.
After entering the credentials, the connection can be checked in n8n via Test Connection.
3.1. Enabling an email account for sending in Automations
An email account integrated into brainX is not enabled for sending in Automations by default. To use an email account for automated email sending (both in brainX Automations and in n8n workflows that send emails via brainX), it must first be enabled:
- Open the Global Settings in brainX
- Open the desired email account
- In the email account settings, activate the Allow automation option
- Save
Without this enablement, the email account is not available for selection in the Send email action within Automations.
4. Available Operations
The brainX node supports the following operations:
4.1. Search
Searches for records in a selectable module based on one or more filters.
Configurable options:
- Module – the module to be searched (e.g. Leads, Contacts, Deals)
- Limit – maximum number of records returned
- Filter – one or more filter criteria; combined with AND by default
- Filter Combine With OR – combines the filters with OR instead of AND
- Fields to Return – limits the fields returned; by default, standard fields are returned
- Include Deleted – also returns records that are still in the Recycle Bin
- Always Output Data – returns an empty array even for an empty result (recommended if the result is evaluated in a downstream condition)
The Always Output Data option should be enabled if the search result is evaluated in a downstream IF node – only then is an empty array returned when there is no match, which allows the condition to be evaluated correctly.
The selection of the predecessor node (e.g. when populating fields in a Create or Update node) is only available if the corresponding output path of the previous IF node was actually active during the last test run. If, for example, the false path was not last traversed, the predecessor node selection is missing in the downstream node. Solution: run the workflow again with test data so that the desired path is activated.
4.2. Create
Creates a new record in a selectable module. All fields of the module are available – including custom fields created in the respective brainX instance.
Fields can be populated with static values or with dynamic values from previous node outputs.
The response returns the complete newly created record, including the automatically assigned record ID.
4.3. Update
Updates an existing record. Works analogously to the Create operation, and additionally requires the Record ID of the record to be updated.
Only the explicitly specified fields are updated – existing field values that are not passed remain unchanged.
4.4. Get
Retrieves a single record by its ID and returns all fields of the record.
Used when the ID of a record is already known and the full details are required.
4.5. Add Relations
Links two records together. This operation is used exclusively for modules that are mutually linked via the Relations tab in brainX (e.g. Leads ↔ Campaigns, Leads ↔ Documents).
The difference between Add Relations and Create/Update:
- Add Relations → for links where both modules display the respective other record in the Relations tab (n:m relationship)
- Create/Update → for all other fields that appear as a relation field in the detail view (e.g. a contact assigned to a lead)
Configuration:
- Record ID – the ID of the record to which the link should be added
- Related Record ID – the ID of the record to be linked
The response returns a status 200 with the message OK.
4.6. Get Current User
Returns the details of the user whose credentials are used for the connection.
4.7. Get Companies
Returns the Organizations to which the current user has access. Relevant for brainX instances with multi-organization capability.
4.8. Custom API Call
Enables direct calling of any endpoint of the brainX REST API for special cases that are not covered by the node's standard operations.
Available HTTP methods: GET, PATCH, POST, DELETE
Configuration:
- Endpoint – the desired API endpoint
- Body – optional JSON body for POST and PATCH requests
4.9. Test Mode 4.9. Production Mode (Webhook)
Webhook nodes in n8n have two operating modes that differ fundamentally:
| Test Mode | Production Mode | |
|---|---|---|
| Activation | Manually via Listen for Test Events | Automatically after Publish of the workflow |
| Availability | Temporary – automatically expires after a short time | Permanently active |
| URL | Test URL (for development only) | Production URL (publicly accessible) |
| Purpose | Development and testing of the workflow | Production operation |
Only activate Test Mode shortly before sending the test data, as it stops automatically after a short period of inactivity. Only after the workflow is published is the production URL available and the workflow permanently active.
After publishing (Publish), the webhook is publicly accessible over the internet. It is strongly recommended to activate header authentication to prevent unauthorised requests.
4.10. Combining fields from different predecessor nodes
In a brainX node, fields from different predecessor nodes can be combined – it is not necessary to limit yourself to a single predecessor node.
In an Update node, the Record ID is obtained from the Search node (since it is available there as a search result), while all other fields (first name, last name, email etc.) are obtained from the webhook that contains the form data.
When populating a field, simply switch the desired predecessor node in the picklist – this can be done independently for each field.
4.11. Refreshing the field list after changes in brainX
The brainX node retrieves the available fields of a module via API when it is opened. If new fields are created in brainX after the node is first opened (e.g. custom fields via module management), they are not initially visible in n8n.
To refresh the field list, use the Reload/Refresh button in the node. This retrieves the current field definitions again via API and makes newly created fields immediately available – without the node having to be reconfigured.
4.12. Date format and time zone for date/time fields
Date/time fields are expected by brainX in ISO 8601 format:
YYYY-MM-DDTHH:mm:ss+HH:mm
2025-10-27T09:00:00+02:00
The +HH:mm part at the end indicates the time zone. If the source system (e.g. a contact form) supplies date and time without a time zone, it can be appended manually to the n8n expression:
{{ $json.wunschtermin }}+02:00
The time zone must correspond to the actual time zone of the user or the system in order to avoid shifts when displayed in the brainX calendar. For Central European Time (CET), +01:00 applies; for Central European Summer Time (CEST), +02:00 applies.
Only activate Test Mode shortly before sending the test data, as it stops automatically after a short period of inactivity. Only after the workflow is published is the production URL available and the workflow permanently active.
5. Practical Examples
5.1. Creating a landing-page lead in brainX
The following example shows the structure of a typical n8n workflow that creates or updates a lead from a contact form in brainX.
Workflow structure:
- Webhook – receives the form data (first name, last name, email, company, phone) via HTTP POST
- Search (Module: Leads) – checks, based on the email address, whether the lead already exists in brainX
- Limit: 1
- Always Output Data: enabled
- IF node – evaluates the search result:
- Result not empty → lead already exists → Update branch
- Result empty → new lead → Create branch
- Create (Module: Leads) – creates a new lead; populates fields from the webhook request as well as static fields (e.g. Source = Website, Status = New)
- Update (Module: Leads) – updates the existing lead with the new form data
- Add Relations – links the lead with a campaign (Record ID of the lead from the Create or Search result; Related Record ID of the campaign)
Webhooks should always be secured with header authentication (Header Auth) to prevent unauthorised requests from external sources.
5.2. Extension with a brainX Automation
Once the lead has been created in brainX via n8n, a brainX-internal Automation can take over the further process. The following example shows how a brainX Automation follows on directly from the n8n workflow.
Trigger: Lead is created (Leads module)
Branch 1 – Notify sales:
- Condition: Source of the lead equals Website
- Action: Send an internal notification to the sales group (e.g. “New lead: [First name] [Last name] has been created")
Branch 2 – Create appointment:
- Condition: The Requested appointment field is not empty
- Action: Create an appointment with the following fields:
- Subject: composed via Blockly, e.g. “New appointment with [Last name]"
- Start: the lead's Requested appointment field
- End: Requested appointment + 30 minutes (via Blockly: calculate time with a number)
- Type: Call
- Status: Planned
- Reference: Lead
Branch 3 – Send confirmation email to the lead:
- Condition: The Email field is not empty
- Action: Send an email to the lead's email address (confirmation that the enquiry has been received and that a response regarding the requested appointment will follow)
The Automation must be activated after creation (status active) so that it is triggered for newly created leads.
Since the lead already passes through the salutation Automation (1.0 | Salutation Leads & Contacts) upon creation, the Salutation field is available as a placeholder in the confirmation email – provided that the Title field is also passed when the lead is created (even if it is empty), so that the logic of the salutation Automation works correctly.
6. Determining the Campaign ID
The ID of a campaign can be determined in two ways:
- Directly from brainX: In the detail view of the campaign, the Record ID is contained in the page's URL.
- Via a Get or Search operation in n8n: A brainX node with the Get operation (Module: Campaigns) returns all campaigns with their IDs. With Search, you can specifically search for a particular campaign.