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 an online-only 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.

In API v2 this always returns an online-only survey.

In API v2 the defaults parameter was added.

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 defaults[] can be used to dynamically override survey field defaults (defaults[/path/to/node]=value)
  • 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 online-only 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.

In API v2 this returns a response with an iframe_url property.

In API v2 the defaults and parent_window_origin parameters were added.

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 defaults[] can be used to dynamically override survey field defaults (defaults[/path/to/node]=value)
  • optional parameter parent_window_origin can be used to safely enable an iframed survey to post messages back to the parent window
  • headers must include a valid API key as username in the Authorization header

Authorization: Basic API_KEY:

Response

Sends back an object including the iframe_url property.

Status: 200 OK (if it already existed) { "iframe_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/offline Get an offline-capable survey (existing)

This returns an offline-capable 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.

This endpoint is new in v2.

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 { "offline_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/single Get an online-only single-submit survey (existing)

This webform view will always redirect the user upon successful submission of a single record.

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.

In API v2 the defaults parameter was added.

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)
  • optional parameter defaults[] can be used to dynamically override survey field defaults (defaults[/path/to/node]=value)
  • 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 an online-only single-submit iframe-able survey (existing)

This webform view will always redirect the user upon successful submission of a single record.

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.

In API v2 the defaults and parent_window_origin parameters were added.

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)
  • optional parameter defaults[] can be used to dynamically override survey field defaults (defaults[/path/to/node]=value)
  • optional parameter parent_window_origin can be used to safely enable an iframed survey to post messages back to the parent window
  • 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_iframe_url property.

Status: 200 OK (if it already existed) { "single_iframe_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/single/once Get an online-only single-submit survey that can be submitted once per user (new)

This webform view will always redirect the user upon successful submission of a single record. It has some basic protection to prevent the same user (browser & device) from submitting more than once.

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.

This endpoint is new in API v2.

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)
  • optional parameter defaults[] can be used to dynamically override survey field defaults (defaults[/path/to/node]=value)
  • 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_once_url property.

Status: 200 OK (if it already existed) { "single_once_url": "https://enke.to/single/werdgag3e423gsgadgsd", "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/once/iframe Get an online-only single-submit iframe-able survey that can be submitted once per user (existing)

This webform view will always redirect the user upon successful submission of a single record. It has some basic protection to prevent the same user (browser & device) from submitting more than once.

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.

This endpoint is new in API v2.

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)
  • optional parameter defaults[] can be used to dynamically override survey field defaults (defaults[/path/to/node]=value)
  • optional parameter parent_window_origin can be used to safely enable an iframed survey to post messages back to the parent window
  • 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_once_iframe_url property.

