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.

Participant Object

The basic participant object is common to many of the participant APIs.

It is important to understand the different kinds of participant identifiers:

  • ParticipantIdentifier is the main, project-specific identifier, visible in the RKStudio participants screen. This can be set in the participant’s invitation to the project, or will be auto-generated. It can be edited at any time, but must remain unique within the project.
  • Id is an auto-generated, globally unique key that can identify the participant across projects. It cannot be changed, and is not visible in the RKStudio screens. It corresponds to the “Global Key” field in the participant data exports.
  • SecondaryIdentifier is an optional project-specific identifier.
  • LinkIdentifier is an auto-generated identifier code used only if the project has allowed survey completion via link.
id guid

Auto-generated, globally-unique identifier for this participant.

enrolled boolean

Whether the participant has completed enrollment.

enrollmentDate date

Date when the participant completed enrollment, in ISO8601 format.

insertedDate date

Date when the participant record was created, in ISO8601 format.

invitationStatus boolean

Status of the participant’s invitation: pending, declined, cancelled, approved, notInvited, or null (not set).

participantIdentifier string

Project-specific participant identifier.

secondaryIdentifier string

Project-specific secondary identifier

linkIdentifier string

Auto-generated identifier used to complete surveys via link, if that feature is enabled for the project.

demographics object

Key/value pairs containing basic participant demographics. Empty demographics will be omitted from queries.

demographics.email string

Must be unique within a project. Cannot be updated once a participant has enrolled.

demographics.firstName string
demographics.middleName string
demographics.lastName string
demographics.dateOfBirth string

Date in YYYY-MM-DD format.

demographics.preferredLanguage string

Preferred language, based on device settings.

demographics.gender string

Gender code: M, F, O, or null.

demographics.street1 string

Line 1 of the street address.

demographics.street2 string

Line 2 of the street address.

demographics.city string
demographics.state string
demographics.postalCode string
demographics.mobilePhone string

Must be unique within a project. Cannot be updated once a participant has enrolled.

demographics.utcOffset string

Timezone represented as a UTC offset, e.g., -04:00:00.

customFields object

Key/value pairs containing project-specific custom fields.

excludeFromExport boolean

Specifies whether this participant is excluded from data exports. Typically used for test or withdrawn participants.

Sample Participant Data
{
  "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

query string

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.

segmentId guid

Limits search to participants in a certain segment.

segmentSortBy string

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

segmentSortAscending boolean

Specify true to sort in ascending order, false in descending order. Only valid when segment ID is specified.

pageNumber integer

If participants span multiple pages, this parameter specifies which page to retrieve. 0-indexed.

pageSize integer

The number of participants returned per page.

Response Fields

totalParticipants integer

The total number of participants in the query.

participants list

A list of data fields for each participant matching the query.

participants.id guid

Auto-generated, globally-unique identifier for this participant.

participants.enrolled boolean

Whether the participant has completed enrollment.

participants.enrollmentDate date

Date when the participant completed enrollment, in ISO8601 format.

participants.insertedDate date

Date when the participant record was created, in ISO8601 format.

participants.invitationStatus boolean

Status of the participant’s invitation: pending, declined, cancelled, approved, notInvited, or null (not set).

participants.participantIdentifier string

Project-specific participant identifier.

participants.secondaryIdentifier string

Project-specific secondary identifier

participants.linkIdentifier string

Auto-generated identifier used to complete surveys via link, if that feature is enabled for the project.

participants.demographics object

Key/value pairs containing basic participant demographics. Empty demographics will be omitted from queries.

participants.demographics.email string

Must be unique within a project. Cannot be updated once a participant has enrolled.

participants.demographics.firstName string
participants.demographics.middleName string
participants.demographics.lastName string
participants.demographics.dateOfBirth string

Date in YYYY-MM-DD format.

participants.demographics.preferredLanguage string

Preferred language, based on device settings.

participants.demographics.gender string

Gender code: M, F, O, or null.

participants.demographics.street1 string

Line 1 of the street address.

participants.demographics.street2 string

Line 2 of the street address.

participants.demographics.city string
participants.demographics.state string
participants.demographics.postalCode string
participants.demographics.mobilePhone string

Must be unique within a project. Cannot be updated once a participant has enrolled.

participants.demographics.utcOffset string

Timezone represented as a UTC offset, e.g., -04:00:00.

participants.customFields object

Key/value pairs containing project-specific custom fields.

participants.excludeFromExport boolean

Specifies whether this participant is excluded from data exports. Typically used for test or withdrawn participants.

pageNumber integer

If participants span multiple pages, this is the page returned. 0-indexed.

Sample Response
{
  "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",
      ...
    },
    ...
  ]
}
               
    
See Participant Object for all participant fields.

