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
Query Participants
Get Participant
Add/Update Participant
Get Participant Segments
Bulk Add/Update Participants
Delete Participant
Withdraw Participant

Participant Object

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

Tip
See Data Overview for important information on the differences between the various types of participant identifiers.

id guid

Internal, stable, unique ID for this participant.

enrolled boolean

Whether the participant has completed enrollment.

enrollmentDate date

Date when the participant completed enrollment, in ISO8601 format.

withdrawDate date

If a participant has withdrawn from the project, this indicates the date they withdrew, in ISO8601 format.

insertedDate date

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

invitationStatus string

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

participantIdentifier string

Project-set, unique participant identifier.

secondaryIdentifier string

(DEPRECATED) An alias for a custom field named SecondaryIdentifier, if one exists. See deprecation notice.

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.

Child Fields

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. See Excluding and Removing Participants for more information.

institutionCode string

Specifies which institution a participant is assigned to. Will be blank if the participant is not assigned to an institution.

addedToSegmentDate date

Date when the participant was added to the specified segment, in ISO8601 format. Will only be present when the segmentId query parameter is provided.

    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",
  "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,
  "institutionCode": "County"
}
  {
  "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",
  "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,
  "institutionCode": "County"
}

Query Participants

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

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.

customField string

You can query by a custom field using a query parameter named customField.FIELDNAME. For example, /participants?customfield.StateOfResidence=AR. You may have multiple custom field query parameters.

demographicField string

You can query by select demographic fields (Email, FirstName, LastName, DOB, MobilePhone, and Email) using a query parameter named demographicField.FIELDNAME. For example, /participants?demographicField.LastName=Smith. You may have multiple custom field query parameters.

sortBy string

Specifies how participants will be sorted. Possible values are: CustomField.FIELD_NAME, DemographicField.DEMOGRAPHIC_NAME, ParticipantIdentifier, SecondaryIdentifier, InvitationStatus, InsertedDate (default), and EnrollmentDate

sortAscending boolean

Specify true to sort in ascending order, false in descending order.

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. Default 20.

Response Fields

totalParticipants integer

The total number of participants in the query.

participants collection

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

Child Fields

participants.id guid

Internal, stable, unique ID 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.withdrawDate date

If a participant has withdrawn from the project, this indicates the date they withdrew, in ISO8601 format.

participants.insertedDate date

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

participants.invitationStatus string

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

participants.participantIdentifier string

Project-set, unique participant identifier.

participants.secondaryIdentifier string

(DEPRECATED) An alias for a custom field named SecondaryIdentifier, if one exists. See deprecation notice.

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.

Child Fields

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. See Excluding and Removing Participants for more information.

participants.institutionCode string

Specifies which institution a participant is assigned to. Will be blank if the participant is not assigned to an institution.

participants.addedToSegmentDate date

