SonaGetStudyList

Description¶

This API retrieves the list of studies in the system based on study type. Note that multipart studies will be listed once for each part of the study, since each part (internally) has a unique experiment_id. The multipart_number field will list which part of the study it is, and this is 1 for all non-multipart studies.

Some information is not included here, like the list of researchers, pre-requisites, and disqualifiers for a study, because these are stored separately. For a list of researchers for the study, use the SonaGetResearcherIDByExperimentID API function.

Input Parameters¶

Below are the following input parameters for use with the SonaGetStudyList API function.

Parameter	Description / Possible Values
`api_key`	Use API key generated for Sona admin user
`active`	Allowed values: `-1`: All `0`: Inactive studies only `1`: Active studies only
`approved`	Allowed values: `-1`: All `0`: Unapproved studies only `1`: Approved studies only
`web_flag`	Allowed values: `-1`: All `0`: Lab studies only `1`: Web studies only (internal online and external web)
`survey_flag`	Allowed values: `-1`: All `0`: All except online surveys `1`: Online surveys only

Output Parameters¶

Will return APIStudyInfo class and display data in an array.

Error Codes¶

Below are the possible error messages encountered and their respective descriptions.

Error Type	Error Code	Description
Authentication Failed	-1 through -7	Standard authentication errors
Error Code	Not supplied	Invalid `active` value. Use `-1`, `0`, or `1`.
Error Code	Not supplied	Invalid `approved` value. Use `-1`, `0`, or `1`.
Error Code	Not supplied	Invalid `web_flag` value. Use `-1`, `0`, or `1`.
Error Code	Not supplied	Invalid `survey_flag` value. Use `-1`, `0`, or `1`.
Error Code	Not supplied	No studies matched the supplied filters.

Sample Input¶

Request URL

https://myschool.sona-systems.com/services/SonaAPI.svc/SonaGetStudyList?api_key=YOUR_API_KEY&active=-1&approved=-1&web_flag=-1&survey_flag=-1

URL components

Component	Value
Scheme	`https`
Host	`myschool.sona-systems.com`
Service path	`/services/SonaAPI.svc`
Function	`SonaGetStudyList`

Query parameters

api_key = YOUR_API_KEY
active = -1
approved = -1
web_flag = -1
survey_flag = -1

Sample Output¶

<SonaGetStudyListResponse
  xmlns="https://www.sona-systems.com/"
  xmlns:a="http://schemas.datacontract.org/2004/07/emsdotnet.sonasystems"
  xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <SonaGetStudyListResult>
    <a:Errors i:nil="true" />
    <a:Result>
      <a:APIStudyInfo>
        <a:active>1</a:active>
        <a:age_maximum>200</a:age_maximum>
        <a:age_minimum>0</a:age_minimum>
        <a:auto_credit_enable>0</a:auto_credit_enable>
        <a:cancel_limit>24</a:cancel_limit>
        <a:course_restrictions />
        <a:creation_date>2019-10-28T12:22:26</a:creation_date>
        <a:credits>1.00</a:credits>
        <a:double_signup_flag>0</a:double_signup_flag>
        <a:duration>30</a:duration>
        <a:exp_pay_managed>0</a:exp_pay_managed>
        <a:exp_signup_email>0</a:exp_signup_email>
        <a:experiment_id>432</a:experiment_id>
        <a:experiment_url />
        <a:experimenter_timeslot>0</a:experimenter_timeslot>
        <a:has_multipart>0</a:has_multipart>
        <a:has_prereqs>0</a:has_prereqs>
        <a:has_rests>0</a:has_rests>
        <a:irb_code>abc123</a:irb_code>
        <a:irb_expiration_date>2023-11-29T00:00:00</a:irb_expiration_date>
        <a:is_neg_req>0</a:is_neg_req>
        <a:last_activity>2019-10-28T12:22:26</a:last_activity>
        <a:last_timeslot>2021-09-30T09:00:00</a:last_timeslot>
        <a:long_desc />
        <a:multipart_exact>0</a:multipart_exact>
        <a:multipart_max_days>0</a:multipart_max_days>
        <a:multipart_min_days>0</a:multipart_min_days>
        <a:multipart_number>1</a:multipart_number>
        <a:neg_req_any>1</a:neg_req_any>
        <a:parent_experiment_id>0</a:parent_experiment_id>
        <a:payment />
        <a:payment_numeric>0.00</a:payment_numeric>
        <a:pi_id>9541</a:pi_id>
        <a:preparation />
        <a:prereq_any>0</a:prereq_any>
        <a:previously_approved>1</a:previously_approved>
        <a:private_comments />
        <a:restrictions>None</a:restrictions>
        <a:short_desc />
        <a:show_participants>0</a:show_participants>
        <a:signup_limit>24</a:signup_limit>
        <a:signup_password />
        <a:study_alternative>0</a:study_alternative>
        <a:study_name>Online Internal Study 1</a:study_name>
        <a:survey_anon_flag>0</a:survey_anon_flag>
        <a:survey_flag>1</a:survey_flag>
        <a:total_credits>1.00</a:total_credits>
        <a:total_parts>1</a:total_parts>
        <a:total_payment />
        <a:total_payment_numeric>0.00</a:total_payment_numeric>
        <a:type>C</a:type>
        <a:usage_limit>200</a:usage_limit>
        <a:valid>1</a:valid>
        <a:web_flag>1</a:web_flag>
      </a:APIStudyInfo>
    </a:Result>
  </SonaGetStudyListResult>
</SonaGetStudyListResponse>