Get Participant

GET /api/v1/administration/projects/:projectId/participants/:participantId

Query Parameters

queryById boolean

When false (the default), the participantId segment will be interpreted as the ParticipantIdentifier. When true, the participantId will be interpreted as the global ID.

Response Fields

id guid

Auto-generated, globally-unique identifier for this participant.

enrolled boolean

Whether the participant has completed enrollment.

enrollmentDate date

Date when the participant completed enrollment, in ISO8601 format.

insertedDate date

Date when the participant record was created, in ISO8601 format.

invitationStatus boolean

Status of the participant’s invitation: pending, declined, cancelled, approved, notInvited, or null (not set).

participantIdentifier string

Project-specific participant identifier.

secondaryIdentifier string

Project-specific secondary identifier

linkIdentifier string

Auto-generated identifier used to complete surveys via link, if that feature is enabled for the project.

demographics object

Key/value pairs containing basic participant demographics. Empty demographics will be omitted from queries.

demographics.email string

Must be unique within a project. Cannot be updated once a participant has enrolled.

demographics.firstName string
demographics.middleName string
demographics.lastName string
demographics.dateOfBirth string

Date in YYYY-MM-DD format.

demographics.preferredLanguage string

Preferred language, based on device settings.

demographics.gender string

Gender code: M, F, O, or null.

demographics.street1 string

Line 1 of the street address.

demographics.street2 string

Line 2 of the street address.

demographics.city string
demographics.state string
demographics.postalCode string
demographics.mobilePhone string

Must be unique within a project. Cannot be updated once a participant has enrolled.

demographics.utcOffset string

Timezone represented as a UTC offset, e.g., -04:00:00.

customFields object

Key/value pairs containing project-specific custom fields.

excludeFromExport boolean

Specifies whether this participant is excluded from data exports. Typically used for test or withdrawn participants.

Sample Response
{
  "id": "3a713a06-295d-4803-9602-776f09a1483b",
  "enrolled": true,
  "invitationStatus": "approved",
  ...
}

    
See Participant Object for all participant fields.

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.

invitationStatus boolean

Status of the participant’s invitation: pending, declined, cancelled, approved, notInvited, or null (not set).

participantIdentifier string

Project-specific participant identifier.

secondaryIdentifier string

Project-specific secondary identifier

demographics object

Key/value pairs containing basic participant demographics. Empty demographics will be omitted from queries.

demographics.email string

Must be unique within a project. Cannot be updated once a participant has enrolled.

demographics.firstName string
demographics.middleName string
demographics.lastName string
demographics.dateOfBirth string

Date in YYYY-MM-DD format.

demographics.preferredLanguage string

Preferred language, based on device settings.

demographics.gender string

Gender code: M, F, O, or null.

demographics.street1 string

Line 1 of the street address.

demographics.street2 string

Line 2 of the street address.

demographics.city string
demographics.state string
demographics.postalCode string
demographics.mobilePhone string

Must be unique within a project. Cannot be updated once a participant has enrolled.

demographics.utcOffset string

Timezone represented as a UTC offset, e.g., -04:00:00.

customFields object

Key/value pairs containing project-specific custom fields.

excludeFromExport boolean

Specifies whether this participant is excluded from data exports. Typically used for test or withdrawn participants.

Response Fields

actionTaken string

Indicates whether the participant was added or updated.

result object

The added or updated participant record.

result.id guid

Auto-generated, globally-unique identifier for this participant.

result.enrolled boolean

Whether the participant has completed enrollment.

result.enrollmentDate date

Date when the participant completed enrollment, in ISO8601 format.

