<!-- BusyBot node reference — https://busybot.net/tools/kobotoolbox/ -->

> Node: KoBoToolbox (`kobotoolbox`) · Action (binary) · v1
> Category: Productivity · Credentials: KoBoToolbox API (`koBoToolboxApi`)
> Updated: 2026-08-16

# 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](https://busybot.net/credentials/ko-bo-toolbox-api/) 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:

```json
{
  "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:

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

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

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

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

Upload form media from a link:

```json
{
  "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:

```json
{
  "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.