Package Information
Available Nodes
Documentation generating…
Documentation
n8n-nodes-swum
Swum nodes for n8n. Swum is scheduling, CRM and payments software for swim schools.
This package has two nodes:
- Swum: add families and swimmers, request enrollments, mark attendance and send messages.
- Swum Trigger: start a workflow when something happens in your school, such as a new client, a booking or a failed payment.
Both nodes act through a dedicated Swum app key. The key's school, permissions and allowed pools decide what a workflow can see and change.
Installation · Credentials · Swum node · Swum Trigger · Example workflows · Compatibility
Installation
n8n Cloud: open the nodes panel, search for Swum, and add it. (Available once n8n has verified the package.)
Self-hosted n8n: go to Settings > Community Nodes > Install, enter n8n-nodes-swum, and install. See n8n's community nodes installation guide.
Credentials
You need a Swum school on a plan that includes the API, and a dedicated n8n key.
- In Swum, open Developers & Integrations > Apps > n8n and create an n8n key. Review its permissions and allowed pools before you save.
- In n8n, create a Swum API credential.
- Paste the key into Dedicated Swum n8n Key.
- Choose the Environment:
- Live for your real school (
sk_live_keys). - DEV Sandbox for a Swum developer sandbox (
sk_test_keys). Live refuses test keys.
- Live for your real school (
- Save. n8n checks the key by reading one family.
The key is sent only to https://api.swum.ai/v1 (Live) or https://swum-53cd2-api.web.app/v1 (DEV Sandbox), as a bearer token. Keep keys and webhook secrets out of execution output and shared workflow exports.
Swum node
| Resource | Operation | What it does |
|---|---|---|
| Family | Create | Adds a family (parent or guardian) to the school roster |
| Family | Search | Finds families by name, email or swimmer name |
| Swimmer | Add | Adds a swimmer to a family |
| Swimmer | Get Many | Lists swimmers, for one family or the whole school |
| Enrollment | Request | Asks the school to enroll a swimmer in a class |
| Attendance | Mark Present | Marks a swimmer present for one dated class meeting |
| Message | Send | Sends a Swum message to 1 to 50 families |
Source Action ID. Every write needs a stable Source Action ID, such as form-123:create-family. Use the same ID when you retry the same input and Swum will not do the action twice. Build it from the source record, for example {{ $json.submissionId }}:create-family.
Approvals. Actions run with the key's school, scopes and pool permissions. Enrollment requests and anything the school must approve come back with their real status, such as pending_approval. A pending result does not mean the swimmer is enrolled.
Limits. This node cannot charge cards, issue refunds, delete families or link accounts.
Search and Get Many return one item per family or swimmer. Turn on Return All to page through every result, or set Limit (1 to 200, default 50).
AI Agent. The Swum node can be used as a tool by n8n's AI Agent.
Errors. When Swum refuses a request, the node shows Swum's reason, for example "This request requires classes:write access." With Continue On Fail on, the item gets a short error message instead.
Swum Trigger
Pick one or more events:
| Event | When it fires |
|---|---|
client.created |
A new family joins the school |
lesson.booked |
A lesson is booked |
lesson.canceled |
A lesson is canceled |
enrollment.created |
A swimmer is enrolled in a class |
payment.succeeded |
A payment goes through |
payment.failed |
A payment fails |
waiver.signed |
A family signs a waiver |
level.advanced |
A swimmer moves up a level |
When you activate the workflow, the trigger registers its webhook URL with Swum. When you deactivate it, the trigger removes it. Your n8n webhook URL must be public and use HTTPS on port 443. n8n Cloud URLs already do.
Every delivery is signed. The trigger checks the Swum-Signature header against the exact raw request bytes with HMAC-SHA256, and rejects altered, unsigned or expired (more than 5 minutes old) deliveries. The signing secret stays in the workflow's private node data. Swum may retry a delivery, so deduplicate downstream work by the event id.
Example workflows
1. Website sign-up to enrollment request
Turn a form submission into a family, a swimmer and an enrollment request the school approves.
- Webhook (or a Typeform, Jotform or Google Forms trigger) receives
parentName,email,phone,childName,birthday,classIdand asubmissionId. - Swum, Family > Create: Name
{{ $json.body.parentName }}; Email and Phone under Additional Fields; Source Action ID{{ $json.body.submissionId }}:family. - Swum, Swimmer > Add: Family ID
{{ $json.id }}; Name{{ $('Webhook').item.json.body.childName }}; Birthday under Additional Fields; Source Action ID{{ $('Webhook').item.json.body.submissionId }}:swimmer. - Swum, Enrollment > Request: Family ID, Swimmer ID and Class ID from the steps above; Source Action ID
{{ $('Webhook').item.json.body.submissionId }}:enroll.
The school sees the request in Swum and approves it. If the workflow is retried, the same Source Action IDs are reused, so nothing is created twice.
2. Failed payment alert
- Swum Trigger with the event
payment.failed. - Slack (or Gmail, or Microsoft Teams) posts to the front desk with the family and amount from the event's
data.
3. Pool closure message
- Manual Trigger (or a Schedule Trigger, or a weather check).
- Swum, Family > Search: leave Search empty and turn on Return All. Add a Filter node if only some families should hear about it.
- Aggregate collects the family
idvalues into one list. - Swum, Message > Send: Family IDs
{{ $json.id.join(',') }}(up to 50 per message); Message "The pool is closed today. We will reach out to reschedule."; Source Action IDclosure-{{ $now.toFormat('yyyy-MM-dd') }}.
Compatibility
Tested with n8n 2.45 on Node.js 22 and later. Version 0.2.0 replaced the single Fields list with resources and operations, so workflows built on 0.1.x need the Swum node set up again. See the changelog.
Development
npm install
npm run dev # starts n8n at http://localhost:5678 with these nodes loaded
npm test # builds, then runs the unit tests
npm run lint
Releases are published to npm by GitHub Actions, with npm provenance, when a v*.*.* tag is pushed. See .github/workflows/publish.yml.
Resources
Support
Email ben@swum.ai or open an issue.