KoBoToolbox

Manage forms, submissions, hooks, and files on KoBoToolbox

Overview

The KoBoToolbox tool provides comprehensive management of the KoBoToolbox data collection platform via its KPI REST API v2. It supports four resources: Form (get, getAll, redeploy), Submission (get, getAll, delete, getValidation, setValidation), Hook (get, getAll, getLogs, retryAll, retryOne), and File (get, getAll, create, delete). Binary data capabilities include downloading submission attachments with configurable size versions (original, small, medium, large) and naming schemes (sequential or question-based), downloading form media file content, and uploading binary files as form media. Submissions support reformatting with GeoJSON coordinate parsing, multiselect field splitting, and number conversion. Uses token-based authentication with a configurable API root URL for self-hosted instances.

Category: Productivity
Tool Name: kobotoolbox
Version: 1

Appearance: Icon: lucide-ClipboardList | Color: #2095F3

Node Type

Action (Binary) — handles file/binary data operations

Input / Output

Direction	Port(s)
Input	Input
Output	Output, Error

Credentials

This tool requires KoBoToolbox API credentials. See the Credentials Guide for setup instructions.

Resources

Resource	Value
File	file
Form	form
Hook	hook
Submission	submission

Operations

Form (form)

Operation	Value	Description
Get	get	Get a single form.
Get Many	getAll	Get many forms.
Redeploy	redeploy	Redeploy current form version.

Submission (submission)

Operation	Value	Description
Delete	delete	Delete a submission.
Get	get	Get a single submission.
Get Many	getAll	Get many submissions.
Get Validation Status	getValidation	Get validation status for a submission.
Update Validation Status	setValidation	Update validation status for a submission.

Hook (hook)

Operation	Value	Description
Get	get	Get a single hook definition.
Get Many	getAll	List hooks on a form.
Logs	getLogs	Get hook logs.
Retry All	retryAll	Retry all failed hook attempts.
Retry One	retryOne	Retry a specific failed hook log.

File (file)

Operation	Value	Description
Create	create	Upload a file as form media.
Delete	delete	Delete a form media file.
Get	get	Get a file and optionally download content.
Get Many	getAll	List all form media files.

Parameters

String parameters accept {{ $json.field }} expressions, which are evaluated once per input item.

Form: Get

Parameter	Type	Required	Default	Description
Form ID (formId)	string	Yes	—	Form asset UID (e.g. aSAvYreNzVEkrWg5Gdcvg). Find forms via the Form: Get Many operation.

Form: Get Many

Parameter	Type	Required	Default	Description
Return All (returnAll)	boolean	Yes	false	Whether to return all results or only up to a given limit.
Limit (limit)	number	No	1000	Max number of results to return. Accepts 1–3000. (shown when Return All is false)
Filters	collection	No	{}	Search terms applied to the form listing.
— Filter	string	No	asset_type:survey	Text search query (e.g. “owner__username:meg AND name__icontains:quixotic”).
Options (options)	collection	No	{}	Additional listing options.
— Sort	fixedCollection	No	{}	How the returned forms are ordered.
— — Descending	boolean	No	true	Whether to sort in descending order.
— — Order By	options	No	date_modified	Field to order by.
				Options: asset_type, date_modified, name, owner__username, subscribers_count

Form: Redeploy

Parameter	Type	Required	Default	Description
Form ID (formId)	string	Yes	—	Form asset UID (e.g. aSAvYreNzVEkrWg5Gdcvg). Find forms via the Form: Get Many operation.

Submission: Delete

Parameter	Type	Required	Default	Description
Form ID (formId)	string	Yes	—	Form asset UID (e.g. aSAvYreNzVEkrWg5Gdcvg).
Submission ID	string	Yes	—	Submission ID (numeric, e.g. 245128).

Submission: Get

Parameter	Type	Required	Default	Description
Form ID (formId)	string	Yes	—	Form asset UID (e.g. aSAvYreNzVEkrWg5Gdcvg).
Submission ID	string	Yes	—	Submission ID (numeric, e.g. 245128).
Options (options)	collection	No	{}	Attachment download, field selection and reformatting options.
— Download Attachments	boolean	No	false	Whether to download submitted attachments as binary data.
— Attachments Naming Scheme	options	No	sequence	How each downloaded attachment’s binary property is named. (shown when Download Attachments is true)
				Options: sequence (numbered properties such as attachment_0), question (the original form question ID)
