Hi Kobo community,
I have had my fair share of struggles using the Kobo API, and I have noticed that I was not the only one.
In our organization, we rely heavily on the API to build our own Kobo front-end. So, to simplify API interactions, we developed a Typescript library that abstracts away much of the complexity:
Kobo-SDK
https://github.com/DRC-UA/kobo-sdk
For example
Submitting data (one of the trickiest parts) becomes as simple as this:
await sdk.v1.submission.submitXml({
formId: '<form_id>',
attachments: [{
name: 'filename as indicated in the answers',
url: 'URL to the file. Alternatively use `path` instead of `url` to select local file.',
}],
data: {
question_text: 'answer',
question_integer: 1,
question_select_multiple: 'option1 option2',
question_begin_repeat: [
{question: 'answer1'},
{question: 'answer2'},
],
},
})
Since it’s built in Typescript, there is autocompletion and type checking, ensuring code is written correctly without guesswork, making it easy to use even for no-developers.
Features summary
-
Submisson
- Easily attach files.
- Uses
/v1/submission.xml(since JSON submissions can cause issues). - Automatically retrieves
formhub/uuid. - Handle
begin_repeatsections. - Generates
instanceID. - Formats the request body to match Kobo’s complex nested structure so we can just use question’s name in the payload.
- Supports automatic retries.
-
Bulk submissions update
- Controls request pacing and split bulk size to prevent server rejection (common API issue).
- Formats the request body using
$xpathas keys so we can just use question’s name in the payload.
-
Fetching submissions
- By pass the limit of 30,000 submissions.
- Provides a simple API for start and end query parameters.
-
Fetch form definitions
- Fully typed API responses.
-
Web hooks
- Easily create and delete.
Hope this helps!
