Survey Results API

The survey results API allows you to get information about what survey tasks have been assigned to your participants, and to assign new tasks.

Contents

Survey Result Object
Query Survey Results
Delete Survey Result

Survey Result Object

The basic survey result object is used in several of the API calls.

Tip
See Data Overview for important information about how survey tasks, results, and answers relate to one another.

id guid

Unique identifier for the result.

participantID guid

The internal, stable, unique ID for the participant associated with this result.

participantIdentifier string

Project-set, unique participant identifier for the participant associated with this result.

taskID string

The associated survey task.

surveyID guid

Identifier for the survey the result is associated with.

surveyName string

The name of the survey the result is associated with.

surveyVersion int

Version number of the survey that the participant completed.

surveyDisplayName string

The participant-visible name of the survey the result is associated with.

date date

When the result was recorded, in ISO8601 format

insertedDate date

When the result was added to the system, in ISO8601 format

schedule

Contains details about the schedule that triggered the survey, if applicable. Will be null if the survey was not triggered by a schedule.

Child Fields

schedule.id guid

Unique identifier for the schedule.

schedule.name string

Schedule name.

schedule.category string

User-assigned category for the schedule (optional).

schedule.interval integer

How often the survey is delivered, based on the interval type. For example, if intervalType is Weeks and interval is 4, it means the survey repeats every 4 weeks. Will be null if the schedule does not repeat.

schedule.intervalType string

Units for interval. May be days, weeks, months, or years.

userType string

Type of user that created the survey result. Can be one of: Participant, Coordinator, ServiceAccount (for automated submissions).

    Sample Survey Result Data
    
  

    {
  "id": "b187773c-7774-ef11-baf9-0affe8024cad",
  "participantID": "4f914cfe-4006-ea11-8184-9494f135fa19",
  "participantIdentifier": "PT-123",
  "taskID": "8b33fde0-7635-ef11-baf6-0affe8024cad",
  "surveyID": "cd20c1da-e3c5-ec11-aaba-0afb9334277d",
  "surveyVersion": 4,
  "surveyName": "Mood Survey",
  "surveyDisplayName": "Mood Survey",
  "date": "2024-09-16T18:01:37-04:00",
  "insertedDate": "2024-09-16T22:01:37.47Z",
  "userType": "Participant",
  "schedule": {
      "id": "a843df73-07c2-45a3-9808-98745fafc766",
      "name": "Weekly",
      "category": "Phase 1",
      "interval": 1,
      "intervalType": "Week"
  }
}
  {
  "id": "b187773c-7774-ef11-baf9-0affe8024cad",
  "participantID": "4f914cfe-4006-ea11-8184-9494f135fa19",
  "participantIdentifier": "PT-123",
  "taskID": "8b33fde0-7635-ef11-baf6-0affe8024cad",
  "surveyID": "cd20c1da-e3c5-ec11-aaba-0afb9334277d",
  "surveyVersion": 4,
  "surveyName": "Mood Survey",
  "surveyDisplayName": "Mood Survey",
  "date": "2024-09-16T18:01:37-04:00",
  "insertedDate": "2024-09-16T22:01:37.47Z",
  "userType": "Participant",
  "schedule": {
      "id": "a843df73-07c2-45a3-9808-98745fafc766",
      "name": "Weekly",
      "category": "Phase 1",
      "interval": 1,
      "intervalType": "Week"
  }
}

Query Survey Results

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

Query Parameters

participantID guid

Search for results for a participant based on the participant’s internal, stable, unique ID field.

participantIdentifier string

Search for results for a participant based on the project-set, unique participant identifier.

surveyID

Search for results from a particular survey, by identifier.

surveyName string

Search for results from a particular survey, by name. You can specify multiple names, separated by a comma (e.g. ?surveyName=Survey1,Survey2).

after date

Search for results recorded after a specific date, in ISO8601 format.

before date

Search for results recorded before a specific date, in ISO8601 format.

insertedAfter date

Search for results submitted to the system after a specific date, in ISO8601 format.

insertedBefore date

Search for results submitted to the system before a specific date, in ISO8601 format.

pageID guid

When the results span multiple pages, this specifies which page to retrieve. Null (the default) will retrieve the first page of results. For subsequent pages, use the ‘nextPageID’ from the response.

limit integer

Limits the number of results returned.

Response Fields

surveyResults collection

A list of the survey results.

Child Fields

surveyResults.id guid

Unique identifier for the result.

surveyResults.participantID guid

The internal, stable, unique ID for the participant associated with this result.

surveyResults.participantIdentifier string

Project-set, unique participant identifier for the participant associated with this result.

surveyResults.taskID string

The associated survey task.

surveyResults.surveyID guid

Identifier for the survey the result is associated with.

surveyResults.surveyName string

The name of the survey the result is associated with.

surveyResults.surveyVersion int

Version number of the survey that the participant completed.

surveyResults.surveyDisplayName string

The participant-visible name of the survey the result is associated with.

surveyResults.date date

When the result was recorded, in ISO8601 format

surveyResults.insertedDate date

When the result was added to the system, in ISO8601 format

surveyResults.schedule

Contains details about the schedule that triggered the survey, if applicable. Will be null if the survey was not triggered by a schedule.

Child Fields

surveyResults.schedule.id guid

Unique identifier for the schedule.

surveyResults.schedule.name string

Schedule name.

surveyResults.schedule.category string

User-assigned category for the schedule (optional).

surveyResults.schedule.interval integer

surveyResults.schedule.intervalType string

Units for interval. May be days, weeks, months, or years.

surveyResults.userType string

Type of user that created the survey result. Can be one of: Participant, Coordinator, ServiceAccount (for automated submissions).

nextPageID

Identifier that you can use to retrieve the next page of results.

    Sample Response
    
  

    {
  "nextPageID": "91cf690a-1433-401b-88e3-3f965e7b47de",
  "surveyResults": [
      {
          "id": "b838bd26-2255-4aaa-8d49-b21187f9f7ae",
          "surveyName": "Sleep Quality",
          "taskID": "8b33fde0-7635-ef11-baf6-0affe8024cad",
          ..,.
      },
      {
        "id": "f716b2c5-980d-484f-a4b4-8663e9acc506",
          "surveyName": "Sleep Time",
          "taskID": "b2d9853f-515f-eb11-aaa4-0afb9334277d",
        ...
      }
  ]
}
  {
  "nextPageID": "91cf690a-1433-401b-88e3-3f965e7b47de",
  "surveyResults": [
      {
          "id": "b838bd26-2255-4aaa-8d49-b21187f9f7ae",
          "surveyName": "Sleep Quality",
          "taskID": "8b33fde0-7635-ef11-baf6-0affe8024cad",
          ..,.
      },
      {
        "id": "f716b2c5-980d-484f-a4b4-8663e9acc506",
          "surveyName": "Sleep Time",
          "taskID": "b2d9853f-515f-eb11-aaa4-0afb9334277d",
        ...
      }
  ]
}

See Survey Result Object for all task fields.

Delete Survey Result

DELETE /api/v1/administration/projects/:projectId/surveyResults/:surveyResultId

Deletes a survey result. This feature is only available for surveys with “Results Can Be Deleted” enabled. This option can be enabled from the Settings pane in MyDataHelps’s Survey Editor.

Warning
This operation CANNOT be undone.