— Attachments Prefix	string	No	attachment_	Prefix for binary property name when using sequence naming. Index starting at 0 is appended. (shown when Download Attachments is true and Attachments Naming Scheme is sequence)
— Fields to Retrieve	string	No	—	Comma-separated list of fields to retrieve. Leave blank for all.
— File Size	options	No	download_url	Attachment size version to download. (shown when Download Attachments is true)
				Options: download_url (original), download_small_url (small), download_medium_url (medium), download_large_url (large)
— Multiselect Mask	string	No	select_*	Comma-separated wildcard selectors for multiselect fields (split by spaces into arrays).
— Number Mask	string	No	n_*, f_*	Comma-separated wildcard selectors for numeric fields.
— Reformat	boolean	No	false	Whether to apply reformatting (GeoJSON coordinates, key sanitization, masks).
— Sort	json	No	—	Sort predicates in MongoDB JSON format (e.g. {“_submission_time”:1}).

Submission: Get Many

Parameter	Type	Required	Default	Description
Form ID (formId)	string	Yes	—	Form asset UID (e.g. aSAvYreNzVEkrWg5Gdcvg).
Return All (returnAll)	boolean	Yes	false	Whether to return all results or only up to a given limit.
Limit (limit)	number	No	100	Max number of results to return. Accepts 1–3000. (shown when Return All is false)
Filter Type	options	No	none	How the returned submissions are filtered.
				Options: none, json
Filters (JSON)	string	No	—	MongoDB-style JSON filter (e.g. {“_submission_time”:{“$lt”:“2021-10-01T01:02:03”}}). (shown when Filter Type is json)
Options (options)	collection	No	{}	Attachment download, field selection and reformatting options.
— Download Attachments	boolean	No	false	Whether to download submitted attachments as binary data.
— Attachments Naming Scheme	options	No	sequence	How each downloaded attachment’s binary property is named. (shown when Download Attachments is true)
				Options: sequence (numbered properties such as attachment_0), question (the original form question ID)
— Attachments Prefix	string	No	attachment_	Prefix for binary property name when using sequence naming. Index starting at 0 is appended. (shown when Download Attachments is true and Attachments Naming Scheme is sequence)
— Fields to Retrieve	string	No	—	Comma-separated list of fields to retrieve. Leave blank for all.
— File Size	options	No	download_url	Attachment size version to download. (shown when Download Attachments is true)
				Options: download_url (original), download_small_url (small), download_medium_url (medium), download_large_url (large)
— Multiselect Mask	string	No	select_*	Comma-separated wildcard selectors for multiselect fields (split by spaces into arrays).
— Number Mask	string	No	n_*, f_*	Comma-separated wildcard selectors for numeric fields.
— Reformat	boolean	No	false	Whether to apply reformatting (GeoJSON coordinates, key sanitization, masks).
— Sort	json	No	—	Sort predicates in MongoDB JSON format (e.g. {“_submission_time”:1}).

Submission: Get Validation Status

Parameter	Type	Required	Default	Description
Form ID (formId)	string	Yes	—	Form asset UID (e.g. aSAvYreNzVEkrWg5Gdcvg).
Submission ID	string	Yes	—	Submission ID (numeric, e.g. 245128).

Submission: Update Validation Status

Parameter	Type	Required	Default	Description
Form ID (formId)	string	Yes	—	Form asset UID (e.g. aSAvYreNzVEkrWg5Gdcvg).
Submission ID	string	Yes	—	Submission ID (numeric, e.g. 245128).
Validation Status	options	Yes	—	Desired validation status.
				Options: validation_status_approved, validation_status_not_approved, validation_status_on_hold

Hook: Get

Parameter	Type	Required	Default	Description
Form ID (formId)	string	Yes	—	Form asset UID (e.g. aSAvYreNzVEkrWg5Gdcvg).
Hook ID	string	Yes	—	Hook UID (starts with h, e.g. hVehywQ2oXPYGHJHKtqth4).

Hook: Get Many

