Participant API version 1

This API is for managing an intervention as a single participant. It uses the session cookie for authentication and so JavaScript code will automatically authenticate as the logged in participant. If you need to perform changes to an intervention as a whole (e.g. create users, access user data for any participant, etc.) then see REST API version 1

API usage

The API is intended to be used by JavaScript embedded into the intervention pages to manage aspects of the current participant. For this reason, it uses the same authentication method (cookie-based session identifier) as the regular intervention pages.

The API will not be available if there is no intervention session associated with the browser. The intervention session only starts on the first POST request received from the browser (otherwise, the session data would be overwhelmed by search and AI bot activity). In this case, the API will return a 404 HTTP response.

If the intervention session has started but there is no current participant yet, then the API will return a 401 HTTP response.

Quick example

Here is a minimal example using the Fetch API:

Code	Response
async function getUserData() { const command = { type: "listUserData", }; const response = await fetch("/api/v1", { method: "POST", body: JSON.stringify(command) }); return await response.json(); } // Example call: const response = await getUserData();	{ "data": [ "age", "gender", "weight" ], "status": "ok" }

Accessing user data

List user data

API request to list user data. All user data fields are returned without pagination.

Request	Response
{ "type": "listUserData" }	{ "data": [ "age", "gender", "weight" ], "status": "ok" }

Get user data

API request to get user data.

Request	Response
{ "type": "getUserData", "id": "age" }	{ "data": 25, "id": "age", "status": "ok" }

If the user data field does not exist then the response will have a status value of "notFound".

Set user data

API request to create or update user data.

Request	Response
{ "type": "setUserData", "id": "consent", "data": true }	{ "id": "consent", "status": "ok" }

Delete user data

API request to delete user data.

Request	Response
{ "type": "deleteUserData", "id": "goal1" }	{ "id": "goal1", "status": "ok" }

If the user data field does not exist then the response will have a status value of "notFound".

Combining multiple API requests into a single HTTP request

An array of requests can be provided instead of a single request. In this case, the API will return an array of responses in the same order as the requests provided.

An example that gets two user data fields.

Code	Response
async function processMultipleRequests() { const commands = [ { type: "getUserData", id: "age", }, { type: "getUserData", id: "consent" } ]; const response = await fetch("/api/v1", { method: "POST", body: JSON.stringify(commands) }); return await response.json(); } // Example call: const response = await processMultipleRequests();	[ { "data": 25, "id": "age", "status": "ok" }, { "data": true, "id": "consent", "status": "ok" } ]

You can mix and match request types, e.g. setting three fields and deleting a fourth field.