Date when the participant was added to the specified segment, in ISO8601 format. Will only be present when the segmentId query parameter is provided.

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",
      ...
    },
    ...
  ]
}
  {
  "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 internal ID.

Response Fields

id guid

Internal, stable, unique ID for this participant.

enrolled boolean

Whether the participant has completed enrollment.

enrollmentDate date

Date when the participant completed enrollment, in ISO8601 format.

withdrawDate date

If a participant has withdrawn from the project, this indicates the date they withdrew, in ISO8601 format.

insertedDate date

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

invitationStatus string

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

participantIdentifier string

Project-set, unique participant identifier.

secondaryIdentifier string

(DEPRECATED) An alias for a custom field named SecondaryIdentifier, if one exists. See deprecation notice.

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.

Child Fields

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. See Excluding and Removing Participants for more information.

institutionCode string

Specifies which institution a participant is assigned to. Will be blank if the participant is not assigned to an institution.

addedToSegmentDate date

Date when the participant was added to the specified segment, in ISO8601 format. Will only be present when the segmentId query parameter is provided.

    Sample Response
    
  

    {
  "id": "3a713a06-295d-4803-9602-776f09a1483b",
  "enrolled": true,
  "invitationStatus": "approved",
  ...
}
  {
  "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.

Note
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.

invitationStatus string

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

participantIdentifier string

Project-set, unique participant identifier.

secondaryIdentifier string

(DEPRECATED) An alias for a custom field named SecondaryIdentifier, if one exists. See deprecation notice.

demographics object

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

Child Fields

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. See Excluding and Removing Participants for more information.

institutionCode string

Specifies which institution a participant is assigned to. Will be blank if the participant is not assigned to an institution.

addedToSegmentDate date

Date when the participant was added to the specified segment, in ISO8601 format. Will only be present when the segmentId query parameter is provided.

Response Fields

actionTaken string

Indicates what action was taken on the participant: add, update, delete, or none.

result object

The participant record.

Child Fields

result.id guid

Internal, stable, unique ID 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.withdrawDate date

If a participant has withdrawn from the project, this indicates the date they withdrew, in ISO8601 format.

result.insertedDate date

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

result.invitationStatus string

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

result.participantIdentifier string

Project-set, unique participant identifier.

result.secondaryIdentifier string

(DEPRECATED) An alias for a custom field named SecondaryIdentifier, if one exists. See deprecation notice.

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.

Child Fields

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. See Excluding and Removing Participants for more information.

result.institutionCode string

Specifies which institution a participant is assigned to. Will be blank if the participant is not assigned to an institution.

result.addedToSegmentDate date

Date when the participant was added to the specified segment, in ISO8601 format. Will only be present when the segmentId query parameter is provided.

    Sample Body Parameters
    
  

    {
      "demographics": {
          "email": "someone@example.com",
          "name": "John Doe"
      },
      "customFields": {
          "Smoker": 1
      }
}
  {
      "demographics": {
          "email": "someone@example.com",
          "name": "John Doe"
      },
      "customFields": {
          "Smoker": 1
      }
}

    Sample Response
    
  

    {
    "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"
      ...
    }
}

See Participant Object for all participant fields.

Get Participant Segments

GET /api/v1/administration/projects/:projectId/participants/:participantID/segments

Response Fields

segments collection

A list of segments the participant belongs to.

Child Fields

segments.segmentID guid

Unique internal identifier for the segment.

segments.segmentName string

The segment name.

segments.addDate date

The date the participant was added to the segment, in ISO8601 format.

    Sample Response
    
  

    [
    {
        "segmentID": "f4828980-3a25-46c7-8d54-ea6bfc4fa970",
        "segmentName": "Under 35",
        "addDate": "2022-11-10T02:20:05.44Z"
    },
    {
        "segmentID": "08936f17-0327-429b-bb2c-5c79180238cd",
        "segmentName": "Recently Enrolled",
        "addDate": "2022-11-10T02:20:05.44Z"
    }    
]
  [
    {
        "segmentID": "f4828980-3a25-46c7-8d54-ea6bfc4fa970",
        "segmentName": "Under 35",
        "addDate": "2022-11-10T02:20:05.44Z"
    },
    {
        "segmentID": "08936f17-0327-429b-bb2c-5c79180238cd",
        "segmentName": "Recently Enrolled",
        "addDate": "2022-11-10T02:20:05.44Z"
    }    
]

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 collection

List of participant data.

Child Fields

participants.invitationStatus string

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

participants.participantIdentifier string

Project-set, unique participant identifier.

participants.secondaryIdentifier string

(DEPRECATED) An alias for a custom field named SecondaryIdentifier, if one exists. See deprecation notice.

participants.demographics object

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

Child Fields

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. See Excluding and Removing Participants for more information.

participants.institutionCode string

Specifies which institution a participant is assigned to. Will be blank if the participant is not assigned to an institution.

participants.addedToSegmentDate date

Date when the participant was added to the specified segment, in ISO8601 format. Will only be present when the segmentId query parameter is provided.

sendDefaultInvitationNotifications boolean

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

Response Fields

totalAdded number

The number of participants added.

totalUpdated number

The number of participants updated.

results collection

A list of the newly added or updated participant records.

Child Fields

results.actionTaken string

Indicates what action was taken on the participant: add, update, delete, or none.

results.result object

The participant record.

Child Fields

results.result.id guid

Internal, stable, unique ID 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.withdrawDate date

If a participant has withdrawn from the project, this indicates the date they withdrew, in ISO8601 format.

results.result.insertedDate date

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

results.result.invitationStatus string

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

results.result.participantIdentifier string

Project-set, unique participant identifier.

results.result.secondaryIdentifier string

(DEPRECATED) An alias for a custom field named SecondaryIdentifier, if one exists. See deprecation notice.

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.

Child Fields

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. See Excluding and Removing Participants for more information.

results.result.institutionCode string

Specifies which institution a participant is assigned to. Will be blank if the participant is not assigned to an institution.

results.result.addedToSegmentDate date

Date when the participant was added to the specified segment, in ISO8601 format. Will only be present when the segmentId query parameter is provided.

    Sample Body Parameters
    
  

    {
    "participants": [
        {
            "demographics": {
                "email": "someone@example.com",
                "name": "John Doe"
            },
            "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"
            },
            "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",
          ...
        },
      },
      ...
    ]
}
  {
    "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

Removes a participant completely from the project.

Warning
Removing a participant will delete all of their survey responses and remove their sensor data from your project. This cannot be undone. If in doubt about whether you wish to permanently remove a participant, you can instead exclude them from data exports using the excludeFromExport flag. See Excluding and Removing Participants for more information.

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 internal ID.

Response Fields

actionTaken string

Indicates what action was taken on the participant: add, update, delete, or none.

result object

The participant record.

Child Fields

result.id guid

Internal, stable, unique ID 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.withdrawDate date

If a participant has withdrawn from the project, this indicates the date they withdrew, in ISO8601 format.

result.insertedDate date

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

result.invitationStatus string

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

result.participantIdentifier string

Project-set, unique participant identifier.

result.secondaryIdentifier string

(DEPRECATED) An alias for a custom field named SecondaryIdentifier, if one exists. See deprecation notice.

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.

Child Fields

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. See Excluding and Removing Participants for more information.

result.institutionCode string

Specifies which institution a participant is assigned to. Will be blank if the participant is not assigned to an institution.

result.addedToSegmentDate date

Date when the participant was added to the specified segment, in ISO8601 format. Will only be present when the segmentId query parameter is provided.

    Sample Response
    
  

    {
    "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"
          ...
        }
      }
    ]
}

