ODK Central API not returning instanceName of submission

1. What is the issue? Please be detailed.
I am trying to perform an API call to the ODK Central API via a GET request, as described on the apiary page. I need the instanceName so I can extract some information about the form out of the name. However, no matter what I try, the API doesn't return the instanceName parameter in the response body. I am wondering how to accept this extra parameter and what could be the issue. My application is writter in Python, using python requests.

2. What steps can we take to reproduce this issue?
I am pretty much following the exact steps to get this information. I am logging in via a session token received via a POST request, which is then used to authenticate GET requests to get submission data from the server.

3. What have you tried to fix the issue?
I tried using the extended metadata header, but to no success. I have also tried calling the same API with the same requests using an API tester online, but to no avail. Still no instanceName attribute to be found.

4. Upload any test forms or screenshots below.

Image: what the API is returing (notice that instanceName is not present)

Any help would be appreciated!


Hi Mapo,

Could you post the query that you're using?

Regardless, what are you trying to get with instance name? If you mean the name the form is saved with in Collect, which is what I think you're referring to, that doesn't (to my knowledge) get sent to the server. It's only used client side in Collect.


The instance name DOES in fact get sent to the server, as if you make a GET request for a specific submission, the instanceName field will be present in the XML file. This however doesn't seem to be the case with the call for all submissions. My GET request is structured exactly the same as shown on the Apiary page, which I linked in my original post. The Apiary page clearly shows that the body of the response is structured differently than the response I'm getting. I am calling the /{formname}/submissions part of the API. The forums aren't uploading my pictures properly.

It is literally written in the documentation: Submissions now have an instanceName field which reflects the tag on the submitted XML.
It is also shown in the API example that the field should be present. It is not.

Ah I see - I learned something new today!

Looks like the instanceName feature was only added in central v1.2. Are you running an older version perhaps? I'm assuming you've checked this, but that's the first thing that comes to mind.

If you are running 1.2 or higher, have you confirmed that instanceName is provided when you make a request to /forms/[formname]/submissions/[instanceid]?

If the answers to both of those are yes, I think I'm unfortunately out of ideas - sounds like it could be a bug with central, in which case I think our best bet is if one of the dev team weighs in here/someone else reports the same problem so the cause can be hunted down.

The only other thing that comes to mind is that perhaps forms are being submitted on an old version of Collect, which doesn't send an instanceName - but then I'd expect instanceName to be returned as an empty string, not simply not exist, but maybe that's not how it is implemented.

1 Like


These are my versions of ODK central:
cd751d789e35e5cb1469cf651d6ba7275903bc03 (v1.4.2-4-gcd751d7)
461c1037997f9fb88075b75612b83cea297ced42 client (v1.4.0)
367a7f572d3ede411cea16d0fa1decb98e280e92 server (v1.4.2)

I tried filling the forms with what appears to currently be the latest version of ODK collect on Android (v2022.3.3) and the result is the same.

If I make a request to /submissions/instanceId I don't get the instanceName either, unless I make a call to /submissions/instanceId.xml, where the instanceName is then included under the tag. However, this still doesn't change the fact that the documentation states that instaceName should be in the response body if you make a request for ALL submissions. This is also makes the most sense from a practical standpoint, as you can include a lot of useful information in the instanceName, that you can later use without having to make a request for every separate submission, just to get some basic information to display.

What I'm trying to do is make a list of submissions that will be user-friendly, but with the current response body that I'm getting from the /submissions API call, this isn't possible unless I separately make another call for each submission via the instanceId that I am receiving.

This is the meta tag in the response when you call /submissions/{instanceId}.xml:

I have noticed that the "userAgent" property is also missing in the response body.

I would really appreciate if someone that is using ODK central could try some of these API calls by using a testing tool, so I can find out if the issue is purely on my side.


Does anyone know a workaround or any solutions?
I considered calling the API to get the XML of each submission, but that would prove itself to be too ineffective and would probably take a while to get through all the API requests, not to mention the load on the server just for listing the submissions...

This is the data that I receive, none of which is user friendly and it's impossible to tell which submission is which:

I'm surprised no one that could help me out has come across this problem, but luckily I found somewhat of a workaround, albeit not a perfect one. In the API there is a way to get all submitters that have submitted this form, and then you can link their user-friendly displayNames with the submitterIds that you get in the submissions API call. This provides at least some user friendly data, but the usage is still very limited.

Hi @mapo,

Looks like there's a bug in REST endpoint GET .../submissions. For now you can use ODATA endpoint, that returns instanceName in the response:

Your URL would look like this https://example.com/v1/projects/390/forms/Simple.svc/Submissions

Correct me if I am mistaken, but I think this is not really the functionality I am looking for, because this OData URL returns the whole submission data for each submission which could become an issue since our forms are quite extensive, whereas the regular API call returns only generic data about the submission (instanceId, submitterId, createdAt, updatedAt,...) and nothing else.


@mapo you are right, OData endpoints currently return all fields, there is one enhancement in progress that will allow selection of fields using $select query parameter. https://github.com/getodk/central-backend/issues/493

There is another endpoint that you can use to get instanceName https://example.com/v1/projects/[projectId]/forms/[formXmlId]/submissions/[instanceId]/versions

I know this is not super useful as you would need to call this endpoint for each submission, this only saves you the trouble of parsing XML