Status: 200 OK (if it already existed) { "single_once_iframe_url": "https://enke.to/single/werdgag3e423gsgadgsd", "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.

In API v2 the defaults, and go_to parameters were added.

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 defaults[] can be used to dynamically override survey field defaults (defaults[/path/to/node]=value)
  • optional parameter go_to can be used to jump to a specific question upon load. It takes any XPath (go_to=//question or go_to=//complex/repeat[3]//question).
  • 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.

In API v2 the defaults and go_to parameters were added.

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 defaults[] can be used to dynamically override survey field defaults (defaults[/path/to/node]=value)
  • optional parameter go_to can be used to jump to a specific question upon load. It takes any XPath (go_to=//question or go_to=//complex/repeat[3]//question).
  • 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_iframe_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/view Get a read-only survey (existing)

This view shows an empty readonly form.

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.

This endpoint is new in API v2.

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)
  • optional parameter go_to can be used to jump to a specific question upon load. It takes any XPath (go_to=//question or go_to=//complex/repeat[3]//question).
  • headers must include a valid API key as username in the Authorization header

Authorization: Basic API_KEY:

Response

Sends back an object including a view_url property.

Status: 200 OK (if it already existed) { "view_url": "https://enke.to/view/abcd232agdf3434sgdra34", "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/view/iframe Get a read-only iframe-able survey (existing)

This view shows an empty readonly iframe-able form.

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.

This endpoint is new in API v2.

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)
  • optional parameter go_to can be used to jump to a specific question upon load. It takes any XPath (go_to=//question or go_to=//complex/repeat[3]//question).
  • optional parameter parent_window_origin can be used to safely enable an iframed survey to post messages back to the parent window
  • headers must include a valid API key as username in the Authorization header

Authorization: Basic API_KEY:

Response

Sends back an object including a view_url property.

Status: 200 OK (if it already existed) { "view_iframe_url": "https://enke.to/view/abcd232agdf3434sgdra34", "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/view/pdf Get a PDF of the survey

The PDF shows an empty form.

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.

This endpoint is new in API v2.

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 format the paper format. Valid values are: Letter, Legal, Tabloid, Ledger, A0, A1, A2, A3, A4, A5, and A6. Default is A4.
  • optional parameter margin the paper margin. Valid units are: in, cm, and mm. Example values are 2.1in, 2cm, 10mm. Default is 0.5in.
  • optional parameter landscape whether paper orientation is landscape. Valid values ar true, false. Default is false.
  • headers must include a valid API key as username in the Authorization header

Authorization: Basic API_KEY:

Response

Sends back a PDF file or a JSON error response.

Status: 200 OK (if it already existed)

For error responses, see the response status codes documentation.

200 201 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.

The response property names have changed in API v2.

In API v2 the defaults and parent_window_origin parameters were added.

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)
  • optional
  • optional parameter defaults[] can be used to dynamically override survey field defaults (defaults[/path/to/node]=value)
  • optional parameter parent_window_origin can be used to safely enable an iframed survey to post messages back to the parent window
  • 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", "offline_url": "https://enke.to/x/abcd", "single_url": "https://enke.to/single/abcd", "single_iframe_url": "https://enke.to/single/i/abcd", "single_once_url": "https://enke.to/single/werdgag3e423gsgadgsd", "single_once_iframe_url": "https://enke.to/single/i/werdgag3e423gsgadgsd", "preview_url": "https://enke.to/preview/abcd", "preview_iframe_url": "https://enke.to/preview/i/abcd", "enketo_id": "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

POST /survey Get an online-only survey (new or existing)

In API v2 this always returns an online-only survey.

In API v2 the defaults and theme parameters were added.

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 theme can be used to centrally override the theme for all subsequent users, or to reset the theme with an empty string value
  • optional parameter defaults[] can be used to dynamically override survey field defaults (defaults[/path/to/node]=value)
  • 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 201 400 401 403 404 405 410

Try in terminal

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

This returns an online-only iframe-friendly survey.

In API v2 this returns a response with an iframe_url property.

In API v2 the theme, defaults, and parent_window_origin parameters were added.

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 theme can be used to centrally override the theme for all subsequent users, or to reset the theme with an empty string value
  • optional parameter defaults[] can be used to dynamically override survey field defaults (defaults[/path/to/node]=value)
  • optional parameter parent_window_origin can be used to safely enable an iframed survey to post messages back to the parent window
  • headers must include a valid API key as username in the Authorization header

Authorization: Basic API_KEY:

Response

Sends back an object including the iframe_url property.

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

For error responses, see the response status codes documentation.

200 201 400 401 403 404 405 410

Try in terminal

POST /survey/offline Get an offline-capable survey (new or existing)

This returns an offline-capable survey.

This endpoint is new in API v2.

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 theme can be used to centrally override the theme for all subsequent users, or to reset the theme with an empty string value
  • 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) { "offline_url": "https://enke.to/abcd", "code": 200 }

For error responses, see the response status codes documentation.

200 201 400 401 403 404 405 410

Try in terminal

POST /survey/single Get an online-only single-submit survey (new or existing)

This webform view will always redirect the user upon successful submission of a single record.

In API v2 the theme and defaults parameters were added.

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 theme can be used to centrally override the theme for all subsequent users, or to reset the theme with an empty string value
  • optional parameter return_url is the URL to redirect the user to after submission/close (default is a generic thank you page)
  • optional parameter defaults[] can be used to dynamically override survey field defaults (defaults[/path/to/node]=value)
  • headers must include a valid API key as username in the Authorization header

Authorization: Basic API_KEY:

Response

Sends back an object including a single_url property.

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

For error responses, see the response status codes documentation.

200 201 400 401 403 404 405 410

Try in terminal

POST /survey/single/iframe Get an online-only single-submit iframe-able survey (new or existing)

This webform view will always redirect the user upon successful submission of a single record.

In API v2 the theme, defaults, and parent_window_origin parameters were added.

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 theme can be used to centrally override the theme for all subsequent users, or to reset the theme with an empty string value
  • optional parameter return_url is the URL to redirect the user to after submission/close (default is a generic thank you page)
  • optional parameter defaults[] can be used to dynamically override survey field defaults (defaults[/path/to/node]=value)
  • optional parameter parent_window_origin can be used to safely enable an iframed survey to post messages back to the parent window
  • 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_iframe_url property.

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

For error responses, see the response status codes documentation.

200 201 400 401 403 404 405 410

Try in terminal

POST /survey/single/once Get an online-only single-submit survey that can be submitted once per user (new or existing)

This webform view will always redirect the user upon successful submission of a single record. It has some basic protection to prevent the same user (browser & device) from submitting more than once.

This endpoint is new in API v2.

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 theme can be used to centrally override the theme for all subsequent users, or to reset the theme with an empty string value
  • optional parameter return_url is the URL to redirect the user to after submission/close (default is a generic thank you page)
  • optional parameter defaults[] can be used to dynamically override survey field defaults (defaults[/path/to/node]=value)
  • 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_once_url property.

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

For error responses, see the response status codes documentation.

200 201 400 401 403 404 405 410

Try in terminal

POST /survey/single/once/iframe Get an online-only single-submit iframe-able survey that can be submitted once per user (new or existing)

This webform view will always redirect the user upon successful submission of a single record. It has some basic protection to prevent the same user (browser & device) from submitting more than once.

This endpoint is new in API v2.

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 theme can be used to centrally override the theme for all subsequent users, or to reset the theme with an empty string value
  • optional parameter return_url is the URL to redirect the user to after submission/close (default is a generic thank you page)
  • optional parameter defaults[] can be used to dynamically override survey field defaults (defaults[/path/to/node]=value)
  • optional parameter parent_window_origin can be used to safely enable an iframed survey to post messages back to the parent window
  • 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_once_iframe_url property.

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

For error responses, see the response status codes documentation.

200 201 400 401 403 404 405 410

Try in terminal

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

In API v2 the theme, go_to, and defaults parameters were added.

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 theme can be used to centrally override the theme for all subsequent users, or to reset the theme with an empty string value
  • optional parameter defaults[] can be used to dynamically override survey field defaults (defaults[/path/to/node]=value)
  • optional parameter go_to can be used to jump to a specific question upon load. It takes any XPath (go_to=//question or go_to=//complex/repeat[3]//question).
  • 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 201 400 401 403 404 405 410

Try in terminal

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

In API v2 the theme, go_to, and defaults parameters were added.

In API v2 the return property was changed to `preview_iframe_url`.

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 theme can be used to centrally override the theme for all subsequent users, or to reset the theme with an empty string value
  • optional parameter defaults[] can be used to dynamically override survey field defaults (defaults[/path/to/node]=value)
  • optional parameter go_to can be used to jump to a specific question upon load. It takes any XPath (go_to=//question or go_to=//complex/repeat[3]//question).
  • 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_iframe_url": "https://enke.to/preview/i/abcd", "code": 200 }

For error responses, see the response status codes documentation.

200 201 400 401 403 404 405 410

Try in terminal

POST /survey/view Get a read-only survey (new or existing)

This view shows an empty readonly form.

This endpoint is new in API v2.

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)
  • optional parameter go_to can be used to jump to a specific question upon load. It takes any XPath (go_to=//question or go_to=//complex/repeat[3]//question).
  • headers must include a valid API key as username in the Authorization header

Authorization: Basic API_KEY:

Response

Sends back an object including a view_url property.

Status: 200 OK (existing) Status: 201 OK (new) { "view_url": "https://enke.to/view/abcd232agdf3434sgdra34", "code": 200 }

For error responses, see the response status codes documentation.

200 201 400 401 403 404 405 410

Try in terminal

POST /survey/view/iframe Get a read-only iframe-able survey (new or existing)

This view shows an empty readonly iframe-able form.

This endpoint is new in API v2.

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)
  • optional parameter go_to can be used to jump to a specific question upon load. It takes any XPath (go_to=//question or go_to=//complex/repeat[3]//question).
  • optional parameter parent_window_origin can be used to safely enable an iframed survey to post messages back to the parent window
  • headers must include a valid API key as username in the Authorization header

Authorization: Basic API_KEY:

Response

Sends back an object including a view_url property.

Status: 200 OK (existing) Status: 201 OK (new) { "view_iframe_url": "https://enke.to/view/abcd232agdf3434sgdra34", "code": 200 }

For error responses, see the response status codes documentation.

200 201 400 401 403 404 405 410

Try in terminal

POST /survey/view/pdf Get a PDF of the survey (new or existing)

The PDF shows an empty form.

This endpoint is new in API v2.

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 format the paper format. Valid values are: Letter, Legal, Tabloid, Ledger, A0, A1, A2, A3, A4, A5, and A6. Default is A4.
  • optional parameter margin the paper margin. Valid units are: in, cm, and mm. Example values are 2.1in, 2cm, 10mm. Default is 0.5in.
  • optional parameter landscape whether paper orientation is landscape. Valid values ar true, false. Default is false.
  • headers must include a valid API key as username in the Authorization header

Authorization: Basic API_KEY:

Response

Sends back a PDF file or a JSON error response.

Status: 200 OK (existing) Status: 201 OK (new)

For error responses, see the response status codes documentation.

200 201 400 401 403 404 405 410

Try in terminal

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

The response property names have changed in API v2.

In API v2 the theme, defaults, and parent_window_origin parameters were added.

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 theme can be used to centrally override the theme for all subsequent users, or to reset the theme with an empty string value
  • optional parameter return_url is the URL to redirect the user to after submission/close (default is a generic thank you page)
  • optional
  • optional parameter defaults[] can be used to dynamically override survey field defaults (defaults[/path/to/node]=value)
  • optional parameter parent_window_origin can be used to safely enable an iframed survey to post messages back to the parent window
  • 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", "offline_url": "https://enke.to/x/abcd", "single_url": "https://enke.to/single/abcd", "single_iframe_url": "https://enke.to/single/i/abcd", "single_once_url": "https://enke.to/single/werdgag3e423gsgadgsd", "single_once_iframe_url": "https://enke.to/single/i/werdgag3e423gsgadgsd", "preview_url": "https://enke.to/preview/abcd", "preview_iframe_url": "https://enke.to/preview/i/abcd", "enketo_id": "abcd", "code": 200 }

For error responses, see the response status codes documentation.

200 201 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) [EMPTY]

For error responses, see the response status codes documentation.

204 400 401 403 404 405 410

Try in terminal

DELETE /survey/cache Flush a survey cache

Remove the cached survey transformation results from Enketo. To be used when an already-launched XForm has been edited and is re-published. Highly recommended to use this only when necessary to avoid severe loading performance degradation.

This endpoint is new in API v2.

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 flushed) [EMPTY]

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 { "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

In API v2 the defaults and parent_window_origin parameters were added.

In API v2 the response properties have changed.

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
  • optional parameter defaults[] can be used to dynamically override survey field defaults (defaults[/path/to/node]=value)
  • optional parameter parent_window_origin can be used to safely enable an iframed survey to post messages back to the parent window
  • 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", "enketo_id": "abcd", "url": "https://enke.to/abcd", "iframe_url": "https://enke.to/i/abcd", "offline_url": "https://enke.to/x/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", "enketo_id": "abcd" }, { "server_url": "https://myserver.com/bob", "form_id": "birds", "enketo_id": "efgh", "url": "https://enke.to/efgh", "iframe_url": "https://enke.to/i/efgh", "offline_url": "https://enke.to/x/efgh", "single_url": "https://enke.to/single/abcag3e423gsgadgsd", "single_iframe_url": "https://enke.to/single/i/abcag3e423gsgadgsd", "preview_url": "https://enke.to/preview/efgh", "preview_iframe_url": "https://enke.to/preview/i/efgh", "enketo_id": "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 { "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

In API v2 the defaults and parent_window_origin parameters were added.

In API v2 the response properties have changed.

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
  • optional parameter defaults[] can be used to dynamically override survey field defaults (defaults[/path/to/node]=value)
  • optional parameter parent_window_origin can be used to safely enable an iframed survey to post messages back to the parent window
  • 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", "enketo_id": "abcd", "url": "https://enke.to/abcd", "iframe_url": "https://enke.to/i/abcd", "offline_url": "https://enke.to/x/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", "enketo_id": "abcd" }, { "server_url": "https://myserver.com/bob", "form_id": "birds", "enketo_id": "efgh", "url": "https://enke.to/efgh", "iframe_url": "https://enke.to/i/efgh", "offline_url": "https://enke.to/x/efgh", "single_url": "https://enke.to/single/abcag3e423gsgadgsd", "single_iframe_url": "https://enke.to/single/i/abcag3e423gsgadgsd", "preview_url": "https://enke.to/preview/efgh", "preview_iframe_url": "https://enke.to/preview/i/efgh", "enketo_id": "efgh" } ], "code": 200 }

For error responses, see the response status codes documentation.

200 400 401 403 404 410

Try in terminal

POST /instance Load an instance for editing

This webform view edits an existing already-submitted finalized record.

In API v2 the instance_attachments, and go_to parameters were added.

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
  • optional parameter instance_attachments[] can be used to pass attachments for the instance to be edited (instance_attachments[file.name]=https://example.com)
  • optional parameter return_url is the URL to redirect the user to after submission/close (default is a generic thank you page)
  • optional parameter go_to can be used to jump to a specific question upon load. It takes any XPath (go_to=//question or go_to=//complex/repeat[3]//question).
  • 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: 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 Load an instance for editing in an iframe

This webform view edits an existing already-submitted finalized record.

In API v2 the instance_attachments, and go_to parameters were added.

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
  • optional parameter instance_attachments[] can be used to pass attachments for the instance to be edited (instance_attachments[file.name]=https://example.com)
  • optional parameter return_url is the URL to redirect the user to after submission/close (default is a generic thank you page)
  • optional parameter go_to can be used to jump to a specific question upon load. It takes any XPath (go_to=//question or go_to=//complex/repeat[3]//question).
  • 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: 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

POST /instance/view Load an instance for viewing

This view shows a record loaded into a readonly form.

This endpoint is new in API v2.

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
  • optional parameter instance_attachments[] can be used to pass attachments for the instance to be edited (instance_attachments[file.name]=https://example.com)
  • optional parameter return_url is the URL to redirect the user to after submission/close (default is a generic thank you page)
  • optional parameter go_to can be used to jump to a specific question upon load. It takes any XPath (go_to=//question or go_to=//complex/repeat[3]//question).
  • headers must include a valid API key as username in the Authorization header

Authorization: Basic API_KEY:

Response

Sends back an object including a view_url property.

Status: 201 OK { "view_url": "https://enke.to/view/abcd232agdf3434sgdra34?instance_id=abcd", "code": 201 }

For error responses, see the response status codes documentation.

201 400 401 403 404 405 410

Try in terminal

POST /instance/view/iframe Load an instance for viewing in an iframe

This view shows a record loaded into a readonly iframe-able survey.

This endpoint is new in API v2.

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
  • optional parameter instance_attachments[] can be used to pass attachments for the instance to be edited (instance_attachments[file.name]=https://example.com)
  • optional parameter return_url is the URL to redirect the user to after submission/close (default is a generic thank you page)
  • optional parameter go_to can be used to jump to a specific question upon load. It takes any XPath (go_to=//question or go_to=//complex/repeat[3]//question).
  • optional parameter parent_window_origin can be used to safely enable an iframed survey to post messages back to the parent window
  • headers must include a valid API key as username in the Authorization header

Authorization: Basic API_KEY:

### Response Sends back an object including a view_url property. ```Status: 201 OK``` ```{ "view_iframe_url": "https://enke.to/view/abcd232agdf3434sgdra34?instance_id=abcd", "code": 201 }```

For error responses, see the response status codes documentation.

201 400 401 403 404 405 410

Try in terminal

POST /instance/view/pdf Load an instance and view form as PDF.

The PDF shows an form with a record.

This endpoint is new in API v2.

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
  • optional parameter instance_attachments[] can be used to pass attachments for the instance to be edited (instance_attachments[file.name]=https://example.com)
  • optional parameter return_url is the URL to redirect the user to after submission/close (default is a generic thank you page)
  • optional parameter format the paper format. Valid values are: Letter, Legal, Tabloid, Ledger, A0, A1, A2, A3, A4, A5, and A6. Default is A4.
  • optional parameter margin the paper margin. Valid units are: in, cm, and mm. Example values are 2.1in, 2cm, 10mm. Default is 0.5in.
  • optional parameter landscape whether paper orientation is landscape. Valid values ar true, false. Default is false.
  • headers must include a valid API key as username in the Authorization header

Authorization: Basic API_KEY:

Response

Sends back a PDF file or a JSON error response.

Status: 201 OK

For error responses, see the response status codes documentation.

200 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