See Participant Object for all participant fields.

Withdraw Participant

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

Withdraws a participant from the project.

Warning
When a participant is withdrawn, they will no longer be able to view or interact with the project in MyDataHelps. This action cannot be undone. You will lose access to their EHR and sensor data, though previously exported data will continue to be available in the export explorer. See Participant Withdrawal for more information.

Response Fields

actionTaken string

Indicates what action was taken on the participant: add, update, delete, or none.

result object

The participant record.

Child Fields

result.id guid

Internal, stable, unique ID 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.withdrawDate date

If a participant has withdrawn from the project, this indicates the date they withdrew, in ISO8601 format.

result.insertedDate date

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

result.invitationStatus string

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

result.participantIdentifier string

Project-set, unique participant identifier.

result.secondaryIdentifier string

(DEPRECATED) An alias for a custom field named SecondaryIdentifier, if one exists. See deprecation notice.

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.

Child Fields

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. See Excluding and Removing Participants for more information.

result.institutionCode string

Specifies which institution a participant is assigned to. Will be blank if the participant is not assigned to an institution.

result.addedToSegmentDate date

Date when the participant was added to the specified segment, in ISO8601 format. Will only be present when the segmentId query parameter is provided.

    Sample Response
    
  

    {
    "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"
      ...
    }
}

See Participant Object for all participant fields.