Overview
This node integrates with the Persio API to manage user data and events. Specifically, the Group - Add operation associates a user with a group by sending group membership information along with optional traits, context details, and integration flags to Persio.
Common scenarios for this node include:
- Associating users with organizational groups or teams in your system.
- Enriching group membership data with additional traits (e.g., company info, custom attributes).
- Providing contextual metadata about the user's environment (device, app, campaign, etc.) when adding them to a group.
- Controlling which downstream integrations receive the group data.
For example, you might use this node to add a user to a "Premium Customers" group with traits like subscription level and region, while also including device and campaign context to better segment and analyze user behavior.
Properties
| Name | Meaning |
|---|---|
| User ID | The unique identifier of the user to associate with the group. If not provided, an anonymous ID will be generated automatically. |
| Group ID | The unique identifier of the group to which the user is being added. This is required and should match your own database's group identifiers. |
| Traits | Key-value pairs representing additional attributes about the group membership, such as company details or custom properties. Multiple traits can be added. |
| Context | Metadata about the user's current environment, including: - Active status (boolean) - IP address - Locale string (e.g., en-US) - Page information (hash, path, referrer, search, title, URL) - Timezone (tzdata string) - App details (name, version, build) - Campaign details (name, source, medium, term, content) - Device details (id, manufacturer, model, name, type, version) |
| Integration | Flags to specify which integrations should receive this group data. Options include a general "all" flag and specific integrations like Salesforce. |
Output
The node outputs the JSON response returned by the Persio API after adding the user to the group. This typically includes confirmation of the group association and any metadata returned by the API.
The output is structured as an array of JSON objects, each corresponding to one input item processed. There is no binary data output.
Dependencies
- Requires an active connection to the Persio API using an API key credential configured in n8n.
- The node uses the
POST /groupendpoint of the Persio API to send group membership data. - The node depends on the
uuidpackage internally to generate anonymous IDs if no user ID is provided.
Troubleshooting
- Missing Required Group ID: The operation requires a valid Group ID. Ensure this field is filled correctly; otherwise, the API call will fail.
- Invalid User ID or Anonymous ID Generation: If no User ID is provided, the node generates an anonymous UUID. If there are issues generating this ID, check that dependencies are installed correctly.
- API Authentication Errors: Verify that the API key credential is set up properly in n8n and has permissions to access the Persio API.
- Malformed Traits or Context Data: Traits and context must be provided as key-value pairs or nested objects matching the expected structure. Incorrect formatting may cause API errors.
- Integration Flags Misconfiguration: Setting incompatible or unsupported integration flags could lead to partial failures or ignored data.
If the node encounters an error during execution and "Continue On Fail" is enabled, it will return the error message in the output array instead of stopping the workflow.
Links and References
- Persio API Documentation (general reference for API endpoints and payloads)
- UUID Package on npm (for understanding anonymous ID generation)