Documentation Index
Fetch the complete documentation index at: https://grantmaster.dev/llms.txt
Use this file to discover all available pages before exploring further.
Integration Guide: KoboToolbox (Field Data Collection)
Overview
GrantMaster integrates with KoboToolbox to pull field data collection results into the Impact & M&E module. This connects on-the-ground survey and monitoring data directly to your impact indicators, enabling real-time tracking without manual data entry.
What It Does
| Feature | Description |
|---|
| Form sync | Imports KoboToolbox form definitions as data collection templates |
| Submission import | Pulls survey responses into GrantMaster’s M&E indicators |
| Indicator mapping | Maps Kobo form fields to GrantMaster impact indicators |
| Scheduled sync | Automatic periodic import of new submissions |
| Data validation | Validates imported data against indicator definitions |
Prerequisites
- A KoboToolbox account (humanitarian or research server)
- At least one deployed form with submissions
- Admin role in GrantMaster
- KoboToolbox API token
Setup
- Log into your KoboToolbox account
- Go to Account Settings (click your profile icon)
- Scroll to the API Key section
- Copy your API token
- Go to Settings > Integrations > KoboToolbox
- Click Connect
- Enter your:
- KoboToolbox server URL (e.g.,
https://kf.kobotoolbox.org or https://kobo.humanitarianresponse.info)
- API token
- Click Test Connection to verify
- Click Save
- After connecting, click Import Forms
- Select the KoboToolbox forms you want to sync
- For each form, map fields to GrantMaster entities:
- Project — which project this data belongs to
- Indicator — which M&E indicator each field populates
- Click Save Mappings
- Go to Settings > Integrations > KoboToolbox > Sync Schedule
- Choose sync frequency:
- Real-time — imports submissions as they arrive (via webhook)
- Hourly — batch import every hour
- Daily — batch import once per day
- Manual — only sync when you click “Sync Now”
- Click Save
Day-to-Day Usage
Viewing Imported Data
- Go to Impact > Indicators
- Select an indicator that has KoboToolbox mappings
- View the Data Sources tab to see imported submissions
- Each submission shows the source form, submission date, and field values
Manual Sync
- Go to Settings > Integrations > KoboToolbox
- Click Sync Now to pull the latest submissions
- Review the sync result: new records imported, skipped duplicates, validation errors
Reviewing Validation Errors
If imported data fails validation (e.g., value out of expected range for an indicator):
- Go to Settings > Integrations > KoboToolbox > Sync History
- Click the latest sync with errors
- Review each error with the source submission and the validation rule that failed
- Fix the data in KoboToolbox and re-sync, or manually adjust the indicator value in GrantMaster
Mapping Guide
Indicator Types and Kobo Field Types
| GrantMaster Indicator Type | Compatible Kobo Field Types |
|---|
| Numeric (counts, percentages) | Integer, Decimal, Calculate |
| Text (qualitative) | Text, Select One, Select Many |
| Date (timeline tracking) | Date, DateTime |
| Location (geographic) | Geopoint, Geotrace, Geoshape |
| Binary (yes/no) | Select One (with Yes/No options) |
Aggregation Options
When mapping a Kobo field to an indicator, choose how submissions aggregate:
- Sum — add all submission values (e.g., “total beneficiaries reached”)
- Count — count the number of submissions (e.g., “number of surveys completed”)
- Average — calculate the mean value (e.g., “average satisfaction score”)
- Latest — use the most recent submission value (e.g., “current stock level”)
- None — store each submission as a separate data point
Troubleshooting
Connection Fails
| Symptom | Possible Cause | Solution |
|---|
| ”Invalid API token” | Token was regenerated | Get a new token from KoboToolbox Account Settings |
| ”Connection timeout” | Server URL incorrect | Verify you are using the correct Kobo server URL |
| ”403 Forbidden” | Token lacks permissions | Ensure the API token has read access to the forms |
Data Not Importing
| Symptom | Possible Cause | Solution |
|---|
| Sync completes with 0 records | No new submissions since last sync | Verify submissions exist in KoboToolbox |
| Partial imports | Validation errors on some records | Check sync history for error details |
| Duplicate records | Sync ran before KoboToolbox deduplicated | KoboToolbox submission IDs prevent duplicates — check mapping |
Indicator Values Look Wrong
- Check aggregation type — Sum vs. Count vs. Average produces very different results
- Check field mapping — ensure the correct Kobo field is mapped to the indicator
- Check data types — text fields mapped to numeric indicators will fail validation
- Check the submission date range — indicators may be filtered by reporting period
Best Practices
- Design Kobo forms with GrantMaster in mind — use field names that clearly indicate what they measure
- Use Calculate fields in Kobo for derived values — this keeps complex logic in the form rather than relying on GrantMaster aggregation
- Start with daily sync and switch to real-time only if you need immediate updates
- Map indicators before deploying forms — it is easier to adjust form fields than to re-map after data collection
- Review validation errors weekly — field data often contains outliers that need human review
- Test with a small form first — verify the sync works end-to-end before connecting high-volume forms
Limitations
- Only KoboToolbox v2 API is supported — legacy API endpoints are not compatible
- Repeat groups (nested tables) in Kobo forms have limited mapping support — only the first-level fields are automatically available
- Media attachments (photos, audio) from Kobo submissions are not imported — only metadata and text/numeric data
- Sync is one-directional: KoboToolbox → GrantMaster. Edits in GrantMaster are not pushed back to Kobo
- Maximum of 10,000 submissions per sync batch — forms with more submissions require multiple sync cycles
