The kobo json api is very not very clear and I understand people might be struggling to use in with their applications. After months of struggling and a lot of guess work i decided to write what I have been able to achieve.
Before you continue I cannot guarantee that it works for everyone. Also I have a self hosted instance of kobo so the url and requirements might be different.
-
Getting ready
I am assuming that you have your kobo instance set up so I will not go over that part. If you have not or you can check out the kobo github page for instructions on that.
Your base url should be something like https://kf.example.com. For authentication you can use basic auth which embeds the username and password to the header or generate a token to send with the headers. In my case I use basic auth. -
Formatting your json data
This has to be the hardest part in terms using the kobo api. I barely found any documentation on this. I was lucky enough though through deep digging, and some guess work I was able to make it work. Below is how you are suppose to format the questions and other data you send to kobo.{ "survey":[ { "name":"what_is_your_name", "type": "text", "label": "What is your name", "required":"true" } ]}
-
name stands for the key identifier for for your question. I think it can be any type of string as long as there are no spaces. Dont quote me on that however.
-
type stands for the type of question. Here you can go with the supported question types such as date, time, select_one, point, integer etc.
-
label This is your actual question. Need I say more?
There are other many values you can add here but I wont dive into that at the moment.
- Survey This is the json array that holds all of your data
3 Creating a draft on kobo
Data is formatted, time to create a draft on kobo. Here things can get a tiny bit tricky but bear with me. Here is what you need:
url: https://kf.example.com/assets/?format=json
Dont ignore anything on the kobo urls. It might be the reason why your code is not working
method: POST
body: formurlencoded
Accept: application/json
Request body
-
asset_type: survey
-
name: Test survey
-
content :“{ “survey”:[
{
“name”:“what_is_your_name”,
“type”:“text”,
“label”:“What is your name?”,
“required”:“true”
}
]}”
Here we pass the survey array we provided before. Make sure to pass this as a string otherwise it will not work. Why is that? No freaking idea.
You should have something similar to what we have below
- DEPLOY/ PUBLISH
Once the form is created kobotoolbox will reply with the form id stored in the ‘uid’ key. Save that key, you will need it from now on.
The publish api call looks very similar to the create api call the difference comes in the url and the request body.
-
url : https://kf.example.com/assets/[ insert your document id here ]/deployment/
-
request body: “active”: “true”
Hit send and boom!! your form is deployed
You see that / at the end of deployment? Dont forget that. That thing gave me sleepless nights
- Pull filled data via JSON api
While kobo has a service that does push form to your server, it never worked for me so pulling data was the alternative; plus why read xml while you can get it in json?
The drill is the same except this time we are doing a GET call to the api:
- url: https://kf.example.com/assets/[ insert your document id here ]/submissions.json’
There you go
If you want to learn more just go to https://kf.example.com/assets/ on your browser and you will see some details about the api that might help you for other calls such as redeployments and archives.
Thank you for attending my ted talk. If you wish to talk to me I am on linkedin Denis Kiura - Android Developer - Sendwave (International Remittance) | LinkedIn
