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.