result.insertedDate date

Date when the participant record was created, in ISO8601 format.

result.invitationStatus boolean

Status of the participant’s invitation: pending, declined, cancelled, approved, notInvited, or null (not set).

result.participantIdentifier string

Project-specific participant identifier.

result.secondaryIdentifier string

Project-specific secondary identifier

result.linkIdentifier string

Auto-generated identifier used to complete surveys via link, if that feature is enabled for the project.

result.demographics object

Key/value pairs containing basic participant demographics. Empty demographics will be omitted from queries.

result.demographics.email string

Must be unique within a project. Cannot be updated once a participant has enrolled.

result.demographics.firstName string
result.demographics.middleName string
result.demographics.lastName string
result.demographics.dateOfBirth string

Date in YYYY-MM-DD format.

result.demographics.preferredLanguage string

Preferred language, based on device settings.

result.demographics.gender string

Gender code: M, F, O, or null.

result.demographics.street1 string

Line 1 of the street address.

result.demographics.street2 string

Line 2 of the street address.

result.demographics.city string
result.demographics.state string
result.demographics.postalCode string
result.demographics.mobilePhone string

Must be unique within a project. Cannot be updated once a participant has enrolled.

result.demographics.utcOffset string

Timezone represented as a UTC offset, e.g., -04:00:00.

result.customFields object

Key/value pairs containing project-specific custom fields.

result.excludeFromExport boolean

Specifies whether this participant is excluded from data exports. Typically used for test or withdrawn participants.

Sample Body Parameters
{
      "demographics": {
          "email": "someone@example.com",
          "name": "John Doe"
      },
      "secondaryIdentifier": "P1111",
      "customFields": {
          "Smoker": 1
      }
}
    
Sample Response
{
    "actionTaken": "update",
    "result": {
      "id": "3a713a06-295d-4803-9602-776f09a1483b",
      "enrolled": true,
      "invitationStatus": "pending"
      ...
    }
}               
    
See Participant Object for all participant fields.

Bulk Add/Update Participants

POST /api/v1/administration/projects/:projectId/participants

Query Parameters

allowUpdate boolean

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

participants list

List of participant data.

participants.invitationStatus boolean

Status of the participant’s invitation: pending, declined, cancelled, approved, notInvited, or null (not set).

participants.participantIdentifier string

Project-specific participant identifier.

participants.secondaryIdentifier string

Project-specific secondary identifier

participants.demographics object

Key/value pairs containing basic participant demographics. Empty demographics will be omitted from queries.

participants.demographics.email string

Must be unique within a project. Cannot be updated once a participant has enrolled.

participants.demographics.firstName string
participants.demographics.middleName string
participants.demographics.lastName string
participants.demographics.dateOfBirth string

Date in YYYY-MM-DD format.

participants.demographics.preferredLanguage string

Preferred language, based on device settings.

participants.demographics.gender string

Gender code: M, F, O, or null.

participants.demographics.street1 string

Line 1 of the street address.

participants.demographics.street2 string

Line 2 of the street address.

participants.demographics.city string
participants.demographics.state string
participants.demographics.postalCode string
participants.demographics.mobilePhone string

Must be unique within a project. Cannot be updated once a participant has enrolled.

participants.demographics.utcOffset string

Timezone represented as a UTC offset, e.g., -04:00:00.

participants.customFields object

Key/value pairs containing project-specific custom fields.

participants.excludeFromExport boolean

Specifies whether this participant is excluded from data exports. Typically used for test or withdrawn participants.

sendDefaultInvitationNotifications boolean

Whether the system should send invitation notifications to the new participants. (Default false.)

Response Fields

totalAdded string

The number of participants added.

totalUpdated string

The number of participants updated.

results list

A list of the newly added or updated participant records.

results.actionTaken string

Indicates whether the participant was added or updated.

results.result object

The added or updated participant record.

results.result.id guid

Auto-generated, globally-unique identifier for this participant.

results.result.enrolled boolean

Whether the participant has completed enrollment.

results.result.enrollmentDate date

Date when the participant completed enrollment, in ISO8601 format.

results.result.insertedDate date

