Resources · n8n integration

KoBoToolbox n8n integrationAutomate KoBoToolbox with n8n.

Field data should not sit in a form waiting for someone to open a laptop. The KoBoToolbox n8n integration gives you a node with 17 operations over 4 resources, forms, submissions, files and hooks, and a trigger that starts a workflow on each new submission. Built for teams collecting offline and processing centrally.

Verified Trustpilot reviews · AI, automation & growth agency

Why automate

What does the KoBoToolbox n8n integration actually cover?

The KoBoToolbox n8n integration wires a data collection account into the rest of your tools through two nodes. The KoBoToolbox node holds 17 operations spread over 4 resources: File, Form, Hook and Submission. The KoBoToolbox Trigger listens to 1 event and starts a workflow when a form receives a new submission. Both run on the same credential, which is the saved login n8n keeps for an app, here an API token.

First scenario, the submission that turns into a row. The trigger fires on formSubmission, the workflow reshapes the item and appends it to a Google Sheets tab the coordination team already opens every morning. The manual CSV export stops being part of anyone's week.

Second scenario, the review loop that closes itself. A submission lands, the workflow posts the answers to Slack, a supervisor replies, and the workflow writes that decision back with submission.setValidation, which sets Approved, Not Approved or On Hold on the submission itself. The verdict lives in KoBoToolbox instead of a chat thread nobody can audit later.

Third scenario, the hooks that fail quietly. hook.getLogs pulls a hook's logs filtered on Failed, hook.retryAll relaunches every failed attempt on that hook, and the count goes to Telegram. A broken downstream system stops being something you discover three weeks later.

Attachments follow the same path: the submission operations can download them into binary properties, and the workflow forwards them as a Gmail message without anyone opening the KoBoToolbox interface.

Two things to keep in mind. When an endpoint of the KoBoToolbox API sits outside the 17 operations of the node, the HTTP Request node calls it directly and reuses the same credential through predefined authentication, so no workflow is stuck. And on any listing, Return All decides the volume: left off, the node stops at Limit, and a truncated export looks exactly like a complete one. If you are still picking a platform, the n8n review is the longer read.

Connect

How do you connect KoBoToolbox to n8n?

  1. 01

    Grab your API token

    Open your KoBoToolbox account and go to Account Settings, where the API token is displayed. That string is the only secret n8n needs. Note which server the account lives on at the same time, because the credential asks for it in the next step and the two values are not interchangeable.

  2. 02

    Create the credential in n8n

    In n8n, open the Credentials menu and add a KoBoToolbox credential. API Root URL takes the address of the server where the account was created: https://kf.kobotoolbox.org for the Global KoBoToolbox Server, https://eu.kobotoolbox.org for the European Union one. API Token takes the string from Account Settings. Save it once and every workflow can reuse it.

  3. 03

    Pick the form in the node

    Drop the KoBoToolbox node or the KoBoToolbox Trigger on the canvas and select the credential from the dropdown. Form Name or ID then loads the forms of that account, so you choose by name instead of hunting for an ID like aSAvYreNzVEkrWg5Gdcvg. You can also pass the ID through an expression, the small piece of code n8n evaluates at runtime.

Triggers

What starts a KoBoToolbox workflow?

KoBoToolbox Trigger is the node that starts a workflow when something happens in KoBoToolbox. It listens to 1 events, listed below by family. Pick one or several, activate the workflow: n8n registers the webhook on your KoBoToolbox account.

What you see in n8n

Every event, by family

One row per object, one chip per action. The event to tick in the node is object.action; hover a chip to read exactly when it fires.

