REST API
Resources
Participant Administration API
The participant administration API allows you to manage your participants. You can find groups of participants or specific participants and update their data.
Contents
Participant Object
The basic participant object is common to many of the participant APIs.
See Data Overview for important information on the differences between the various types of participant identifiers.
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
}
Query Participants
GET /api/v1/administration/projects/:projectId/participants?query=Smith&pageSize=10
Query Parameters
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.
Response Fields
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 Participant
GET /api/v1/administration/projects/:projectId/participants/:participantID
Query Parameters
When false (the default), the participantId segment will be interpreted as the ParticipantIdentifier. When true, the participantId will be interpreted as the internal ID.
Response Fields
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",
...
}
Add/Update Participant
PUT /api/v1/administration/projects/:projectId/participants
Body Parameters
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.
If you want to update an existing participant, the body parameters must include either a ParticipantIdentifier or ID field matching the participant’s existing record. To add a new participant, you must include either a ParticipantIdentifier or email.
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.
Response Fields
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"
...
}
}
Bulk Add/Update Participants
POST /api/v1/administration/projects/:projectId/participants
Query Parameters
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.
Body Parameters
If you want to update an existing participant, the body parameters must include either a ParticipantIdentifier or ID field matching the participant’s existing record. To add a new participant, you must include either a ParticipantIdentifier or email.
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.)
Response Fields
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 Participant
DELETE /api/v1/administration/projects/:projectId/participants/:participantID
Query Parameters
When false (the default), the participantID segment will be interpreted as the ParticipantIdentifier. When true, the participantID will be interpreted as the internal ID.
Response Fields
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"
...
}
}
]
}
