Connect KoboToolbox¶
Connect your KoboToolbox account to FieldOps to bring existing Kobo forms and submission data into your FieldOps operational workflows.
After creating a connection, you can select a KoboToolbox form, map it to a FieldOps Programme, Project, and Site, optionally associate an existing Monitoring Template, and synchronize submissions.
Before you begin¶
You need:
- Access to the KoboToolbox account containing the forms you want to use
- A KoboToolbox API token
- Permission to create integrations in your FieldOps organization
- At least one form available in your KoboToolbox account
Note
FieldOps uses your KoboToolbox connection to access forms and submission data available to the connected KoboToolbox account.
Step 1: Get your KoboToolbox API token¶
Sign in to the KoboToolbox account that contains the forms you want to connect.
Open your KoboToolbox account settings and locate your API token.
Copy the token so that you can enter it when creating the connection in FieldOps.
Warning
Treat your API token like a password. Do not share it publicly, include it in screenshots, or send it through unsecured channels.
Step 2: Open Kobo Connections in FieldOps¶
Sign in to FieldOps and open Kobo Connections from the application navigation.
Select the action to create a new KoboToolbox connection.
Step 3: Enter the connection details¶
Complete the connection form using the details for your KoboToolbox account.
FieldOps requires:
- Connection name — a descriptive name that helps you identify the connection
- Base URL — the address of the KoboToolbox server used by your account
- API token — the API token from your KoboToolbox account
KoboToolbox Base URL¶
For most KoboToolbox accounts, the default Base URL is:
Use this URL unless your organization uses a different KoboToolbox server or a self-hosted deployment.
Tip
If you use the standard KoboToolbox service and are unsure which Base URL to enter, use https://kf.kobotoolbox.org.
If your organization uses another KoboToolbox server, enter the Base URL for that server instead.
Connection name¶
Use a clear connection name, especially if your organization may connect more than one KoboToolbox account or server.
For example:
- Kenya Monitoring Kobo
- Regional Programme Kobo
- Production KoboToolbox
API token¶
Paste the API token obtained from your KoboToolbox account.
Warning
Treat your API token like a password. Do not share it publicly, include it in screenshots, or send it through unsecured channels.
Step 4: Test and create the connection¶
Before saving the connection, select Test Connection.
FieldOps will use the supplied Base URL and API token to test whether it can successfully connect to your KoboToolbox account.
If the connection is successful, FieldOps will display a success message.
You can then select Create to save the connection.
Tip
Always use Test Connection before creating the connection. This helps confirm that the Base URL and API token are correct.
If the connection test fails, review:
- The Base URL
- The API token
- Whether the API token belongs to an active KoboToolbox account
- Whether the connected account is accessible
Correct any problems and select Test Connection again.
Once the test is successful, select Create to save the connection.
The connection will then be available under Kobo Connections.
Security considerations¶
Your KoboToolbox API token provides access to data available to the connected KoboToolbox account.
To protect the connection:
- Use a trusted KoboToolbox account
- Do not share API tokens between users unnecessarily
- Do not include API tokens in screenshots or documentation
- Revoke or replace credentials if you believe they have been exposed
- Remove connections that are no longer required
Warning
Never paste a real KoboToolbox API token into a support ticket, public message, screenshot, or documentation example.
Using multiple KoboToolbox connections¶
Your organization may create multiple KoboToolbox connections if your FieldOps plan and permissions allow it.
Multiple connections can be useful when:
- Different programmes use different KoboToolbox accounts
- Teams use different KoboToolbox servers
- Development and production environments are separated
- Different partners manage their own data collection accounts
Use descriptive connection names so that users can easily identify the correct connection.
Common problems¶
FieldOps cannot connect to KoboToolbox¶
Check that:
- The API token is correct
- The selected KoboToolbox server is correct
- The token belongs to an active KoboToolbox account
- The KoboToolbox service is accessible
- Your organization has not reached its connection limit
For additional help, review the troubleshooting guide.