The participant administration API allows you to manage your participants. You can find groups of participants or specific participants and update their data.
Contents
The basic participant object is common to many of the participant APIs.
Auto-generated, internal identifier for this participant.
Whether the participant has completed enrollment.
Date when the participant completed enrollment, in ISO8601 format.
Date when the participant record was created, in ISO8601 format.
Status of the participant’s invitation: pending, declined, cancelled, approved, notInvited, or null (not set).
Project-specific participant identifier.
Project-specific secondary identifier
Auto-generated identifier used to complete surveys via link, if that feature is enabled for the project.
Key/value pairs containing basic participant demographics. Empty demographics will be omitted from queries.
Must be unique within a project. Cannot be updated once a participant has enrolled.
Date in YYYY-MM-DD format.
Preferred language, based on device settings.
Gender code: M, F, O, or null.
Line 1 of the street address.
Line 2 of the street address.
Must be unique within a project. Cannot be updated once a participant has enrolled.
Timezone represented as a UTC offset, e.g., -04:00:00.
Key/value pairs containing project-specific custom fields.
Specifies whether this participant is excluded from data exports. Typically used for test or withdrawn participants.
{
"id": "3a713a06-295d-4803-9602-776f09a1483b",
"enrolled": true,
"invitationStatus": "approved",
"insertedDate": "2020-06-16T15:23:00.9+00:00",
"enrollmentDate": "2020-06-16T15:23:00.967+00:00",
"participantIdentifier": "4c9d3554-7cb1-456e-89ca-5387bda4803c",
"secondaryIdentifier": "419d567e-76e6-4b53-8b3c-567d7260a85d",
"linkIdentifier": "0971fbcd-ec92-414c-bd49-41a3c8b6547b",
"demographics": {
"email": "somebody@example.com",
"firstName": "John",
"middleName": "James",
"lastName": "Smith",
"dateOfBirth": "2000-06-16",
"preferredLanguage": "en",
"gender": "M",
"utcOffset": "-04:00:00",
"street1": "123 Main Street",
"street2": "Apartment #1",
"city": "Anytown",
"state": "NY",
"postalCode": "12345"
},
"customFields": {
"Medication1": "Warfarin",
"Smoker": 0,
"SurgeryDate": "2021-08-10"
},
"excludeFromExport": false
}
{
"id": "3a713a06-295d-4803-9602-776f09a1483b",
"enrolled": true,
"invitationStatus": "approved",
"insertedDate": "2020-06-16T15:23:00.9+00:00",
"enrollmentDate": "2020-06-16T15:23:00.967+00:00",
"participantIdentifier": "4c9d3554-7cb1-456e-89ca-5387bda4803c",
"secondaryIdentifier": "419d567e-76e6-4b53-8b3c-567d7260a85d",
"linkIdentifier": "0971fbcd-ec92-414c-bd49-41a3c8b6547b",
"demographics": {
"email": "somebody@example.com",
"firstName": "John",
"middleName": "James",
"lastName": "Smith",
"dateOfBirth": "2000-06-16",
"preferredLanguage": "en",
"gender": "M",
"utcOffset": "-04:00:00",
"street1": "123 Main Street",
"street2": "Apartment #1",
"city": "Anytown",
"state": "NY",
"postalCode": "12345"
},
"customFields": {
"Medication1": "Warfarin",
"Smoker": 0,
"SurgeryDate": "2021-08-10"
},
"excludeFromExport": false
}
GET /api/v1/administration/projects/:projectId/participants?query=Smith&pageSize=10
Limits search to participants with a demographic field or identifier containing this string. When a segment ID is provided, this will also search custom fields.
Limits search to participants in a certain segment.
You can query by a custom field using a query parameter named customField.NAMEOFCUSTOMFIELD
. For example, /participants?customfield.StateOfResidence=AR
. You may have multiple custom field query parameters.
Specifies how participants will be sorted. Only valid when segment ID is specified. Possible values are: CustomField.FIELD_NAME, DemographicField.DEMOGRAPHIC_NAME, ParticipantIdentifier, SecondaryIdentifier, InvitationStatus, InsertedDate (default), and EnrollmentDate
Specify true to sort in ascending order, false in descending order. Only valid when segment ID is specified.
If participants span multiple pages, this parameter specifies which page to retrieve. 0-indexed.
The number of participants returned per page.
The total number of participants in the query.
A list of data fields for each participant matching the query.
Auto-generated, internal identifier for this participant.
Whether the participant has completed enrollment.
Date when the participant completed enrollment, in ISO8601 format.
Date when the participant record was created, in ISO8601 format.
Status of the participant’s invitation: pending, declined, cancelled, approved, notInvited, or null (not set).
Project-specific participant identifier.
Project-specific secondary identifier
Auto-generated identifier used to complete surveys via link, if that feature is enabled for the project.
Key/value pairs containing basic participant demographics. Empty demographics will be omitted from queries.
Must be unique within a project. Cannot be updated once a participant has enrolled.
Date in YYYY-MM-DD format.
Preferred language, based on device settings.
Gender code: M, F, O, or null.
Line 1 of the street address.
Line 2 of the street address.
Must be unique within a project. Cannot be updated once a participant has enrolled.
Timezone represented as a UTC offset, e.g., -04:00:00.
Key/value pairs containing project-specific custom fields.
Specifies whether this participant is excluded from data exports. Typically used for test or withdrawn participants.
If participants span multiple pages, this is the page returned. 0-indexed.
{
"pageNumber": 0,
"totalParticipants": 4,
"participants": [
{
"id": "3a713a06-295d-4803-9602-776f09a1483b",
"enrolled": true,
"invitationStatus": "approved",
...
},
{
"id": "c9238480-6a9d-11eb-9439-0242ac130002",
"enrolled" false,
"invitationStatus": "pending",
...
},
...
]
}
{
"pageNumber": 0,
"totalParticipants": 4,
"participants": [
{
"id": "3a713a06-295d-4803-9602-776f09a1483b",
"enrolled": true,
"invitationStatus": "approved",
...
},
{
"id": "c9238480-6a9d-11eb-9439-0242ac130002",
"enrolled" false,
"invitationStatus": "pending",
...
},
...
]
}
GET /api/v1/administration/projects/:projectId/participants/:participantID
When false (the default), the participantId segment will be interpreted as the ParticipantIdentifier. When true, the participantId will be interpreted as the internal ID.
Auto-generated, internal identifier for this participant.
Whether the participant has completed enrollment.
Date when the participant completed enrollment, in ISO8601 format.
Date when the participant record was created, in ISO8601 format.
Status of the participant’s invitation: pending, declined, cancelled, approved, notInvited, or null (not set).
Project-specific participant identifier.
Project-specific secondary identifier
Auto-generated identifier used to complete surveys via link, if that feature is enabled for the project.
Key/value pairs containing basic participant demographics. Empty demographics will be omitted from queries.
Must be unique within a project. Cannot be updated once a participant has enrolled.
Date in YYYY-MM-DD format.
Preferred language, based on device settings.
Gender code: M, F, O, or null.
Line 1 of the street address.
Line 2 of the street address.
Must be unique within a project. Cannot be updated once a participant has enrolled.
Timezone represented as a UTC offset, e.g., -04:00:00.
Key/value pairs containing project-specific custom fields.
Specifies whether this participant is excluded from data exports. Typically used for test or withdrawn participants.
{
"id": "3a713a06-295d-4803-9602-776f09a1483b",
"enrolled": true,
"invitationStatus": "approved",
...
}
{
"id": "3a713a06-295d-4803-9602-776f09a1483b",
"enrolled": true,
"invitationStatus": "approved",
...
}
PUT /api/v1/administration/projects/:projectId/participants
The following parameters may be included in the body of the request, and will be stored or updated on the participant. Partial updates are supported.
Status of the participant’s invitation: pending, declined, cancelled, approved, notInvited, or null (not set).
Project-specific participant identifier.
Project-specific secondary identifier
Key/value pairs containing basic participant demographics. Empty demographics will be omitted from queries.
Must be unique within a project. Cannot be updated once a participant has enrolled.
Date in YYYY-MM-DD format.
Preferred language, based on device settings.
Gender code: M, F, O, or null.
Line 1 of the street address.
Line 2 of the street address.
Must be unique within a project. Cannot be updated once a participant has enrolled.
Timezone represented as a UTC offset, e.g., -04:00:00.
Key/value pairs containing project-specific custom fields.
Specifies whether this participant is excluded from data exports. Typically used for test or withdrawn participants.
Indicates whether the participant was added or updated.
The added or updated participant record.
Auto-generated, internal identifier for this participant.
Whether the participant has completed enrollment.
Date when the participant completed enrollment, in ISO8601 format.
Date when the participant record was created, in ISO8601 format.
Status of the participant’s invitation: pending, declined, cancelled, approved, notInvited, or null (not set).
Project-specific participant identifier.
Project-specific secondary identifier
Auto-generated identifier used to complete surveys via link, if that feature is enabled for the project.
Key/value pairs containing basic participant demographics. Empty demographics will be omitted from queries.
Must be unique within a project. Cannot be updated once a participant has enrolled.
Date in YYYY-MM-DD format.
Preferred language, based on device settings.
Gender code: M, F, O, or null.
Line 1 of the street address.
Line 2 of the street address.
Must be unique within a project. Cannot be updated once a participant has enrolled.
Timezone represented as a UTC offset, e.g., -04:00:00.
Key/value pairs containing project-specific custom fields.
Specifies whether this participant is excluded from data exports. Typically used for test or withdrawn participants.
{
"demographics": {
"email": "someone@example.com",
"name": "John Doe"
},
"secondaryIdentifier": "P1111",
"customFields": {
"Smoker": 1
}
}
{
"demographics": {
"email": "someone@example.com",
"name": "John Doe"
},
"secondaryIdentifier": "P1111",
"customFields": {
"Smoker": 1
}
}
{
"actionTaken": "update",
"result": {
"id": "3a713a06-295d-4803-9602-776f09a1483b",
"enrolled": true,
"invitationStatus": "pending"
...
}
}
{
"actionTaken": "update",
"result": {
"id": "3a713a06-295d-4803-9602-776f09a1483b",
"enrolled": true,
"invitationStatus": "pending"
...
}
}
POST /api/v1/administration/projects/:projectId/participants
Determines whether existing participants may be updated by the request. If allowUpdate
is false and an existing participantIdentifier
is passed in, an error will be returned.
List of participant data.
Status of the participant’s invitation: pending, declined, cancelled, approved, notInvited, or null (not set).
Project-specific participant identifier.
Project-specific secondary identifier
Key/value pairs containing basic participant demographics. Empty demographics will be omitted from queries.
Must be unique within a project. Cannot be updated once a participant has enrolled.
Date in YYYY-MM-DD format.
Preferred language, based on device settings.
Gender code: M, F, O, or null.
Line 1 of the street address.
Line 2 of the street address.
Must be unique within a project. Cannot be updated once a participant has enrolled.
Timezone represented as a UTC offset, e.g., -04:00:00.
Key/value pairs containing project-specific custom fields.
Specifies whether this participant is excluded from data exports. Typically used for test or withdrawn participants.
Whether the system should send invitation notifications to the new participants. (Default false.)
The number of participants added.
The number of participants updated.
A list of the newly added or updated participant records.
Indicates whether the participant was added or updated.
The added or updated participant record.
Auto-generated, internal identifier for this participant.
Whether the participant has completed enrollment.
Date when the participant completed enrollment, in ISO8601 format.
Date when the participant record was created, in ISO8601 format.
Status of the participant’s invitation: pending, declined, cancelled, approved, notInvited, or null (not set).
Project-specific participant identifier.
Project-specific secondary identifier
Auto-generated identifier used to complete surveys via link, if that feature is enabled for the project.
Key/value pairs containing basic participant demographics. Empty demographics will be omitted from queries.
Must be unique within a project. Cannot be updated once a participant has enrolled.
Date in YYYY-MM-DD format.
Preferred language, based on device settings.
Gender code: M, F, O, or null.
Line 1 of the street address.
Line 2 of the street address.
Must be unique within a project. Cannot be updated once a participant has enrolled.
Timezone represented as a UTC offset, e.g., -04:00:00.
Key/value pairs containing project-specific custom fields.
Specifies whether this participant is excluded from data exports. Typically used for test or withdrawn participants.
{
"participants": [
{
"demographics": {
"email": "someone@example.com",
"name": "John Doe"
},
"secondaryIdentifier": "P1111",
"customFields": {
"Smoker": 1
}
},
{
"demographics": {
"email": "someone-else@example.com",
"name": "Another Test Person"
},
"participantIdentifier": "3a713a06...",
"customFields": {
"Smoker": 0
}
},
...
],
"sendDefaultInvitationNotifications" : true
}
{
"participants": [
{
"demographics": {
"email": "someone@example.com",
"name": "John Doe"
},
"secondaryIdentifier": "P1111",
"customFields": {
"Smoker": 1
}
},
{
"demographics": {
"email": "someone-else@example.com",
"name": "Another Test Person"
},
"participantIdentifier": "3a713a06...",
"customFields": {
"Smoker": 0
}
},
...
],
"sendDefaultInvitationNotifications" : true
}
{
"totalAdded": 1,
"totalUpdated": 2,
"results": [
{
"actionTaken": "update",
"result": {
"id": "3a713a06-295d-4803-9602-776f09a1483b",
"enrolled": true,
"invitationStatus": "approved"
...
}
},
{
"actionTaken": "add",
"result": {
"id": "c9238480-6a9d-11eb-9439-0242ac130002",
"enrolled" false,
"invitationStatus": "pending",
...
},
},
...
]
}
{
"totalAdded": 1,
"totalUpdated": 2,
"results": [
{
"actionTaken": "update",
"result": {
"id": "3a713a06-295d-4803-9602-776f09a1483b",
"enrolled": true,
"invitationStatus": "approved"
...
}
},
{
"actionTaken": "add",
"result": {
"id": "c9238480-6a9d-11eb-9439-0242ac130002",
"enrolled" false,
"invitationStatus": "pending",
...
},
},
...
]
}
DELETE /api/v1/administration/projects/:projectId/participants/:participantID
When false (the default), the participantID segment will be interpreted as the ParticipantIdentifier. When true, the participantID will be interpreted as the internal ID.
Indicates that the participant was deleted.
The deleted participant record.
Auto-generated, internal identifier for this participant.
Whether the participant has completed enrollment.
Date when the participant completed enrollment, in ISO8601 format.
Date when the participant record was created, in ISO8601 format.
Status of the participant’s invitation: pending, declined, cancelled, approved, notInvited, or null (not set).
Project-specific participant identifier.
Project-specific secondary identifier
Auto-generated identifier used to complete surveys via link, if that feature is enabled for the project.
Key/value pairs containing basic participant demographics. Empty demographics will be omitted from queries.
Must be unique within a project. Cannot be updated once a participant has enrolled.
Date in YYYY-MM-DD format.
Preferred language, based on device settings.
Gender code: M, F, O, or null.
Line 1 of the street address.
Line 2 of the street address.
Must be unique within a project. Cannot be updated once a participant has enrolled.
Timezone represented as a UTC offset, e.g., -04:00:00.
Key/value pairs containing project-specific custom fields.
Specifies whether this participant is excluded from data exports. Typically used for test or withdrawn participants.
{
"totalAdded": 1,
"totalUpdated": 2,
"results": [
{
"actionTaken": "update",
"result": {
"id": "3a713a06-295d-4803-9602-776f09a1483b",
"enrolled": true,
"invitationStatus": "pending"
...
}
}
]
}
{
"totalAdded": 1,
"totalUpdated": 2,
"results": [
{
"actionTaken": "update",
"result": {
"id": "3a713a06-295d-4803-9602-776f09a1483b",
"enrolled": true,
"invitationStatus": "pending"
...
}
}
]
}