form.*1

    Configuration notes

    01Configure the KoBoToolbox TriggerThe trigger node starts a workflow on new submissions of one form, and it creates and deletes the hook on the KoBoToolbox side by itself, so there is nothing to configure in KoBoToolbox. It reads submissions the same way the Get a submission operation does, with the same reformatting options.

    The trigger node starts a workflow on new submissions of one form, and it creates and deletes the hook on the KoBoToolbox side by itself, so there is nothing to configure in KoBoToolbox. It reads submissions the same way the Get a submission operation does, with the same reformatting options.

    Key parameters

    • Form Name or ID: required, the form being watched. Choose it from the list n8n loads from the account, or pass an ID such as aSAvYreNzVEkrWg5Gdcvg through an expression.
    • Reformat: in the Options collection, applies some reformatting to the submission data, such as parsing GeoJSON coordinates, instead of handing you the raw payload.
    When to use it
    any time the work should start at collection time rather than at export time, from a supervisor alert to a live dashboard feed.
    02On Form SubmissionformSubmission is the single event of the catalogue, the whole form family, and it is set on the Trigger On parameter. The mechanism is a webhook, meaning a URL that KoBoToolbox calls the moment something happens, so each submission reaches the workflow in seconds with no polling loop in between. Trigger version 1.

    formSubmission is the single event of the catalogue, the whole form family, and it is set on the Trigger On parameter. The mechanism is a webhook, meaning a URL that KoBoToolbox calls the moment something happens, so each submission reaches the workflow in seconds with no polling loop in between. Trigger version 1.

    Key parameters

    • Download Attachments: pulls the pictures or videos submitted with the answers into the workflow rather than leaving them behind.
    • Attachments Naming Scheme and Attachments Prefix: name the binary properties, either as a sequence or from the original form question ID, with an index starting at 0 added to the prefix.
    • File Size: which version of an attachment to retrieve when several are available.
    • Multiselect Mask and Number Mask: comma-separated wildcard selectors for the fields to parse as arrays or as numbers.
    When to use it
    whenever a photo or a location matters as much as the answers, because these options decide what actually reaches the workflow.
    Actions

    What can the KoBoToolbox node do?

    The KoBoToolbox node exposes 17 operations across 4 resources. For each one: the node as you configure it in n8n, the required fields, and our field notes.

    Resources × operations matrix
    ResourceCreateGetGet ManyDeleteLogsGet Validation StatusRedeployRetry AllRetry OneUpdate Validation Status
    File✓✓✓✓
    Form✓✓✓
    Hook✓✓✓✓✓
    Submission✓✓✓✓✓

    File

    4 operations
    01

    Create a file

    file.create

    What you see in n8n

    Notes & use cases

    Uploads a file to a form, either from binary data the workflow already carries or from a public link.

    Key parameters

    • Form Name or ID: the form that receives the file, chosen from the dropdown or passed as an ID through an expression.
    • File Upload Mode: two choices, Binary File when the file travels inside the item, URL when KoBoToolbox should fetch it itself.
    • Property Name: the binary property holding the file. Supported types are image, audio, video, csv, xml and zip.
    • File URL: the HTTP(s) link to the file, used in URL mode.
    Use cases
    a reference list rebuilt every month by a workflow and pushed to the form without anyone clicking through the interface.
    02

    Delete a file

    file.delete

    What you see in n8n

    Notes & use cases

    Removes one file from a form, by its identifier.

    Key parameters

    • File ID: the uid of the file, which starts with af, for example afQoJxA4kmKEXVpkH6SYbhb. It is the identifier, not the file name.
    • Form Name or ID: the form the file belongs to, since the same workflow may juggle several.
    Use cases
    the second half of a refresh routine. Delete the outdated version, then upload the new one with Create a file, so the form never holds two versions of the same reference list.
    03

    Get a file content

    file.get

    What you see in n8n

    Notes & use cases

    Reads a file already attached to a form and can bring its content into the workflow as binary data.

    Key parameters

    • File ID: the uid starting with af, often taken from a previous node with {{ $json.field }}.
    • Download File Content: whether the content is downloaded into a binary property, or not.
    • Property Name: the name of the binary property the file is written into.
    Use cases
    pulling a form's file to send it on as an email attachment, without giving anyone access to the KoBoToolbox account.
    04

    Get many files

    file.getAll

    What you see in n8n

    Notes & use cases

    Lists the files attached to a form, with a single parameter to fill.

    Key parameters

    • Form Name or ID: the only required field here. Pick the form from the list, and the node returns its files.
    Use cases
    an inventory pass before a cleanup. Loop over the files, keep the ones the workflow expects, and hand the rest to Delete a file. It also makes a decent starting point when a form has been passed between several people and nobody remembers what was uploaded.

    Form

    3 operations
    05

    Get a form

    form.get

    What you see in n8n

    Notes & use cases

    Returns a single form from the account.

    Key parameters

    • Form Name or ID: the form to read. The dropdown is the fast path; the expression syntax is the one to use when the ID comes from an earlier node.
    Use cases
    a lookup step in the middle of a longer workflow, when a branch needs the form record before deciding what to do next, for example just before a redeploy or before posting a recap message to a channel.
    06

    Get many forms

    form.getAll

    What you see in n8n

    Notes & use cases

    Walks through the forms of the account and returns them as items.

    Key parameters

    • Return All: on, the node chains the API pages until every form is back; off, it stops at Limit.
    • Limit: the maximum number of forms returned when Return All stays off.
    • Filter: in Options, a text search on form data, for example owner__username:meg AND name__icontains:quixotic.
    • Sort: in Options, the ordering criteria applied to the result.
    Use cases
    a weekly inventory of every form in the account, dropped into a spreadsheet so the project leads see what is live.
    07

    Redeploy Current Form Version

    form.redeploy

    What you see in n8n

    Notes & use cases

    Redeploys the current version of a form from the workflow.

    Key parameters

    • Form Name or ID: the form to redeploy, named once in the node and reused on every run.
    Use cases
    the last step of a chain that starts elsewhere. A coordinator approves a change in a channel, the workflow picks up the approval and runs the redeploy, so the action is logged in an execution instead of living in someone's memory.

    Hook

    5 operations
    08

    Get a hook

    hook.get

    What you see in n8n

    Notes & use cases

    Returns a single hook definition declared on a form.

    Key parameters

    • Hook ID: the identifier of the hook, which starts with h, for example hVehywQ2oXPYGHJHKtqth4.
    • Form Name or ID: the form carrying that hook.
    Use cases
    the sanity check before a retry. Read the definition, confirm the workflow is about to act on the right hook, then continue to the logs or to the retry operations further down the branch.
    09

    Get Many hooks

    hook.getAll

    What you see in n8n

    Notes & use cases

    Lists the hooks declared on one form, so you can see what that form is wired to.

    Key parameters

    • Return All: on, every hook of the form comes back; off, the node stops at Limit.
    • Limit: the ceiling applied when Return All is left off.
    Use cases
    an audit run across forms that have been around for a while. Collect the hooks, keep the identifiers, and feed them to the log and retry operations in the same workflow.
    10

    Get Logs for a hook

    hook.getLogs

    What you see in n8n

    Notes & use cases

    Fetches the logs of a hook, with filters to narrow down what came back.

    Key parameters

    • Hook ID: the hook whose logs you want, identifier starting with h.
    • Log Status: All, Failed, Pending or Success.
    • Start Date and End Date: the minimum and the maximum date of the logs retrieved, which is how you keep a check focused on one window instead of replaying the whole history.
    Use cases
    a morning check filtered on Failed over the last day, with the result counted and posted to a channel so a silent breakage gets noticed.
    11

    Retry All hooks

    hook.retryAll

    What you see in n8n

    Notes & use cases

    Relaunches every failed attempt of a given hook in a single call, so a backlog of errors clears without the workflow walking through the logs one by one.

    Key parameters

    • Hook ID: the hook whose failed attempts are replayed.
    • Form Name or ID: the form the hook is attached to.
    Use cases
    the recovery step after the receiving system was down. Rather than replaying log by log, the workflow calls this once per hook and moves on to the notification branch.
    12

    Retry One hook

    hook.retryOne

    What you see in n8n

    Notes & use cases

    Replays one precise attempt instead of the whole batch.

    Key parameters

    • Hook Log ID: the log to replay, identifier starting with hl, for example hlSbGKaUKzTVNoWEVMYbLHe.
    • Hook ID: the hook that log belongs to.
    Use cases
    pairs naturally with Get Logs for a hook. Filter on Failed, loop over the results, and retry each log individually when you want the outcome of each one in its own execution.

    Submission

    5 operations
    13

    Delete a submission

    submission.delete

    What you see in n8n

    Notes & use cases

    Erases a single submission from a form.

    Key parameters

    • Submission ID: a number, for example 245128, not the respondent's name.
    • Form Name or ID: the form holding that submission.
    Use cases
    clearing the test entries left behind after a form rehearsal, so the real collection starts from a clean count. Put a confirmation step in front of it, because there is no undo branch to fall back on.
    14

    Get a submission

    submission.get

    What you see in n8n

    Notes & use cases

    Retrieves one submission and its data, with a set of options to shape the response.

    Key parameters

    • Submission ID: the numeric identifier of the submission, often passed as {{ $json.field }} from an earlier node.
    • Fields to Retrieve: a comma-separated list such as _submission_time,_submitted_by. Left blank, all fields come back.
    • Reformat: applies the reformatting logic, including parsing GeoJSON coordinates.
    Use cases
    enriching an alert. The notification carries an identifier, this operation turns it into the full answer set.
    15

    Get many submissions

    submission.getAll

    What you see in n8n

    Notes & use cases

    Collects the submissions of a form in bulk, which is the operation most exports are built on.

    Key parameters

    • Return All: on, the node pages through every submission; off, it stops at Limit.
    • Filter: None or JSON, and with JSON selected, Filters (JSON) carries the query.
    • Sort: in Options, sort predicates in MongoDB JSON format, for example {"_submission_time":1}.
    Use cases
    a nightly export into a spreadsheet, sorted by submission time so the newest rows land at the bottom.
    16

    Get the validation status for a submission

    submission.getValidation

    What you see in n8n

    Notes & use cases

    Tells you where one submission stands in the review process, without touching it.

    Key parameters

    • Submission ID: the numeric identifier of the submission being checked.
    • Form Name or ID: the form it was submitted to.
    Use cases
    the guard clause of a review workflow. Read the status first, and branch so the workflow skips the submissions a supervisor has already handled instead of pinging the channel twice.
    17

    Update the validation status for a submission

    submission.setValidation

    What you see in n8n

    Notes & use cases

    Writes the review decision back onto the submission, so the status lives in the data rather than in a conversation.

    Key parameters

    • Validation Status: Approved, Not Approved or On Hold, the three values the node accepts.
    • Submission ID: the numeric identifier of the submission being updated.
    Use cases
    a supervisor answers in a channel, the workflow maps the answer to one of the three values and applies it, and the next export already carries the decision.
    Need help

    Need help automating KoBoToolbox with n8n?

    A person reads every message.

    FAQ

    KoBoToolbox and n8n, the questions that come next

    01Is the KoBoToolbox n8n integration free?
    Yes on the n8n side. The KoBoToolbox node and the KoBoToolbox Trigger ship with n8n, so there is nothing to install, nothing to buy and no marketplace step. That holds whether you run n8n Cloud, the hosted offer run by n8n, or a self-hosted instance installed with Docker or npm under the Community Edition and its Sustainable Use licence. A workflow behaves the same in both cases, so a flow built on a laptop moves to a server without rework. What a KoBoToolbox account itself costs is a separate question and is not covered here.
    02What credentials do you need to connect KoBoToolbox to n8n?
    One credential, using an API token. It asks for two values. API Root URL is the address of the KoBoToolbox server where the account was created: https://kf.kobotoolbox.org for the Global KoBoToolbox Server, https://eu.kobotoolbox.org for the European Union server. API Token is the string displayed in the Account Settings of that same account. You create the credential once from the Credentials menu in n8n, and both the node and the trigger pick it up from their dropdown afterwards. No OAuth screen, no app to register, no scope list to tick.
    03What are the limits of the KoBoToolbox node in n8n?
    Two things to plan for. First, pagination: on the listing operations, Return All chains the API pages until everything is back, and leaving it off means the node stops at Limit. A truncated export looks identical to a complete one, which is how silent data gaps happen. Second, coverage: the node exposes 17 operations across 4 resources, and when the endpoint you need sits outside that catalogue, the HTTP Request node calls the KoBoToolbox API directly and reuses the very same credential through predefined authentication. So the workflow keeps going, just with one generic node in the chain.
    04Does the KoBoToolbox Trigger react in real time?
    Yes. The mechanism is a webhook, meaning a URL that KoBoToolbox calls the moment a submission arrives, so the workflow starts within seconds rather than on a schedule. There is no polling interval to tune and no delay to accept. The trigger node also handles the creation and the deletion of the hook itself when you activate or deactivate the workflow, so nothing has to be set up manually inside KoBoToolbox. It reads the submission the same way the Get a submission operation does, with the same reformatting and attachment options.
    05n8n or Make for KoBoToolbox?
    It depends on three criteria, and both tools are reasonable. Hosting: Make is a hosted platform with no self-hosting option, while n8n runs on your own server or on n8n Cloud, which matters when field data cannot leave a given jurisdiction. Cost model: Make bills per operation, so a workflow that loops over thousands of submissions has a different shape there. Visual logic: both draw the flow on a canvas, with different habits around branching and code. For KoBoToolbox specifically, the same 17 operations and the same submission webhook are the starting point either way.