Using the KoboToolbox REST Services

Last updated: 19 Nov 2026

KoboToolbox REST Services allow you to automatically send new project submissions to external applications or servers. This can help integrate KoboToolbox with other systems, automate workflows, and reduce manual data transfers.

REST Services can also be useful for creating raw data backups on an external server, where submitted data remains stored even if the original submissions are edited or deleted from KoboToolbox.

REST Services send submissions to a web address, called an endpoint URL, provided by the receiving application. You can choose which fields to send, configure authentication, and customize the format of the data.

This article covers creating and configuring REST Services, understanding the available settings, and managing submission delivery.

Understanding REST Services

REST Services use webhooks to automatically send data from KoboToolbox to external systems. A webhook is a connection that sends information to a specified URL when an event occurs.

Unlike the KoboToolbox Application Programming Interface (API), which allows external applications to request data from KoboToolbox, REST Services automatically send data to an external application when a new submission is received.

When a new submission is received in KoboToolbox, the configured REST Service sends the submission data to the receiving application’s endpoint URL using an HTTP POST request.

REST Services support:

  • JSON and XML formats: Choose the format required by the receiving application.

  • Authentication: Configure credentials or custom HTTP headers to authorize requests.

  • Field selection: Send all submission fields or only selected fields.

  • Custom wrappers: Customize the structure of JSON data sent to the receiving application.

  • Error notifications and retries: Receive notifications about failed requests and automatically retry certain unsuccessful deliveries.

Note: REST Services only send data when a new submission is created. Changes to existing submissions, including edits and deletions, are not automatically sent to the receiving application.

Creating a REST Service

Before creating a REST Service, you need an endpoint URL from the application or server that will receive your KoboToolbox submissions. Depending on the receiving application, you may also need authentication credentials and information about the required data format.

To create a REST Service:

  1. Open your KoboToolbox project.

  2. Go to SETTINGS > REST Services.

  3. Click Register a New Service.

  4. Configure the service using the settings described below.

  5. Click Create to save the service.

new_rest

Configuring the service settings

The REST Service configuration window contains several fields that determine how submissions are sent to the receiving application.

Field

Description

Name

Enter a descriptive name to identify the REST Service within your KoboToolbox project. The name is for your reference and does not affect the data sent to the external application.

Endpoint URL

Enter the web address where KoboToolbox should send new submissions. This URL must be provided by the receiving application or the administrator of the external server. Use an HTTPS endpoint to protect data during transmission.

Enabled

Select Enabled to activate the REST Service and allow KoboToolbox to send new submissions to the configured endpoint. You can disable the service to stop sending new submissions without deleting its configuration.

Receive email notifications

Enable this option to receive email notifications when submission delivery fails. This can help you identify connection problems or errors with the receiving application.

Type

Choose the format used to send submission data:

  • JSON: Sends submissions in JSON format, commonly used by web applications and APIs.
  • XML: Sends submissions in XML format, which may be required by some external systems.

Select the format supported by the receiving application. If you are unsure, check the application’s integration documentation.

Security

Choose the authentication method required by the receiving application.

  • No Authorization: Use this when the endpoint does not require HTTP authentication or when authentication is provided through custom HTTP headers.
  • Basic Authentication: Use this when the endpoint requires a username and password.

If you select Basic Authentication, enter the credentials provided by the receiving application in the corresponding fields.

Select fields subset

Limit which fields are included. By default, REST Services send all available submission data to the receiving application. Enter the question names of the fields you want to include, and press Enter or Tab to add each field. For questions inside groups, use their full field names, including the group path where applicable.

Custom HTTP Headers

Some external applications require additional information in the HTTP request headers to authenticate requests or identify the integration. Enter the required header name in the Name field. Enter the corresponding value in the Value field. Click Add header to include additional headers if needed. Follow the instructions provided by the receiving application.

Add custom wrapper around JSON submission

Customize the structure of the data sent to the receiving application when using the JSON format, if the receiving application requires submission data to be placed inside a specific JSON structure.

For example:

{
  “source”: “KoboToolbox”,
  “submission”: %SUBMISSION%
}

The %SUBMISSION% placeholder represents the submission data that KoboToolbox sends.

If the receiving application does not require a specific JSON structure, you can leave this option unconfigured.

Note: REST Services do not automatically send existing submissions when a new service is created. Only submissions received after the service is enabled are sent through the connection.

Managing REST Services

After creating a REST Service, it appears in the list of registered services under SETTINGS > REST Services.

You can review its configuration and manage the service as needed.

Enabling or disabling a REST Service

You can disable an existing REST Service to temporarily stop sending new submissions to the receiving application.

  • When the service is enabled again, KoboToolbox resumes sending new submissions.

  • Disabling and re-enabling a service does not automatically send submissions that were received while it was disabled.

Updating or removing a REST Service

If the receiving application’s endpoint URL, authentication credentials, or data requirements change, update the REST Service configuration.

You can also delete a REST Service when the connection is no longer needed. Removing a REST Service stops future submissions from being sent through that connection. It does not delete submissions already sent to the receiving application.

Handling failed submissions

If KoboToolbox cannot deliver a submission to the external server, it automatically retries the request only when the server returns one of the following errors:

  • HTTP 502 (Bad Gateway)

  • HTTP 503 (Service Unavailable)

  • HTTP 504 (Gateway Timeout)

KoboToolbox makes up to three automatic retry attempts, after approximately 5, 10, and 20 minutes.

For all other errors, automatic retries are not performed, and you must retry the failed request manually.

You can enable Receive email notifications in the REST Service settings to receive notifications about failed deliveries.

If submissions are not reaching the receiving application:

  • Check the endpoint URL, authentication settings, and required data format.

  • Confirm that the external server is available and configured to accept incoming requests.