Date when the participant record was created, in ISO8601 format.

results.result.invitationStatus boolean

Status of the participant’s invitation: pending, declined, cancelled, approved, notInvited, or null (not set).

results.result.participantIdentifier string

Project-specific participant identifier.

results.result.secondaryIdentifier string

Project-specific secondary identifier

results.result.linkIdentifier string

Auto-generated identifier used to complete surveys via link, if that feature is enabled for the project.

results.result.demographics object

Key/value pairs containing basic participant demographics. Empty demographics will be omitted from queries.

results.result.demographics.email string

Must be unique within a project. Cannot be updated once a participant has enrolled.

results.result.demographics.firstName string
results.result.demographics.middleName string
results.result.demographics.lastName string
results.result.demographics.dateOfBirth string

Date in YYYY-MM-DD format.

results.result.demographics.preferredLanguage string

Preferred language, based on device settings.

results.result.demographics.gender string

Gender code: M, F, O, or null.

results.result.demographics.street1 string

Line 1 of the street address.

results.result.demographics.street2 string

Line 2 of the street address.

results.result.demographics.city string
results.result.demographics.state string
results.result.demographics.postalCode string
results.result.demographics.mobilePhone string

Must be unique within a project. Cannot be updated once a participant has enrolled.

results.result.demographics.utcOffset string

Timezone represented as a UTC offset, e.g., -04:00:00.

results.result.customFields object

Key/value pairs containing project-specific custom fields.

results.result.excludeFromExport boolean

Specifies whether this participant is excluded from data exports. Typically used for test or withdrawn participants.

Sample Body Parameters
{
    "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
}
    
Sample Response
{
    "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",
          ...
        },
      },
      ...
    ]
}               
    
See Participant Object for all participant fields.

Delete Participant

DELETE /api/v1/administration/projects/:projectId/participants/:participantId

Query Parameters

queryById boolean

When false (the default), the participantId segment will be interpreted as the ParticipantIdentifier. When true, the participantId will be interpreted as the global ID.

Response Fields

actionTaken string

Indicates that the participant was deleted.

result object

The deleted participant record.

result.id guid

Auto-generated, globally-unique identifier for this participant.

result.enrolled boolean

Whether the participant has completed enrollment.

result.enrollmentDate date

Date when the participant completed enrollment, in ISO8601 format.

result.insertedDate date

Date when the participant record was created, in ISO8601 format.

result.invitationStatus boolean

Status of the participant’s invitation: pending, declined, cancelled, approved, notInvited, or null (not set).

result.participantIdentifier string

Project-specific participant identifier.

result.secondaryIdentifier string

Project-specific secondary identifier

result.linkIdentifier string

Auto-generated identifier used to complete surveys via link, if that feature is enabled for the project.

result.demographics object

Key/value pairs containing basic participant demographics. Empty demographics will be omitted from queries.

result.demographics.email string

Must be unique within a project. Cannot be updated once a participant has enrolled.

result.demographics.firstName string
result.demographics.middleName string
result.demographics.lastName string
result.demographics.dateOfBirth string

Date in YYYY-MM-DD format.

result.demographics.preferredLanguage string

Preferred language, based on device settings.

result.demographics.gender string

Gender code: M, F, O, or null.

result.demographics.street1 string

Line 1 of the street address.

result.demographics.street2 string

Line 2 of the street address.

result.demographics.city string
result.demographics.state string
result.demographics.postalCode string
result.demographics.mobilePhone string

Must be unique within a project. Cannot be updated once a participant has enrolled.

result.demographics.utcOffset string

Timezone represented as a UTC offset, e.g., -04:00:00.

result.customFields object

Key/value pairs containing project-specific custom fields.

result.excludeFromExport boolean

Specifies whether this participant is excluded from data exports. Typically used for test or withdrawn participants.

Sample Response
{
    "totalAdded": 1,
    "totalUpdated": 2,
    "results": [
      {
        "actionTaken": "update",
        "result": {
          "id": "3a713a06-295d-4803-9602-776f09a1483b",
          "enrolled": true,
          "invitationStatus": "pending"
          ...
        }
      }
    ]
}               
    
See Participant Object for all participant fields.