Enketo Logo
Hide allShow all

Response status codes

Success

Successes differ from errors in that their body may not be a simple response object with a code and a message. The headers however are consistent across all calls:

  • GET, POST returns 200 OK on success if the information was found,
  • POST returns 201 on success if a new database entry was created,
  • DELETE returns 204, without a body, if the entry was deleted

When retrieving stuff for example:

Status: 200 OK { "url": "https://enke.to/abcd", "code": 200 }

Error

Error responses are returning standard HTTP error codes along with a descriptive message:

  • The error code is sent back as a status header,
  • The body includes an object describing both the code and message (for debugging and/or display purposes),

For a call with an invalid API key as username in the Authorization header for example:

Status: 401 Unauthorized { "code": 401, "message": "Access denied: invalid API key as username in the Authorization header."" }

400 401 403 404 405 410

Test Responses

Tests

The following parameters can (and should) be used to write tests for the Enketo API:

  • all tests all use API Token abc (or missing to test for errors),
  • form_id could be any string (or missing to test for errors),

Success responses

Use the following server_url parameter for success responses:

  • https://testserver.com/bob

Error responses

Use the following server_url parameters for error responses:

  • https://testserver.com/noquota to simulate insufficient quota
  • https://testserver.com/noapi to simulate no API access
  • https://testserver.com/noquotanoapi to simulate insufficient quota and no API access
  • https://testserver.com/notpaid to simulate an inactive account
  • https://testserver.com/notexist to simulate a non-existing server url or account with that server_url

GET /survey Get a survey (existing)

This returns an offline-capable survey, unless the Enketo server does not have offline-capable surveys enabled, in which case it returns an online-only survey.

The GET version of this endpoint is only meant to test the Enketo Smart Paper API in the browser. It does not launch new surveys and is therefore not of use for integrating with Enketo.

Request

The request Content-Type is application/x-www-form-urlencoded.

  • required parameter server_url is the url of the OpenRosa server your form is hosted on
  • required parameter form_id is the ID of the form listed in SERVER/formList
  • headers must include a valid API key as username in the Authorization header

Authorization: Basic API_KEY:

Response

Sends back an object including a url property if it exists (i.e. if it has been launched on enketo before with POST).

Status: 200 OK { "url": "https://enke.to/abcd", "code": 200 }

For error responses, see the response status codes documentation.

200 400 401 403 404 405 410

Try in browser

Enter API token as username when asked.

Try in terminal

GET /survey/iframe Get an iframe-able survey (existing)

This returns an online-only iframe-friendly survey.

The GET version of this endpoint is only meant to test the Enketo Smart Paper API in the browser. It does not launch new surveys and is therefore not of use for integrating with Enketo.

Request

The request Content-Type is application/x-www-form-urlencoded.

  • required parameter server_url is the url of the OpenRosa server your form is hosted on
  • required parameter form_id is the ID of the form listed in SERVER/formList
  • headers must include a valid API key as username in the Authorization header

Authorization: Basic API_KEY:

Response

Sends back an object including the url property.

Status: 200 OK (if it already existed) { "url": "https://enke.to/i/abcd", "code": 200 }

For error responses, see the response status codes documentation.

200 400 401 403 404 405 410

Try in browser

Enter API token as username when asked.

Try in terminal

GET /survey/single Get a single-use survey (existing)

The GET version of this endpoint is only meant to test the Enketo Smart Paper API in the browser. It does not launch new surveys and is therefore not of use for integrating with Enketo.

Request

The request Content-Type is application/x-www-form-urlencoded.

  • required parameter server_url is the url of the OpenRosa server your form is hosted on
  • required parameter form_id is the ID of the form listed in SERVER/formList
  • optional parameter return_url is the URL to redirect the user to after submission/close (default is a generic thank you page)
  • headers must include a valid API key as username in the Authorization header

Authorization: Basic API_KEY:

Response

Sends back an object including an single_url property.

Status: 200 OK (if it already existed) { "single_url": "https://enke.to/single/abcd", "code": 200 }

For error responses, see the response status codes documentation.

200 400 401 403 404 405 410

Try in browser

Enter API token as username when asked.

Try in terminal

GET /survey/single/iframe Get a single-use iframe-able survey (existing)

The GET version of this endpoint is only meant to test the Enketo Smart Paper API in the browser. It does not launch new surveys and is therefore not of use for integrating with Enketo.

Request

The request Content-Type is application/x-www-form-urlencoded.

  • required parameter server_url is the url of the OpenRosa server your form is hosted on
  • required parameter form_id is the ID of the form listed in SERVER/formList
  • optional parameter return_url is the URL to redirect the user to after submission/close (default is a generic thank you page)
  • headers must include a valid API key as username in the Authorization header

Authorization: Basic API_KEY:

Response

Sends back an object including an single_url property.

Status: 200 OK (if it already existed) { "single_url": "https://enke.to/single/i/abcd", "code": 200 }

For error responses, see the response status codes documentation.

200 400 401 403 404 405 410

Try in browser

Enter API token as username when asked.

Try in terminal

GET /survey/preview Get a survey preview (existing)

The GET version of this endpoint is only meant to test the Enketo Smart Paper API in the browser. It does not launch new surveys and is therefore not of use for integrating with Enketo.

Request

The request Content-Type is application/x-www-form-urlencoded.

  • required parameter server_url is the url of the OpenRosa server your form is hosted on
  • required parameter form_id is the ID of the form listed in SERVER/formList
  • headers must include a valid API key as username in the Authorization header

Authorization: Basic API_KEY:

Response

Sends back an object including a preview_url property which contains the enketo webform.

Status: 200 OK (if it already existed) { "preview_url": "https://enke.to/preview/abcd", "code": 200 }

For error responses, see the response status codes documentation.

200 400 401 403 404 405 410

Try in browser

Enter API token as username when asked.

Try in terminal

GET /survey/preview/iframe Get an iframe-able survey preview (existing)

The GET version of this endpoint is only meant to test the Enketo Smart Paper API in the browser. It does not launch new surveys and is therefore not of use for integrating with Enketo.

Request

The request Content-Type is application/x-www-form-urlencoded.

  • required parameter server_url is the url of the OpenRosa server your form is hosted on
  • required parameter form_id is the ID of the form listed in SERVER/formList
  • headers must include a valid API key as username in the Authorization header

Authorization: Basic API_KEY:

Response

Sends back an object including a preview_url property.

Status: 200 OK (if it already existed) { "preview_url": "https://enke.to/preview/abcd", "code": 200 }

For error responses, see the response status codes documentation.

200 400 401 403 404 405 410

Try in browser

Enter API token as username when asked.

Try in terminal

GET /survey/all Get all survey views (existing)

The GET version of this endpoint is only meant to test the Enketo Smart Paper API in the browser. It does not launch new surveys and is therefore not of use for integrating with Enketo.

Request

The request Content-Type is application/x-www-form-urlencoded.

  • required parameter server_url is the url of the OpenRosa server your form is hosted on
  • required parameter form_id is the ID of the form listed in SERVER/formList
  • optional parameter return_url is the URL to redirect the user to after submission/close (default is a generic thank you page)
  • headers must include a valid API key as username in the Authorization header

Authorization: Basic API_KEY:

Response

Sends back an object with various properties.

Status: 200 OK (if it already existed) { "url": "https://enke.to/abcd", "iframe_url": "https://enke.to/i/abcd", "single_url": "https://enke.to/single/werdgag3e423gsgadgsd", "single_iframe_url": "https://enke.to/single/i/werdgag3e423gsgadgsd", "preview_url": "https://enke.to/preview/abcd", "preview_iframe_url": "https://enke.to/preview/i/abcd", "subdomain": "", "code": 200 }

For error responses, see the response status codes documentation.

200 400 401 403 404 405 410

Try in browser

Enter API token as username when asked.

Try in terminal

POST /survey Get a survey (new or existing)

This returns an offline-capable survey, unless the Enketo server does not have offline-capable surveys enabled, in which case it returns an online-only survey.

Request

The request Content-Type is application/x-www-form-urlencoded.

  • required parameter server_url is the url of the OpenRosa server your form is hosted on
  • required parameter form_id is the ID of the form listed in SERVER/formList
  • headers must include a valid API key as username in the Authorization header

Authorization: Basic API_KEY:

Response

Sends back an object including a url property.

Status: 200 OK (existing) Status: 201 OK (new) { "url": "https://enke.to/abcd", "code": 200 }

For error responses, see the response status codes documentation.

200 400 401 403 404 405 410

Try in terminal

POST /survey/iframe Get an iframe-able survey (new or existing)

This returns an online-only iframe-friendly survey.

Request

The request Content-Type is application/x-www-form-urlencoded.

  • required parameter server_url is the url of the OpenRosa server your form is hosted on
  • required parameter form_id is the ID of the form listed in SERVER/formList
  • headers must include a valid API key as username in the Authorization header

Authorization: Basic API_KEY:

Response

Sends back an object including the url property.

Status: 200 OK (existing) Status: 201 OK (new) { "url": "https://enke.to/i/abcd", "code": 200 }

For error responses, see the response status codes documentation.

200 400 401 403 404 405 410

Try in terminal

POST /survey/single Get a single-use survey (new or existing)

Request

The request Content-Type is application/x-www-form-urlencoded.

  • required parameter server_url is the url of the OpenRosa server your form is hosted on
  • required parameter form_id is the ID of the form listed in SERVER/formList
  • headers must include a valid API key as username in the Authorization header

Authorization: Basic API_KEY:

Request

  • required parameter server_url is the url of the OpenRosa server your form is hosted on.
  • required parameter form_id is the ID of the form listed in SERVER/formList.
  • optional parameter return_url is the URL to redirect the user to after submission.
  • The headers must include a valid API key as username in the Authorization header.

Authorization: Basic API_KEY:

Response

Sends back an object including an single_url property.

Status: 200 OK (existing) Status: 201 OK (new) { "single_url": "https://enke.to/single/abw3e325tt2gdsgsfd", "code": 200 }

For error responses, see the response status codes documentation.

200 400 401 403 404 405 410

Try in terminal

POST /survey/single/iframe Get a single-use iframe-able survey (new or existing)

Request

The request Content-Type is application/x-www-form-urlencoded.

  • required parameter server_url is the url of the OpenRosa server your form is hosted on
  • required parameter form_id is the ID of the form listed in SERVER/formList
  • optional parameter return_url is the URL to redirect the user to after submission/close (default is a generic thank you page)
  • headers must include a valid API key as username in the Authorization header

Authorization: Basic API_KEY:

Response

Sends back an object including an single_url property.

Status: 200 OK (existing) Status: 201 OK (new) { "single_url": "https://enke.to/single/i/aberj32wrkjdgkajahg", "code": 200 }

For error responses, see the response status codes documentation.

200 400 401 403 404 405 410

Try in terminal

POST /survey/preview Get a survey preview (new or existing)

Request

The request Content-Type is application/x-www-form-urlencoded.

  • required parameter server_url is the url of the OpenRosa server your form is hosted on
  • required parameter form_id is the ID of the form listed in SERVER/formList
  • headers must include a valid API key as username in the Authorization header

Authorization: Basic API_KEY:

Response

Sends back an object including a preview_url property.

Status: 200 OK (existing) Status: 201 OK (new) { "preview_url": "https://enke.to/preview/abcd", "code": 200 }

For error responses, see the response status codes documentation.

200 400 401 403 404 405 410

Try in terminal

POST /survey/preview/iframe Get an iframeable survey preview (new or existing)

Request

The request Content-Type is application/x-www-form-urlencoded.

  • required parameter server_url is the url of the OpenRosa server your form is hosted on
  • required parameter form_id is the ID of the form listed in SERVER/formList
  • headers must include a valid API key as username in the Authorization header

Authorization: Basic API_KEY:

Response

Sends back an object including a preview_url property.

Status: 200 OK (existing) Status: 201 OK (new) { "preview_url": "https://enke.to/preview/i/abcd", "code": 200 }

For error responses, see the response status codes documentation.

200 400 401 403 404 405 410

Try in terminal

POST /survey/all Get all survey views (new or existing)

Request

The request Content-Type is application/x-www-form-urlencoded.

  • required parameter server_url is the url of the OpenRosa server your form is hosted on
  • required parameter form_id is the ID of the form listed in SERVER/formList
  • optional parameter return_url is the URL to redirect the user to after submission/close (default is a generic thank you page)
  • headers must include a valid API key as username in the Authorization header

Authorization: Basic API_KEY:

Response

Sends back an object with various properties.

Status: 200 OK (existing) Status: 201 OK (new) { "url": "https://enke.to/abcd", "iframe_url": "https://enke.to/i/abcd", "single_url": "https://enke.to/single/werdgag3e423gsgadgsd", "single_iframe_url": "https://enke.to/single/i/werdgag3e423gsgadgsd", "preview_url": "https://enke.to/preview/abcd", "preview_iframe_url": "https://enke.to/preview/i/abcd", "subdomain": "", "code": 200 }

For error responses, see the response status codes documentation.

200 400 401 403 404 405 410

Try in terminal

DELETE /survey De-activate a survey

Request

The request Content-Type is application/x-www-form-urlencoded.

  • required parameter server_url is the url of the OpenRosa server your form is hosted on
  • required parameter form_id is the ID of the form listed in SERVER/formList
  • headers must include a valid API key as username in the Authorization header

Authorization: Basic API_KEY:

Response

Status: 204 OK (found and de-activated)

For error responses, see the response status codes documentation.

204 400 401 403 404 405 410

Try in terminal

GET /surveys/number Get the number of launched surveys

Request

The request Content-Type is application/x-www-form-urlencoded.

  • required parameter server_url is the url of the OpenRosa server your form is hosted on
  • headers must include a valid API key as username in the Authorization header

Authorization: Basic API_KEY:

Response

Sends back an object including the number property.

Status: 200 OK (existing) { "number": 12, "code": 200 }

For error responses, see the response status codes documentation.

200 400 401 403 404 410

Try in browser

Enter API token as username when asked.

Try in terminal

GET /surveys/list Get the list of launched surveys

Request

The request Content-Type is application/x-www-form-urlencoded.

  • required parameter server_url is the url of the OpenRosa server your form is hosted on
  • headers must include a valid API key as username in the Authorization header

Authorization: Basic API_KEY:

Response

Sends back an object with launched forms.

Status: 200 OK { "forms": [ { "server_url": "https://myserver.com/bob", "form_id": "widgets", "url": "https://enke.to/abcd" }, { "server_url": "https://myserver.com/bob", "form_id": "Birds", "url": "https://enke.to/efgh" } ], "code": 200 }

For error responses, see the response status codes documentation.

200 400 401 403 404 410

Try in browser

Enter API token as username when asked.

Try in terminal

POST /surveys/number Get the number of launched surveys

Request

The request Content-Type is application/x-www-form-urlencoded.

  • required parameter server_url is the url of the OpenRosa server your form is hosted on
  • headers must include a valid API key as username in the Authorization header

Authorization: Basic API_KEY:

Response

Sends back an object including the number property.

Status: 200 OK (existing) { "number": 12, "code": 200 }

For error responses, see the response status codes documentation.

200 400 401 403 404 410

Try in terminal

POST /surveys/list Get the list of launched surveys

Request

The request Content-Type is application/x-www-form-urlencoded.

  • required parameter server_url is the url of the OpenRosa server your form is hosted on
  • headers must include a valid API key as username in the Authorization header

Authorization: Basic API_KEY:

Response

Sends back an object with launched forms.

Status: 200 OK { "forms": [ { "server_url": "https://myserver.com/bob", "form_id": "widgets", "url": "https://enke.to/abcd" }, { "server_url": "https://myserver.com/bob", "form_id": "Birds", "url": "https://enke.to/efgh" } ], "code": 200 }

For error responses, see the response status codes documentation.

200 400 401 403 404 410

Try in terminal

POST /instance Post an instance for editing

Request

The request Content-Type is application/x-www-form-urlencoded.

  • required parameter server_url is the url of the OpenRosa server your form is hosted on
  • required parameter form_id is the ID of the form listed in SERVER/formList
  • required parameter instance is the XML instance with escaped quotation marks to be loaded
  • required parameter instance_id is the instanceID of the existing record to be loaded
  • required parameter return_url is the URL to redirect the user to after submission/close (default is a generic thank you page)
  • headers must include a valid API key as username in the Authorization header

Authorization: Basic API_KEY:

Response

Sends back an object including a edit_url property. You should redirect the user to this temporary URL immediately. Nother that this method will never return a 200. To (somewhat) protect agains two persons editing the same instance simultaneously, the instance is saved only temporarily in enketo (1 minute max) and during this time, a subsequent request will return 405 Not Allowed.

Status: Status: 201 OK { "edit_url": "https://enke.to//edit/abcd?instance_id=324sfasgsa324", "code": 201 }

For error responses, see the response status codes documentation.

201 400 401 403 404 405 410

Try in terminal

POST /instance/iframe Post an instance for editing (iframeable response)

Request

The request Content-Type is application/x-www-form-urlencoded.

  • required parameter server_url is the url of the OpenRosa server your form is hosted on
  • required parameter form_id is the ID of the form listed in SERVER/formList
  • required parameter instance is the XML instance with escaped quotation marks to be loaded
  • required parameter instance_id is the instanceID of the existing record to be loaded
  • required parameter return_url is the URL to redirect the user to after submission/close (default is a generic thank you page)
  • headers must include a valid API key as username in the Authorization header

Authorization: Basic API_KEY:

Response

Sends back an object including a edit_url property. You should redirect the user to this temporary URL immediately. Nother that this method will never return a 200. To (somewhat) protect agains two persons editing the same instance simultaneously, the instance is saved only temporarily in enketo (1 minute max) and during this time, a subsequent request will return 405 Not Allowed.

Status: Status: 201 OK { "edit_url": "https://enke.to//edit/i/abcd?instance_id=324sfasgsa324", "code": 201 }

For error responses, see the response status codes documentation.

201 400 401 403 404 405 410

Try in terminal

DELETE /instance Delete a temporary instance

This method may not have a practical use as instances POSTed to enketo for editing are only cached/saved very briefly (available for a maximum of 1 minute).

Request

The request Content-Type is application/x-www-form-urlencoded.

  • required parameter server_url is the url of the OpenRosa server your form is hosted on
  • required parameter form_id is the ID of the form listed in SERVER/formList
  • required parameter instance_id is the instanceID of the existing record to be loaded
  • headers must include a valid API key as username in the Authorization header

Authorization: Basic API_KEY:

Response

Status: 204 OK (found and removed)

For error responses, see the response status codes documentation.

204 400 401 403 404 405 410

Try in terminal