Parameter	Type	Required	Default	Description
Form ID (formId)	string	Yes	—	Form asset UID (e.g. aSAvYreNzVEkrWg5Gdcvg).
Return All (returnAll)	boolean	Yes	false	Whether to return all results or only up to a given limit.
Limit (limit)	number	No	1000	Max number of results to return. Accepts 1–3000. (shown when Return All is false)

Hook: Logs

Parameter	Type	Required	Default	Description
Form ID (formId)	string	Yes	—	Form asset UID (e.g. aSAvYreNzVEkrWg5Gdcvg).
Hook ID	string	Yes	—	Hook UID (starts with h, e.g. hVehywQ2oXPYGHJHKtqth4).
Log Status	options	No	—	Filter logs by status. Leave it empty to return every status.
				Options: 0 (failed), 1 (pending), 2 (success)
Start Date	dateTime	No	—	Minimum date for hook log entries.
End Date	dateTime	No	—	Maximum date for hook log entries.

Hook: Retry All

Parameter	Type	Required	Default	Description
Form ID (formId)	string	Yes	—	Form asset UID (e.g. aSAvYreNzVEkrWg5Gdcvg).
Hook ID	string	Yes	—	Hook UID (starts with h, e.g. hVehywQ2oXPYGHJHKtqth4).

Hook: Retry One

Parameter	Type	Required	Default	Description
Form ID (formId)	string	Yes	—	Form asset UID (e.g. aSAvYreNzVEkrWg5Gdcvg).
Hook ID	string	Yes	—	Hook UID (starts with h, e.g. hVehywQ2oXPYGHJHKtqth4).
Hook Log ID	string	Yes	—	Hook log UID (starts with hl, e.g. hlSbGKaUKzTVNoWEVMYbLHe).

File: Create

Parameter	Type	Required	Default	Description
Form ID (formId)	string	Yes	—	Form asset UID (e.g. aSAvYreNzVEkrWg5Gdcvg).
File Upload Mode	options	Yes	binary	Where the file to upload comes from.
				Options: binary, url
Binary Property (binaryPropertyName)	string	Yes	data	Name of the binary property containing the file to upload. Names are case-sensitive — see the upstream node’s Binary Data panel for the exact names to use. (shown when File Upload Mode is binary)
File URL	string	Yes	—	HTTP(s) link to the file to upload. (shown when File Upload Mode is url)

File: Delete

Parameter	Type	Required	Default	Description
Form ID (formId)	string	Yes	—	Form asset UID (e.g. aSAvYreNzVEkrWg5Gdcvg).
File ID	string	Yes	—	File UID (starts with af, e.g. afQoJxA4kmKEXVpkH6SYbhb).

File: Get

Parameter	Type	Required	Default	Description
Form ID (formId)	string	Yes	—	Form asset UID (e.g. aSAvYreNzVEkrWg5Gdcvg).
File ID	string	Yes	—	File UID (starts with af, e.g. afQoJxA4kmKEXVpkH6SYbhb).
Download File Content	boolean	Yes	false	Whether to download the file content into a binary property.
Binary Property (binaryPropertyName)	string	Yes	data	Name of the binary property to write the file into. Names are case-sensitive — see the upstream node’s Binary Data panel for the exact names to use.

File: Get Many

Parameter	Type	Required	Default	Description
Form ID (formId)	string	Yes	—	Form asset UID (e.g. aSAvYreNzVEkrWg5Gdcvg).

All Operations

Parameter	Type	Required	Default	Description
Max Concurrency	number	No	10	Maximum number of items to process concurrently. Accepts 1–100.

Output Data

The KoBoToolbox response is merged into the item JSON at the top level, so the response fields sit alongside the fields the item already carried. The rest of the input item passes through unchanged, and any binary the item arrived with is forwarded and merged with anything this node downloads.

Get Many and Logs fan out: when the call returns more than one record, the node emits one output item per record. Every other operation emits one output item per input item. When a Get Many or Logs call returns nothing, the node still emits a single item carrying only the passed-through item JSON — check for the field you expect rather than assuming a record is present.

Submission: Delete and File: Delete are the only operations whose result the node builds itself: they output success: true.

Binary output:

• Submission attachments — with Download Attachments on, every attachment listed on the submission is fetched at the size chosen by File Size and attached as binary. With the sequence naming scheme the property is the Attachments Prefix plus a zero-based index (attachment_0, attachment_1, …); with question it is the form question whose answer matches the file name. Submission: Get Many with attachment download always emits one item per submission — and no items at all when no submission matches.
• Form media — File: Get with Download File Content on writes the file into the binary property you named, using the file’s stored file name where the record has one and file_{fileId} otherwise.

With Reformat on, submissions are rewritten before being emitted: GeoJSON coordinates are parsed, keys are sanitized, and the multiselect and number masks are applied.

Field names come from KoBoToolbox itself and are not renamed, so reference them downstream exactly as the API returns them, e.g. {{ $json.fieldName }}.

Usage Examples

• Get all submissions for a KoBoToolbox form
• Download submission attachments from a form
• Upload a media file to a KoBoToolbox form
• Get validation status of a submission
• List all webhooks for a form
• Retry failed webhook deliveries
• Redeploy a form

Example Configuration

List every survey form, newest first:

{
  "type": "kobotoolbox",
  "parameters": {
    "resource": "form",
    "operation": "getAll",
    "returnAll": true,
    "filters": {
      "filter": "asset_type:survey"
    },
    "options": {
      "sort": {
        "value": {
          "descending": true,
          "ordering": "date_modified"
        }
      }
    }
  }
}

Get one form by its asset UID:

{
  "type": "kobotoolbox",
  "parameters": {
    "resource": "form",
    "operation": "get",
    "formId": "aSAvYreNzVEkrWg5Gdcvg"
  }
}

Get recent submissions with a MongoDB-style filter, downloading each attachment:

{
  "type": "kobotoolbox",
  "parameters": {
    "resource": "submission",
    "operation": "getAll",
    "formId": "aSAvYreNzVEkrWg5Gdcvg",
    "returnAll": false,
    "limit": 100,
    "filterType": "json",
    "filterJson": "{\"_submission_time\":{\"$gte\":\"2023-01-01T00:00:00\"}}",
    "options": {
      "download": true,
      "binaryNamingScheme": "sequence",
      "dataPropertyAttachmentsPrefixName": "attachment_",
      "version": "download_url",
      "selectMask": "select_*",
      "numberMask": "n_*, f_*",
      "reformat": true
    }
  }
}

Approve a submission:

{
  "type": "kobotoolbox",
  "parameters": {
    "resource": "submission",
    "operation": "setValidation",
    "formId": "aSAvYreNzVEkrWg5Gdcvg",
    "submissionId": "245128",
    "validationStatus": "validation_status_approved"
  }
}

Read a hook’s failed deliveries for a date range:

{
  "type": "kobotoolbox",
  "parameters": {
    "resource": "hook",
    "operation": "getLogs",
    "formId": "aSAvYreNzVEkrWg5Gdcvg",
    "hookId": "hVehywQ2oXPYGHJHKtqth4",
    "status": "0",
    "startDate": "2023-01-01T00:00:00Z",
    "endDate": "2023-12-31T23:59:59Z"
  }
}

Upload form media from an upstream node’s binary property:

{
  "type": "kobotoolbox",
  "parameters": {
    "resource": "file",
    "operation": "create",
    "formId": "aSAvYreNzVEkrWg5Gdcvg",
    "fileMode": "binary",
    "binaryPropertyName": "uploadFile"
  }
}

Upload form media from a link:

{
  "type": "kobotoolbox",
  "parameters": {
    "resource": "file",
    "operation": "create",
    "formId": "aSAvYreNzVEkrWg5Gdcvg",
    "fileMode": "url",
    "fileUrl": "https://example.com/media/image.jpg"
  }
}

Download a form media file into a named binary property:

{
  "type": "kobotoolbox",
  "parameters": {
    "resource": "file",
    "operation": "get",
    "formId": "aSAvYreNzVEkrWg5Gdcvg",
    "fileId": "afQoJxA4kmKEXVpkH6SYbhb",
    "download": true,
    "binaryPropertyName": "downloadedFile"
  }
}

Error Handling

Mode	Behavior
stop	Halts workflow on first error
continue	Skips failed items, passes successful ones through
errorPort	Routes failed items to Error output port

Tips

Manage KoBoToolbox forms, submissions, hooks, and files with attachment download/upload support for humanitarian field surveys.