Sona API Documentation

Sona API documentation

The Application Programming Interface (API) for the Experiment Management System is a tool for advanced users to communicate directly with the system via a program or script they have written. Typically, this would be used to query specific information from the database for processing outside the system, or to do batch processing of updates.

The benefit of the API is that this can be done without human interaction. Without the API, the process of getting data from the system would involve logging into the system and going to the relevant page, downloading the data in CSV format, and parsing that. The login process is difficult to automate, so this approach does not work well for repetitive or scheduled tasks.

With the API, you can write your own script to connect directly to the system and query this information. One usage scenario would be if you want to display on a monitor in the main offices a list of all studies running that day. Using the API, you can write a program to query this information and then send it for display on the monitor. Another scenario would be if you want to have a daily or weekly batch process to query timeslot usage and update usage limits based on that information.

Intended Audience¶

It is important to understand that the API is intended for advanced users only, and requires a certain amount of programming knowledge. If terms like XML, SOAP, and HTTP are unfamiliar to you, then the API is not for you. If the API is too complicated, your best option would be to ask your IT department to write the code for you. Unfortunately, we do not have the resources to provide any training in technical concepts.

About This Documentation¶

This documentation covers the Application Programming Interface (API) for the Experiment Management System. API features will be released outside of the normal version schedule for our main software, so this document will be updated on a routine basis as new API functions are added.

Obtaining Technical Support¶

We can provide technical support to advise on the best API functions to use to solve your problem, and also to troubleshoot a problem in the API itself. We are not equipped to debug your code or solve programming problems.

Release Schedule¶

As releasing new API features does not change the end-user interface or functionality, then we plan to release new API features on a more frequent basis. Because of this, the API will not have a version number. This documentation will be updated on a regular basis to reflect any updates in the API.

Improvements and Suggestions¶

Because adding new features to the API does not impact the end-user interface, we are very open to adding new features to the API, especially if they provide a generic function that all customers can benefit from. Please feel free to contact us with any suggestions or questions.

Back to contents

Getting started

Follow this sequence to prepare an administrator API request. For external-study completion, use WebstudyCredit and the study's generated completion URL instead.

Quick start¶

Locate your API service. Start with API Access and URL and replace the example tenant name with your own Sona site name.
Generate an API key. Follow Authentication to create a key for an administrator account, then pass it as api_key=YOUR_API_KEY.
Identify your client. Add the required User-Agent header described in Request Requirements.
Choose a request method. Use HTTPS GET, JSON HTTP POST, or SOAP over HTTPS.
Adapt an example. Select a function from the API function reference and use the common programming-language examples as a starting point for your client.

Before using the integration¶

Keep API keys out of source code and logs, and review the security guidance.
Review performance and acceptable-use guidance before automating repeated requests.

Back to contents

API Access and URL

The API is accessed at the same address as your Sona site. If your Sona site’s URL is https://myschool.sona-systems.com then the API is located at https://myschool.sona-systems.com/services/SonaAPI.svc

Use HTTPS GET with parameters in the URL, JSON HTTP POST to the function URL, or SOAP over HTTPS at the /ws endpoint. See the programming-language examples for JSON POST and SOAP guidance for XML requests.

WSDL¶

If you go to that URL listed above (changing the “myschool” to your own site of course), you will find a link to the WSDL (Web Services Description Language) data for all functions within the API. Note that the WSDL may point to www.sona-systems.com so you may need to modify this to your site’s own URL.

You can find a direct link to the WSDL for your site at https://myschool.sona-systems.com/services/SonaAPI.svc?singleWsdl (change “myschool” to your site’s URL).

Back to contents

Authentication

Administrator API functions require a valid api_key. Include it in the query string for HTTP GET requests or the request body for JSON POST and SOAP requests.

WebstudyCredit uses the study's credit_token instead. It does not require an administrator API key.

API keys are user-specific and can be generated as follows:

Navigate to the Users | Add/Edit/Search section on your main site.

Find the user for whom you want to generate an API key.

Click on the "Set API Key" button next to the user's information.

On the "Set API Key" page, click "Set API Key" to generate a new key for that user.

Each administrator can have their own API key for access control and usage tracking.

Authentication Errors¶

Listed below are the different authentication error codes along with their description.

Error Code	Description
0	unspecified error
-1	bad username/password*
-2	bad user type (not an admin)
-3	access not allowed (account disabled)
-4	user not found
-5	access prevented due to password account lockout
-6	reach API key limit
-7	bad API key

* Username/password access has been deprecated and removed.

These error codes apply only if the API key authentication fails. If it works OK, then the return will merely be the typical return value from the API call (and unrelated to authentication).

Username and Password API Authentication Removal¶

To enhance the security of the Sona platform and better support users accessing Sona via Single Sign-On (SSO), username and password authentication for API access was deprecated and has now been removed.

Use an administrator API key for administrator API functions. For WebstudyCredit, use the study's generated completion URL and credit_token.

Back to contents

Request Requirements

Include a User-Agent header on every API request. Sona requires this header, and requests without it may be blocked by the firewall. Choose a value that identifies your integration. For example:

GET /services/SonaAPI.svc/SonaGetPersonInfoByPersonID?api_key=YOUR_API_KEY&person_id=1234 HTTP/1.1
Host: myschool.sona-systems.com
User-Agent: myCustomClient/202309011456

Downloading documentation files¶

The documentation website, its Markdown files, and the OpenAPI specification can also be downloaded by scripts and AI tools. These downloads are public and do not require an API key.

When downloading documentation programmatically, use a descriptive User-Agent, such as MyIntegration/1.0. Some HTTP libraries' default User-Agent values may be blocked by the documentation host with HTTP 403. This is separate from the requirements for calling the API described above.

For example, use Python's standard library to download the OpenAPI specification:

from urllib.request import Request, urlopen

url = (
    "https://www.sona-systems.com/api-documentation/"
    "openapi/sona-api.openapi.yaml"
)
request = Request(url, headers={"User-Agent": "MyIntegration/1.0"})
with urlopen(request, timeout=30) as response:
    openapi_yaml = response.read().decode("utf-8")

If your tool cannot set this header, download the files with a client that can and provide them to the tool locally.

Back to contents

Accessing the API using HTTP GET

One method to access the API, particularly if you are just querying data (as opposed to uploading a set of data), is to request a URL with the function name and necessary input parameters, and the system will then return an XML-formatted document with the result. This is an easy way to make most programs use the API, since it involves just loading a URL.

Back to contents

Accessing the API using SOAP

The other method to access the API is through a SOAP (Simple Object Access Protocol) call, which is an XML-formatted request that is sent as a POST over HTTPS. This works well (and is sometimes the only option) if you are using an API function that requires sending a large amount of data, since that’s not suitable for an HTTPS GET call.

Making an HTTP POST Request¶

Listed below is a sample HTTPS POST request to the API for the SonaGetPersonInfoByUserID function, assuming your site name is yoursite.sona-systems.com.

Request headers¶

POST /services/SonaAPI.svc/ws HTTP/1.1
Content-Type: application/soap+xml; charset=utf-8
Host: yoursite.sona-systems.com
User-Agent: myCustomClient/202309011456
Expect: 100-continue
Accept-Encoding: gzip, deflate
Connection: Keep-Alive

Request body¶

Update the site, API key, and user ID in this request body. MessageID is optional. Your HTTP client should calculate the Content-Length header.

<s:Envelope
  xmlns:s="http://www.w3.org/2003/05/soap-envelope"
  xmlns:a="http://www.w3.org/2005/08/addressing">
  <s:Header>
    <a:Action s:mustUnderstand="1">
      https://www.sona-systems.com/SonaAPI/SonaGetPersonInfoByUserID_Post
    </a:Action>
    <a:MessageID>urn:uuid:73e142a1-df57-4bfe-9caa-dc9ef790d50c</a:MessageID>
    <a:ReplyTo>
      <a:Address>http://www.w3.org/2005/08/addressing/anonymous</a:Address>
    </a:ReplyTo>
    <a:To s:mustUnderstand="1">
      https://yoursite.sona-systems.com/services/SonaAPI.svc/ws
    </a:To>
  </s:Header>
  <s:Body>
    <SonaGetPersonInfoByUserID_Post xmlns="https://www.sona-systems.com/">
      <api_key>your_api_key_here</api_key>
      <user_id>a_user</user_id>
    </SonaGetPersonInfoByUserID_Post>
  </s:Body>
</s:Envelope>

The main things to note here are to send the POST request to the URL but with /ws appended to the end, and to append _Post to the function call.

Back to contents

Request Examples for Common Programming Languages

The following examples send a JSON HTTP POST request to SonaActivateUser. They use cURL, Python, Node.js, C#/.NET, Java, and PHP.

This request enables sign-in for an existing user. Use a test account that you intend to activate. Replace the site name and API key before running an example. For XML SOAP requests, see Accessing the API using SOAP.

Request body¶

Save this JSON object in data.txt. Replace 1234 with the numeric ID of the user to activate.

{
  "api_key": "YOUR_API_KEY",
  "person_id": "1234"
}

CURL¶

curl -v -X POST --http1.1 -H "Content-Type: application/json; charset=utf-8" \
  --data-binary @data.txt -A "myCustomClient/202309011456" \
  https://yoursite.sona-systems.com/services/SonaAPI.svc/SonaActivateUser

Python¶

import requests

# Specify the file path and headers
file_path = 'data.txt'
headers = {
    'Content-Type': 'application/json; charset=utf-8',
    'User-Agent': 'myCustomClient/202309011456'
}

# Read the data from the file
with open(file_path, 'r') as file:
    data = file.read()

# Set the URL for the API endpoint
url = 'https://yoursite.sona-systems.com/services/SonaAPI.svc/SonaActivateUser'

# Send the POST request
response = requests.post(url, headers=headers, data=data)

# Output the response
print(response.status_code)
print(response.text)

Node.js¶

const fs = require('fs');
const axios = require('axios');

// Read the data from the file
const data = fs.readFileSync('data.txt', 'utf8');

// Set the headers
const headers = {
  'Content-Type': 'application/json; charset=utf-8',
  'User-Agent': 'myCustomClient/202309011456'
};

// Set the URL for the API endpoint
const url = 'https://yoursite.sona-systems.com/services/SonaAPI.svc/SonaActivateUser';

// Send the POST request
axios.post(url, data, { headers })
  .then(response => {
    console.log(response.status);
    console.log(response.data);
  })
  .catch(error => {
    console.error(error);
  });

C#/.NET¶

using System;
using System.IO;
using System.Net.Http;
using System.Threading.Tasks;

class Program
{
  static async Task Main(string[] args)
  {
    string url = "https://yoursite.sona-systems.com/services/SonaAPI.svc/SonaActivateUser";
    string filePath = "data.txt";

    using HttpClient client = new HttpClient();
    client.DefaultRequestHeaders.Add("User-Agent", "myCustomClient/202309011456");

    string data = await File.ReadAllTextAsync(filePath);
    HttpContent content = new StringContent(data, System.Text.Encoding.UTF8, "application/json");

    HttpResponseMessage response = await client.PostAsync(url, content);
    string responseBody = await response.Content.ReadAsStringAsync();

    Console.WriteLine(response.StatusCode);
    Console.WriteLine(responseBody);
  }
}

Java¶

import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Paths;

import okhttp3.*;

public class PostRequestExample {
  public static void main(String[] args) throws IOException {
    String url = "https://yoursite.sona-systems.com/services/SonaAPI.svc/SonaActivateUser";
    String filePath = "data.txt";

    OkHttpClient client = new OkHttpClient();

    String data = new String(Files.readAllBytes(Paths.get(filePath)));
    RequestBody body = RequestBody.create(data, MediaType.get("application/json; charset=utf-8"));

    Request request = new Request.Builder()
      .url(url)
      .post(body)
      .header("User-Agent", "myCustomClient/202309011456")
      .build();

    try (Response response = client.newCall(request).execute()) {
      System.out.println(response.code());
      System.out.println(response.body().string());
    }
  }
}

PHP¶

<?php

$url = 'https://yoursite.sona-systems.com/services/SonaAPI.svc/SonaActivateUser';
$file_path = 'data.txt';

$data = file_get_contents($file_path);

$options = [
  'http' => [
    'header' => [
      "Content-Type: application/json; charset=utf-8",
      "User-Agent: myCustomClient/202309011456"
    ],
    'method'  => 'POST',
    'content' => $data,
  ],
];

$context = stream_context_create($options);
$response = file_get_contents($url, false, $context);

if ($response === FALSE) {
  die('Error');
}

echo $http_response_header[0] . "\n";
echo $response;
?>

Back to contents

Guides

Operational guidance for building a responsible Sona API integration.

Back to contents

Performance Considerations and Acceptable Use

The system enforces a rate limit of 600 API requests per 5-minute interval. Design your programs to use the API efficiently, minimizing unnecessary calls. If abusive patterns are detected, additional restrictions may be applied.

One example for how to use the API efficiently would be to cache or store locally certain data if it does not change often, instead of calling the API for the same data every time. Also, instead of “polling” the API every few minutes for data, call it only when data is needed (e.g., requested by the user).

Note that calls to the API are to the same site as your main site is running on, so excessive calls can slow down the main site for all your users. We reserve the right to terminate access to the API if it is excessive or adversely affecting site performance.

Back to contents

Testing Tools

There are several tools out there for testing your API calls to determine if they work. One tool available from Microsoft is the WCF Test Client, which is part of the Visual Studio package. More information on the WCF Test Client can be found here: http://msdn.microsoft.com/en-us/library/bb552364.aspx

Back to contents

Security Concerns

When using the URL GET method for API calls, the API key is included as part of the URL. Please be aware that this approach has some security considerations:

Proxy servers within your network may log or cache these calls, potentially exposing the API key.

Our servers maintain logs of parameters used in GET requests as part of standard website logging practices.

For enhanced security, you may prefer to use SOAP calls to access the API. With SOAP, the API key is included in the request body rather than the URL, reducing the likelihood of it being logged or cached by intermediate systems.

Always treat your API key as sensitive information and avoid sharing it unnecessarily. If you suspect your API key has been compromised, generate a new one immediately through the user management interface.

Back to contents

API reference

Browse all API functions and data classes, or open the generated OpenAPI reference.

Back to contents

API functions

SonaConvertUserToSSOByPersonID: This API converts a non-SSO user to a SSO user using the numeric person_id of the user as the identifier.
SonaConvertUserToSSOByUserID: This API converts a non-SSO user to an SSO user using the user_id of the user as the identifier.
SonaGetCoursesByPersonID: This API retrieves a list of all courses the participant specified by person_id is in.
SonaSetCoursesByPersonID: This API allows overwriting or removing the course assignments for a participant specified by person_id.
SonaGetPersonInfoByName: Returns users matching the supplied first name, last name, or both.
SonaCreateTimeslot: This function allows creation of a timeslot programmatically via API. It returns the new timeslot’s ID and logs the event for auditing or indicates if creation wasn’t allowed.
SonaSignUpUserToATimeslot: Signs up a participant for a specified timeslot.
SonaGetSignUpsForTimeslot: Returns signup records for a specified timeslot.
SonaGetSignupsByDateRange: This API retrieves the list of signup records, within a given date range.
SonaGetStudyScheduleList: This API retrieves the list of studies within a given date range. It basically mimics the Study Schedule Report as found in the Generate Reports page of the main site.
SonaGetStudyList: Lists studies that match the specified study-type filters.
SonaGetResearcherIDByExperimentID: This API call retrieves the list of researchers (by person_id) for a study, based on the study’s experiment_id.
SonaGetPrescreenSurveyDataByPersonID: This API call retrieves the list of prescreen or survey responses of a particular participant.
SonaGetPrescreenSurveyDataByDateRange: This API retrieves the list of prescreen or survey responses, for multiple participants, based on a given date range.
SonaGetPrescreenDataByExperimentID: Returns prescreen responses for participants with credit records for the specified study.
SonaGetPrescreenDataByTimeslotID: Returns prescreen responses for participants signed up for the specified timeslot.
SonaGrantCreditBySignupID: Updates the credit status and comments for one signup.
SonaFixStudyCreditAssignmentMismatch: Corrects credit assignments that do not match study course restrictions.
SonaGetStudyCreditAssignmentMismatch: Returns credit assignments where the assigned course is not included in the study's course restrictions.
SonaGetPersonInfoByPersonID: Returns user information for the supplied numeric person ID.
SonaGetPersonInfoByStudentID: Returns one participant matching the supplied student ID number.
SonaGetPersonInfoByUserID: Returns user information for the supplied user ID.
SonaGetPersonInfoByIDCode: Returns user information for the supplied anonymous ID code.
SonaGetCreditBySignupID: This function will provide all information about a particular study signup, with the specified signup_id.
SonaGetCreditsByPersonID: This function will provide information on each credit and signup for the specified participant, including non-study credit grants.
SonaGetCreditsByTimeslotID: This function will provide information on every sign up for the specified timeslot.
SonaGetCreditsByDateRange: This function will provide information on each credit within a given date range.
SonaGetPersonListByClassID: This API retrieves a list of all participants in the specified course.
SonaGetTimeslotsByExperimentID: This API retrieves a list of timeslots for a particular study.
SonaGetTimeslotsByExperimentIDDateRange: This API retrieves the list of timeslots, for a particular study, within a given date range.
SonaGetParticipantStats: This API retrieves basic credit and usage information (summarized) for a particular course, or all courses in the system.
SonaGetStudyStats: This API retrieves basic usage information for a particular study. It’s similar to the Timeslot Usage Summary in the web interface.
SonaGetStudyStatsByDateRange: This API retrieves basic usage information for a particular study, within a given date range. It’s similar to the Timeslot Usage Summary in the web interface.
SonaGetInstructorByClassID: This API retrieves the user information for the Instructors assigned to a particular course. A course may have up to two instructors.
SonaGetPersonListByLoginDate: Returns users filtered by user type, login permission, and last recorded login date.
SonaGetPersonListByCreationDate: Returns users created on or after the specified date, including their user type and login permission.
SonaGetStudyInfoByExperimentID: This function returns all information pertaining to a study based on its experiment_id.
SonaGetStudyListByResearcher: This function returns a detailed list of studies managed by a particular researcher.
SonaGetStudyListByPI: This function returns a detailed list of studies managed by a particular PI.
SonaActivateUser: Activates an existing user account.
SonaCreateUser: This function allows for the creation of a new user in the system by providing necessary details such as name, user ID, and person type.
SonaDeactivateUser: Deactivates an existing user account.
SonaApproveUser: Approves a participant account.
SonaMergeUser: Merges two user accounts and transfers associated records and roles to the retained account.
SonaSetUserTimeslotUsageLimit: Sets the Study Time Usage Limit, in participant-hours, for an existing user.
SonaSetUserAdminComments: Appends, replaces, or deletes a user's administrator comments.
SonaAddUserRole: Adds a researcher, principal investigator, instructor, or participant role to an existing user.
SonaRemoveUserRole: Removes a researcher, principal investigator, instructor, or participant role from an existing user.
WebstudyCredit: Grants credit or records participation when a participant completes an external online study.

Back to contents

SonaConvertUserToSSOByPersonID

Description¶

This API converts a non-SSO user to a SSO user using the numeric person_id of the user as the identifier.

Input Parameters¶

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

Parameter	Description / Possible Values
`api_key`	Use API key generated for Sona admin user
`person_id`	The `person_id` to convert to SSO (e.g. 1234)
`sso_id`	The SSO id of the user (e.g. someuser@myschool.edu)

Output Parameters¶

Will return True if converted else errors.

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	-8	User not found
Error Code	-9	`sso_id` already exists
Error Code	-10	Invalid SSO ID
Error Code	-11	Invalid `person_id`

Sample Input¶

Request URL

https://myschool.sona-systems.com/services/SonaAPI.svc/SonaConvertUserToSSOByPersonID?api_key=YOUR_API_KEY&person_id=1234&sso_id=[email protected]

URL components

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

Query parameters

api_key = YOUR_API_KEY
person_id = 1234
sso_id = [email protected]

Sample Output¶

<SonaConvertUserToSSOByPersonIDResponse
  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">
  <SonaConvertUserToSSOByPersonIDResult>
    <a:Errors i:nil="true" />
    <a:Result>true</a:Result>
  </SonaConvertUserToSSOByPersonIDResult>
</SonaConvertUserToSSOByPersonIDResponse>

Back to contents

SonaConvertUserToSSOByUserID

Description¶

This API converts a non-SSO user to an SSO user using the user_id of the user as the identifier.

Input Parameters¶

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

Parameter	Description / Possible Values
`api_key`	Use API key generated for Sona admin user
`user_id`	The user ID to convert to SSO (e.g. someuser)
`sso_id`	The SSO ID of the user (e.g. someuser @myschool.edu)

Output Parameters¶

Will return True if converted else errors.

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	-8	`sso_id` already exists
Error Code	-9	Invalid SSO ID
Error Code	-10	`user_id` does not exist
Error Code	-11	Invalid `user_id`

Sample Input¶

Request URL

https://myschool.sona-systems.com/services/SonaAPI.svc/SonaConvertUserToSSOByUserID?api_key=YOUR_API_KEY&user_id=auser&sso_id=[email protected]

URL components

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

Query parameters

api_key = YOUR_API_KEY
user_id = auser
sso_id = [email protected]

Sample Output¶

<SonaConvertUserToSSOByUserIDResponse
  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">
  <SonaConvertUserToSSOByUserIDResult>
    <a:Errors i:nil="true" />
    <a:Result>true</a:Result>
  </SonaConvertUserToSSOByUserIDResult>
</SonaConvertUserToSSOByUserIDResponse>

Back to contents

SonaGetCoursesByPersonID

Description¶

This API retrieves a list of all courses the participant specified by person_id is in.

Input Parameters¶

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

Parameter	Description / Possible Values
`api_key`	Use API key generated for Sona admin user
`person_id`	The `person_id` to retrieve courses of

Output Parameters¶

Will return APICourse classes 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	-8	User is not a participant.
Error Code	-9	Invalid person ID

Sample Input¶

Request URL

https://myschool.sona-systems.com/services/SonaAPI.svc/SonaGetCoursesByPersonID?api_key=YOUR_API_KEY&person_id=1234

URL components

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

Query parameters

api_key = YOUR_API_KEY
person_id = 1234

Sample Output¶

<SonaGetCoursesByPersonIDResponse
  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">
  <SonaGetCoursesByPersonIDResult>
    <a:Errors i:nil="true" />
    <a:Result>
      <a:APICourse>
        <a:class_id>5</a:class_id>
        <a:class_name>My Class</a:class_name>
        <a:credits_required>30</a:credits_required>
        <a:instructor_id>9458</a:instructor_id>
        <a:instructor_id2>0</a:instructor_id2>
        <a:selectable>1</a:selectable>
      </a:APICourse>
    </a:Result>
  </SonaGetCoursesByPersonIDResult>
</SonaGetCoursesByPersonIDResponse>

Back to contents

SonaSetCoursesByPersonID

Description¶

This API allows overwriting or removing the course assignments for a participant specified by person_id.

Input Parameters¶

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

Parameter	Description / Possible Values
`api_key`	Use API key generated for Sona admin user
`person_id`	The `person_id` to set courses for
`class_ids`	Comma-separated list of course IDs to assign to the participant. E.g. `42,67,1337` Specify a single `class_id` of `0` to remove all course assignments for that participant.

Credit Assignment Note: If course credit assignment is enabled for your site, credits assigned to removed courses are handled as follows:

If you provide exactly one course, credits from removed courses are reassigned to that course. Any previously unassigned non-zero credits are also assigned to it.

If you provide more than one course, credits from removed courses will be unassigned.

Output Parameters¶

Will return True if course assignment was successful, or errors if unsuccessful.

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	-8	No courses chosen. You must choose at least one course.
Error Code	-10	`person_id` is invalid or does not identify a participant, or no valid course IDs were supplied.

Sample Input¶

Request URL

https://myschool.sona-systems.com/services/SonaAPI.svc/SonaSetCoursesByPersonID?api_key=YOUR_API_KEY&person_id=1234&class_ids=42,67,1337

URL components

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

Query parameters

api_key = YOUR_API_KEY
person_id = 1234
class_ids = 42,67,1337

Sample Output¶

<SonaSetCoursesByPersonIDResponse
  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">
  <SonaSetCoursesByPersonIDResult>
    <a:Errors i:nil="true" />
    <a:Result>true</a:Result>
  </SonaSetCoursesByPersonIDResult>
</SonaSetCoursesByPersonIDResponse>

Back to contents

SonaGetPersonInfoByName

Description¶

This API retrieves the person information for all users with specified name(s). At least one name parameter must be specified (first or last name), or both. When searching on only one name parameter, include the other parameter but pass a blank value, instead of omitting the parameter entirely. There may be more than one match. Search is case-insensitive.

Input Parameters¶

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

Parameter	Description / Possible Values
`api_key`	Use API key generated for Sona admin user
`first_name`	The first name search parameter (first and/or last name required, pass blank value if not being searched)
`last_name`	The last name search parameter (first and/or last name required, pass blank value if not being searched)

Output Parameters¶

Will return APIPerson 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	-8	No users found with supplied first name and/or last name
Error Code	-9	No `first_name` or `last_name` supplied

Sample Input¶

Request URL

https://myschool.sona-systems.com/services/SonaAPI.svc/SonaGetPersonInfoByName?api_key=YOUR_API_KEY&first_name=john&last_name=doe

URL components

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

Query parameters

api_key = YOUR_API_KEY
first_name = john
last_name = doe

Sample Output¶

<SonaGetPersonInfoByNameResponse
  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">
  <SonaGetPersonInfoByNameResult>
    <a:Errors i:nil="true" />
    <a:Result>
      <a:APIPerson>
        <a:admin_comments />
        <a:alt_email>[email protected]</a:alt_email>
        <a:anon_id_code>1337</a:anon_id_code>
        <a:approved>1</a:approved>
        <a:birthdate>0001-01-01T00:00:00</a:birthdate>
        <a:classes_needed>1</a:classes_needed>
        <a:creation_date>0001-01-01T00:00:00</a:creation_date>
        <a:credits_earned>0</a:credits_earned>
        <a:credits_needed>1.00</a:credits_needed>
        <a:daily_reminder>0</a:daily_reminder>
        <a:email_needed>0</a:email_needed>
        <a:first_name>test</a:first_name>
        <a:hipaa_ack_date>0001-01-01T00:00:00</a:hipaa_ack_date>
        <a:hipaa_ack_date_nonp>0001-01-01T00:00:00</a:hipaa_ack_date_nonp>
        <a:language_pref>EN</a:language_pref>
        <a:last_login>0001-01-01T00:00:00</a:last_login>
        <a:last_name>Test</a:last_name>
        <a:limit_date>0001-01-01T00:00:00</a:limit_date>
        <a:limit_type />
        <a:limited>0</a:limited>
        <a:login_allowed>1</a:login_allowed>
        <a:login_days>0</a:login_days>
        <a:login_sent_date>2012-10-08T04:05:24</a:login_sent_date>
        <a:noshow_count>0</a:noshow_count>
        <a:office />
        <a:password_change_needed>1</a:password_change_needed>
        <a:password_failed_count>0</a:password_failed_count>
        <a:person_id>9416</a:person_id>
        <a:person_type_a>0</a:person_type_a>
        <a:person_type_e>0</a:person_type_e>
        <a:person_type_i>0</a:person_type_i>
        <a:person_type_p>0</a:person_type_p>
        <a:person_type_pref>S</a:person_type_pref>
        <a:person_type_s>1</a:person_type_s>
        <a:phone>12444</a:phone>
        <a:pretest>0</a:pretest>
        <a:student_id_num>12333</a:student_id_num>
        <a:study_invitation>1</a:study_invitation>
        <a:usage_limit>0</a:usage_limit>
        <a:user_id>testme</a:user_id>
        <a:weekly_reminder>0</a:weekly_reminder>
      </a:APIPerson>
      <a:APIPerson>
        <a:admin_comments />
        <a:alt_email>[email protected]</a:alt_email>
        <a:anon_id_code>32290</a:anon_id_code>
        <a:approved>1</a:approved>
        <a:birthdate>0001-01-01T00:00:00</a:birthdate>
        <a:classes_needed>1</a:classes_needed>
        <a:creation_date>0001-01-01T00:00:00</a:creation_date>
        <a:credits_earned>0</a:credits_earned>
        <a:credits_needed>0</a:credits_needed>
        <a:daily_reminder>0</a:daily_reminder>
        <a:email_needed>0</a:email_needed>
        <a:first_name>Test</a:first_name>
        <a:hipaa_ack_date>0001-01-01T00:00:00</a:hipaa_ack_date>
        <a:hipaa_ack_date_nonp>0001-01-01T00:00:00</a:hipaa_ack_date_nonp>
        <a:language_pref>EN</a:language_pref>
        <a:last_login>0001-01-01T00:00:00</a:last_login>
        <a:last_name>Test</a:last_name>
        <a:limit_date>0001-01-01T00:00:00</a:limit_date>
        <a:limit_type />
        <a:limited>0</a:limited>
        <a:login_allowed>1</a:login_allowed>
        <a:login_days>0</a:login_days>
        <a:login_sent_date>2013-05-03T10:29:13</a:login_sent_date>
        <a:noshow_count>0</a:noshow_count>
        <a:office />
        <a:password_change_needed>1</a:password_change_needed>
        <a:password_failed_count>0</a:password_failed_count>
        <a:person_id>9435</a:person_id>
        <a:person_type_a>0</a:person_type_a>
        <a:person_type_e>0</a:person_type_e>
        <a:person_type_i>0</a:person_type_i>
        <a:person_type_p>0</a:person_type_p>
        <a:person_type_pref>S</a:person_type_pref>
        <a:person_type_s>1</a:person_type_s>
        <a:phone>301-111-1111</a:phone>
        <a:pretest>0</a:pretest>
        <a:student_id_num>111-23</a:student_id_num>
        <a:study_invitation>1</a:study_invitation>
        <a:usage_limit>0</a:usage_limit>
        <a:user_id>test3323</a:user_id>
        <a:weekly_reminder>0</a:weekly_reminder>
      </a:APIPerson>
    </a:Result>
  </SonaGetPersonInfoByNameResult>
</SonaGetPersonInfoByNameResponse>

Back to contents

SonaCreateTimeslot

Description¶

This function allows creation of a timeslot programmatically via API. It returns the new timeslot’s ID and logs the event for auditing or indicates if creation wasn’t allowed.

Input Parameters¶

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

Parameter	Description / Possible Values
`api_key`	Use API key generated for Sona admin user
`occur_date`	The date (YYYY-MM-DD format) when the timeslot is to occur. For online studies, this is the participation deadline. E.g. 1999-12-31
`start_time`	The start time (HH24:MI format) of the timeslot. E.g. 17:30
`num_students`	The total number of participants allowed for this timeslot
`experiment_id`	The numeric identifier of the study
`experimenter_id`	The numeric identifier of the researcher to assign to this timeslot. Optional – `experimenter_id` may be omitted. Applicable only if all three conditions are met: 1. The study is configured so that researchers are assigned at the timeslot level. 2. Multiple researcher support is enabled in System Settings. 3. The specified researcher is listed as one of the researchers for the study.
`resource_id`	The numeric identifier of the location, which is the pulldown list of locations that appears when adding a timeslot. Only applies to lab studies, and if Location Scheduling is enabled in System Settings. Optional – an empty string or omitting the `resource_id` is valid. `resource_id`, `videoconf_url`, or location must be specified for a lab study.
`videoconf_url`	The URL of the videoconference. Only applies to lab studies. Optional – either `resource_id`, `videoconf_url`, or location must be specified for a lab study.
`location`	The location of the lab study. This does not apply to online studies. Optional – either `resource_id`, `videoconf_url`, or location must be specified for a lab study.

Output Parameters¶

Will return the timeslot_id of the timeslot that was created.

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	-8	Invalid `start_time` or `occur_date`
Error Code	-9	Invalid number of participants
Error Code	-10	Invalid `experiment_id`
Error Code	-11	Invalid `resource_id`
Error Code	-12	Study not found
Error Code	-13	Timeslot add failed. Adding a timeslot with the number of participants specified would exceed the timeslot usage limits.
Error Code	-17	Slot not valid You must enter a valid date/start time combination in proper format There are other timeslots scheduled in the same location during the time you have scheduled your timeslot You must specify a location The timeslot may not occur after the approval expiration date
Error Code	-18	The `experimenter_id` is not numeric, or the specified researcher is not assigned to the study.
Error Code	-19	Invalid location, and `videoconf_url` and `resource_id` not specified

Sample Input¶

Request URL

https://myschool.sona-systems.com/services/SonaAPI.svc/SonaCreateTimeslot?api_key=YOUR_API_KEY&occur_date=2012-06-26&start_time=17%3A30&location=Miller%20Hall&num_students=200&experiment_id=3141&experimenter_id=3117&resource_id=2718&videoconf_url=https%3A%2F%2Fwww.zoom.com%2F123

URL components

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

Query parameters

api_key = YOUR_API_KEY
occur_date = 2012-06-26
start_time = 17:30
location = Miller%20Hall
num_students = 200
experiment_id = 3141
experimenter_id = 3117
resource_id = 2718
videoconf_url = https%3A%2F%2Fwww.zoom.com%2F123

Sample Output¶

<SonaCreateTimeslotResponse
  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">
  <SonaCreateTimeslotResult>
    <a:Errors i:nil="true" />
    <a:Result>5678</a:Result>
  </SonaCreateTimeslotResult>
</SonaCreateTimeslotResponse>

Back to contents

This API function signs users up for a specific timeslot. The timeslot is specified as a timeslot_id. The user is specified using their person_id. Note: This function only works for lab studies and external web studies. It does not work for internal online survey studies.

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

Parameter	Description / Possible Values
`api_key`	Use API key generated for Sona admin user
`person_id`	The `person_id` of the person to sign up.
`timeslot_id`	The `timeslot_id` of the timeslot to sign the person up for.

Returns a single APISignup result for the new signup.

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	-8	Invalid or no `timeslot_id` supplied
Error Code	-11	Invalid or no `person_id` supplied
Error Code	9	No participant found
Error Code	10	No supported timeslot found
Error Code	11	The timeslot is full

Other sign-up restrictions may be returned as descriptive error messages without a numeric code.

Request URL

https://myschool.sona-systems.com/services/SonaAPI.svc/SonaSignUpUserToATimeslot?api_key=YOUR_API_KEY&person_id=11498&timeslot_id=75

URL components

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

Query parameters

api_key = YOUR_API_KEY
person_id = 11498
timeslot_id = 75

<SonaSignUpUserToATimeslotResponse
  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">
  <SonaSignUpUserToATimeslotResult>
    <a:Errors i:nil="true" />
    <a:Result>
      <a:anon_id_code>1234</a:anon_id_code>
      <a:credit_status>W</a:credit_status>
      <a:email>[email protected]</a:email>
      <a:first_name>Mike</a:first_name>
      <a:last_name>Lee</a:last_name>
      <a:link_click_date>0001-01-01T00:00:00</a:link_click_date>
      <a:occur_date>2019-08-14T16:00:00</a:occur_date>
      <a:phone>8509886</a:phone>
      <a:signup_date>2019-08-13T15:00:00</a:signup_date>
      <a:signup_id>258</a:signup_id>
      <a:student_id_num>09341404</a:student_id_num>
      <a:survey_code>222</a:survey_code>
      <a:user_id>mikel</a:user_id>
    </a:Result>
  </SonaSignUpUserToATimeslotResult>
</SonaSignUpUserToATimeslotResponse>

Back to contents

SonaGetSignUpsForTimeslot

Description¶

This API retrieves the list of signup records for a given timeslot. The timeslot is specified as a timeslot_id. In the system’s interface, when you click on a timeslot, you will see the timeslot_id in the URL in the browser address section.

Input Parameters¶

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

Parameter	Description / Possible Values
`api_key`	Use API key generated for Sona admin user
`timeslot_id`	The numeric reference of the timeslot from which to retrieve the records from.

Output Parameters¶

Will return APISignup 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	`timeslot_id` must be numeric
Error Code	Not supplied	either no records were found for `timeslot_id` or `timeslot_id` does not exist

Sample Input¶

Request URL

https://myschool.sona-systems.com/services/SonaAPI.svc/SonaGetSignUpsForTimeslot?api_key=YOUR_API_KEY&timeslot_id=75

URL components

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

Query parameters

api_key = YOUR_API_KEY
timeslot_id = 75

Sample Output¶

<SonaGetSignUpsForTimeslotResponse
  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">
  <SonaGetSignUpsForTimeslotResult>
    <a:Errors i:nil="true" />
    <a:Result>
      <a:APISignUp>
        <a:anon_id_code>1234</a:anon_id_code>
        <a:credit_status>G</a:credit_status>
        <a:email>[email protected]</a:email>
        <a:first_name>Mike</a:first_name>
        <a:last_name>Lee</a:last_name>
        <a:link_click_date>2019-08-14T16:00:00</a:link_click_date>
        <a:phone>8509886</a:phone>
        <a:signup_date>2019-08-13T15:00:00</a:signup_date>
        <a:signup_id>258</a:signup_id>
        <a:student_id_num>09341404</a:student_id_num>
        <a:survey_code>222</a:survey_code>
        <a:user_id>mikel</a:user_id>
      </a:APISignUp>
      <a:APISignUp>
        <a:anon_id_code>5678</a:anon_id_code>
        <a:credit_status>G</a:credit_status>
        <a:email>[email protected]</a:email>
        <a:first_name>Jesse</a:first_name>
        <a:last_name>James</a:last_name>
        <a:link_click_date>2019-08-14T16:00:00</a:link_click_date>
        <a:phone>8509887</a:phone>
        <a:signup_date>2019-08-13T15:00:00</a:signup_date>
        <a:signup_id>266</a:signup_id>
        <a:student_id_num>09341405</a:student_id_num>
        <a:survey_code>729</a:survey_code>
        <a:user_id>jessej</a:user_id>
      </a:APISignUp>
    </a:Result>
  </SonaGetSignUpsForTimeslotResult>
</SonaGetSignUpsForTimeslotResponse>

Back to contents

SonaGetSignupsByDateRange

Description¶

This API retrieves the list of signup records, within a given date range.

Input Parameters¶

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

Parameter	Description / Possible Values
`api_key`	Use API key generated for Sona admin user
`start_date`	The start date of the date range to include. Date must be formatted as: YYYY-MM-DD.
`end_date`	The end date of the date range to include. Date must be formatted as: YYYY-MM-DD.

Output Parameters¶

Will return APISignup 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	-8	Invalid end date
Error Code	-9	Start date is after end date
Error Code	-10	Invalid start date
Error Code	-11	No credit record found for selected date range

Sample Input¶

Request URL

https://myschool.sona-systems.com/services/SonaAPI.svc/SonaGetSignupsByDateRange?api_key=YOUR_API_KEY&start_date=2014-01-01&end_date=2014-12-31

URL components

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

Query parameters

api_key = YOUR_API_KEY
start_date = 2014-01-01
end_date = 2014-12-31

Sample Output¶

<SonaGetSignupsByDateRangeResponse
  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">
  <SonaGetSignupsByDateRangeResult>
    <a:Errors i:nil="true" />
    <a:Result>
      <a:APISignUp>
        <a:anon_id_code>1234</a:anon_id_code>
        <a:credit_status>G</a:credit_status>
        <a:email>[email protected]</a:email>
        <a:first_name>Mike</a:first_name>
        <a:last_name>Lee</a:last_name>
        <a:link_click_date>2019-08-14T16:00:00</a:link_click_date>
        <a:phone>8509886</a:phone>
        <a:signup_date>2019-08-13T15:00:00</a:signup_date>
        <a:signup_id>258</a:signup_id>
        <a:student_id_num>09341404</a:student_id_num>
        <a:survey_code>222</a:survey_code>
        <a:user_id>mikel</a:user_id>
      </a:APISignUp>
      <a:APISignUp>
        <a:anon_id_code>5678</a:anon_id_code>
        <a:credit_status>G</a:credit_status>
        <a:email>[email protected]</a:email>
        <a:first_name>Jesse</a:first_name>
        <a:last_name>James</a:last_name>
        <a:link_click_date>2019-08-14T16:00:00</a:link_click_date>
        <a:phone>8509887</a:phone>
        <a:signup_date>2019-08-13T15:00:00</a:signup_date>
        <a:signup_id>266</a:signup_id>
        <a:student_id_num>09341405</a:student_id_num>
        <a:survey_code>729</a:survey_code>
        <a:user_id>jessej</a:user_id>
      </a:APISignUp>
    </a:Result>
  </SonaGetSignupsByDateRangeResult>
</SonaGetSignupsByDateRangeResponse>

Back to contents

SonaGetStudyScheduleList

Description¶

This API retrieves the list of studies within a given date range. It basically mimics the Study Schedule Report as found in the Generate Reports page of the main site.

Input Parameters¶

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

Parameter	Description / Possible Values
`api_key`	Use API key generated for Sona admin user
`location_id`	Allowed values: `-2`: All locations `-1`: All locations with no resource IDs `0`: All locations with resource IDs `> 0`: Specific resource ID A `resource_id` exists if the location was selected from the list configured in Location Listings.
`start_date`	Date to use for beginning of listing. Date must be formatted as: YYYY-MM-DD.
`end_date`	Date to use for end of listing. Date must be formatted as: YYYY-MM-DD.
`lab_only`	Possible values are as follows: 1 = only standard studies \| 0 = all studies.

Output Parameters¶

Returns an array of APIStudySchedule records. If no records match the request, Errors contains No records found. and Result is not populated.

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	`start_date` is not a valid date or is not properly formatted (must be YYYY-MM-DD)
Error Code	Not supplied	`end_date` is not a valid date or is not properly formatted (must be YYYY-MM-DD)
Error Code	Not supplied	`start_date` must be earlier than `end_date`
Error Code	Not supplied	`location_id` must be numeric
Error Code	Not supplied	`lab_only` must be numeric
Error Code	Not supplied	No records match the supplied filters.

Sample Input¶

Request URL

https://myschool.sona-systems.com/services/SonaAPI.svc/SonaGetStudyScheduleList?api_key=YOUR_API_KEY&location_id=-2&start_date=2012-01-03&end_date=2012-01-10&lab_only=1

URL components

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

Query parameters

api_key = YOUR_API_KEY
location_id = -2
start_date = 2012-01-03
end_date = 2012-01-10
lab_only = 1

Sample Output¶

<SonaGetStudyScheduleListResponse
  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">
  <SonaGetStudyScheduleListResult>
    <a:Errors i:nil="true" />
    <a:Result>
      <a:APIStudySchedule>
        <a:duration>30</a:duration>
        <a:experiment_id>11</a:experiment_id>
        <a:location>LAB 01</a:location>
        <a:num_signed_up>5</a:num_signed_up>
        <a:num_students>10</a:num_students>
        <a:researcher_id>9311</a:researcher_id>
        <a:study_name>Study Name 1</a:study_name>
        <a:survey_flag>0</a:survey_flag>
        <a:timeslot_date>2012-01-05T15:00:00</a:timeslot_date>
        <a:timeslot_id>67</a:timeslot_id>
        <a:videoconf_flag>1</a:videoconf_flag>
        <a:videoconf_url>https://www.zoom.com/123</a:videoconf_url>
        <a:web_flag>0</a:web_flag>
      </a:APIStudySchedule>
      <a:APIStudySchedule>
        <a:duration>30</a:duration>
        <a:experiment_id>12</a:experiment_id>
        <a:location>LAB 02</a:location>
        <a:num_signed_up>3</a:num_signed_up>
        <a:num_students>3</a:num_students>
        <a:researcher_id>9312</a:researcher_id>
        <a:study_name>Study Name 2</a:study_name>
        <a:survey_flag>0</a:survey_flag>
        <a:timeslot_date>2012-01-06T15:00:00</a:timeslot_date>
        <a:timeslot_id>68</a:timeslot_id>
        <a:videoconf_flag>1</a:videoconf_flag>
        <a:videoconf_url>https://www.zoom.com/123</a:videoconf_url>
        <a:web_flag>0</a:web_flag>
      </a:APIStudySchedule>
    </a:Result>
  </SonaGetStudyScheduleListResult>
</SonaGetStudyScheduleListResponse>

Back to contents

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>

Back to contents

SonaGetResearcherIDByExperimentID

Description¶

This API call retrieves the list of researchers (by person_id) for a study, based on the study’s experiment_id.

Input Parameters¶

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

Parameter	Description / Possible Values
`api_key`	Use API key generated for Sona admin user
`experiment_id`	The `experiment_id` of the study.

Output Parameters¶

Will return the person_id of all researchers for the study.

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	-8	invalid `experiment_id`
Error Code	-9	no researchers found for `experiment_id` or invalid `experiment_id`

Sample Input¶

Request URL

https://myschool.sona-systems.com/services/SonaAPI.svc/SonaGetResearcherIDByExperimentID?api_key=YOUR_API_KEY&experiment_id=123

URL components

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

Query parameters

api_key = YOUR_API_KEY
experiment_id = 123

Sample Output¶

<SonaGetResearcherIDByExperimentIDResponse
  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">
  <SonaGetResearcherIDByExperimentIDResult>
    <a:Errors i:nil="true" />
    <a:Result xmlns:b="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
      <b:int>9272</b:int>
      <b:int>9406</b:int>
    </a:Result>
  </SonaGetResearcherIDByExperimentIDResult>
</SonaGetResearcherIDByExperimentIDResponse>

Back to contents

SonaGetPrescreenSurveyDataByPersonID

Description¶

This API call retrieves the list of prescreen or survey responses of a particular participant.

Input Parameters¶

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

Parameter	Description / Possible Values
`api_key`	Use API key generated for Sona admin user
`experiment_id`	The `experiment_id` of the study. Pass in 0 for the prescreen.
`person_id`	The `person_id` of the participant.

Output Parameters¶

Returns a single APIPrescreenSurveyData result for the participant.

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	-8	no prescreen nor survey found for the specified `experiment_id`
Error Code	-9	No prescreen response record or user record was found.
Error Code	-10	Invalid `experiment_id`
Error Code	-11	Invalid `person_id`

Sample Input¶

Request URL

https://myschool.sona-systems.com/services/SonaAPI.svc/SonaGetPrescreenSurveyDataByPersonID?api_key=YOUR_API_KEY&experiment_id=0&person_id=9444

URL components

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

Query parameters

api_key = YOUR_API_KEY
experiment_id = 0
person_id = 9444

Sample Output¶

<SonaGetPrescreenSurveyDataByPersonIDResponse
  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">
  <SonaGetPrescreenSurveyDataByPersonIDResult>
    <a:Errors i:nil="true" />
    <a:Result>
      <a:anon_id_code />
      <a:data_status>S</a:data_status>
      <a:end_time>2013-05-07T00:26:02</a:end_time>
      <a:first_name>Jim</a:first_name>
      <a:last_name>Smith</a:last_name>
      <a:person_id>9444</a:person_id>
      <a:pretest_id>10</a:pretest_id>
      <a:responses>
        <a:APIPrescreenSurveyResponseItem>
          <a:choice_id>462</a:choice_id>
          <a:opt_out_choice>0</a:opt_out_choice>
          <a:question_id>17</a:question_id>
          <a:response_id>1020</a:response_id>
          <a:response_numeric>0</a:response_numeric>
          <a:response_text>4 sup</a:response_text>
        </a:APIPrescreenSurveyResponseItem>
        <a:APIPrescreenSurveyResponseItem>
          <a:choice_id>132</a:choice_id>
          <a:opt_out_choice>0</a:opt_out_choice>
          <a:question_id>27</a:question_id>
          <a:response_id>1021</a:response_id>
          <a:response_numeric>0</a:response_numeric>
          <a:response_text>kinda</a:response_text>
        </a:APIPrescreenSurveyResponseItem>
        <a:APIPrescreenSurveyResponseItem>
          <a:choice_id>147</a:choice_id>
          <a:opt_out_choice>0</a:opt_out_choice>
          <a:question_id>32</a:question_id>
          <a:response_id>1022</a:response_id>
          <a:response_numeric>0</a:response_numeric>
          <a:response_text>erg</a:response_text>
        </a:APIPrescreenSurveyResponseItem>
        <a:APIPrescreenSurveyResponseItem>
          <a:choice_id>293</a:choice_id>
          <a:opt_out_choice>0</a:opt_out_choice>
          <a:question_id>75</a:question_id>
          <a:response_id>1023</a:response_id>
          <a:response_numeric>0</a:response_numeric>
          <a:response_text>yeah!</a:response_text>
        </a:APIPrescreenSurveyResponseItem>
      </a:responses>
      <a:start_time>2013-05-07T00:25:36</a:start_time>
      <a:status>C</a:status>
      <a:user_id>jsmith</a:user_id>
    </a:Result>
  </SonaGetPrescreenSurveyDataByPersonIDResult>
</SonaGetPrescreenSurveyDataByPersonIDResponse>

Back to contents

SonaGetPrescreenSurveyDataByDateRange

Description¶

This API retrieves the list of prescreen or survey responses, for multiple participants, based on a given date range.

Input Parameters¶

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

Parameter	Description / Possible Values
`api_key`	Use API key generated for Sona admin user
`experiment_id`	The `experiment_id` of the study. Pass in 0 for the prescreen.
`start_date`	The start date of the date range to include. Date must be formatted as: YYYY-MM-DD. This date is based on when the participant completed the prescreen or online survey.
`end_date`	The end date of the date range to include. Date must be formatted as: YYYY-MM-DD. This date is based on when the participant completed the prescreen or online survey.

Output Parameters¶

Will return APIPrescreenSurveyData 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	-8	no prescreen nor survey found for the specified `experiment_id`
Error Code	-9	No completed prescreen or survey responses were found in the selected date range.
Error Code	-10	invalid start date
Error Code	-11	invalid end date
Error Code	-12	start date is greater than end date
Error Code	-14	`experiment_id` is not found/invalid

Sample Input¶

Request URL

https://myschool.sona-systems.com/services/SonaAPI.svc/SonaGetPrescreenSurveyDataByDateRange?api_key=YOUR_API_KEY&experiment_id=0&start_date=2013-01-01&end_date=2013-12-31

URL components

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

Query parameters

api_key = YOUR_API_KEY
experiment_id = 0
start_date = 2013-01-01
end_date = 2013-12-31

Sample Output¶

<SonaGetPrescreenSurveyDataByDateRangeResponse
  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">
  <SonaGetPrescreenSurveyDataByDateRangeResult>
    <a:Errors i:nil="true" />
    <a:Result>
      <a:APIPrescreenSurveyData>
        <a:anon_id_code />
        <a:data_status>S</a:data_status>
        <a:end_time>2013-04-24T15:28:58</a:end_time>
        <a:first_name>Frank</a:first_name>
        <a:last_name>Bass</a:last_name>
        <a:person_id>9394</a:person_id>
        <a:pretest_id>10</a:pretest_id>
        <a:responses>
          <a:APIPrescreenSurveyResponseItem>
            <a:choice_id>57</a:choice_id>
            <a:opt_out_choice>0</a:opt_out_choice>
            <a:question_id>17</a:question_id>
            <a:response_id>1005</a:response_id>
            <a:response_numeric>0</a:response_numeric>
            <a:response_text>külm</a:response_text>
          </a:APIPrescreenSurveyResponseItem>
          <a:APIPrescreenSurveyResponseItem>
            <a:choice_id>129</a:choice_id>
            <a:opt_out_choice>1</a:opt_out_choice>
            <a:question_id>27</a:question_id>
            <a:response_id>1006</a:response_id>
            <a:response_numeric>0</a:response_numeric>
            <a:response_text>[Decline to Answer]</a:response_text>
          </a:APIPrescreenSurveyResponseItem>
          <a:APIPrescreenSurveyResponseItem>
            <a:choice_id>145</a:choice_id>
            <a:opt_out_choice>1</a:opt_out_choice>
            <a:question_id>32</a:question_id>
            <a:response_id>1007</a:response_id>
            <a:response_numeric>0</a:response_numeric>
            <a:response_text>[Decline to Answer]</a:response_text>
          </a:APIPrescreenSurveyResponseItem>
        </a:responses>
        <a:start_time>2013-04-24T15:28:45</a:start_time>
        <a:status>C</a:status>
        <a:user_id>bass</a:user_id>
      </a:APIPrescreenSurveyData>
      <a:APIPrescreenSurveyData>
        <a:anon_id_code />
        <a:data_status>S</a:data_status>
        <a:end_time>2013-04-29T23:31:55</a:end_time>
        <a:first_name>Greg</a:first_name>
        <a:last_name>Smith</a:last_name>
        <a:person_id>9308</a:person_id>
        <a:pretest_id>10</a:pretest_id>
        <a:responses>
          <a:APIPrescreenSurveyResponseItem>
            <a:choice_id>57</a:choice_id>
            <a:opt_out_choice>0</a:opt_out_choice>
            <a:question_id>17</a:question_id>
            <a:response_id>1010</a:response_id>
            <a:response_numeric>0</a:response_numeric>
            <a:response_text>külm</a:response_text>
          </a:APIPrescreenSurveyResponseItem>
          <a:APIPrescreenSurveyResponseItem>
            <a:choice_id>130</a:choice_id>
            <a:opt_out_choice>0</a:opt_out_choice>
            <a:question_id>27</a:question_id>
            <a:response_id>1011</a:response_id>
            <a:response_numeric>1</a:response_numeric>
            <a:response_text>Yes</a:response_text>
          </a:APIPrescreenSurveyResponseItem>
          <a:APIPrescreenSurveyResponseItem>
            <a:choice_id>146</a:choice_id>
            <a:opt_out_choice>0</a:opt_out_choice>
            <a:question_id>32</a:question_id>
            <a:response_id>1012</a:response_id>
            <a:response_numeric>2</a:response_numeric>
            <a:response_text>No</a:response_text>
          </a:APIPrescreenSurveyResponseItem>
        </a:responses>
        <a:start_time>2013-04-29T23:31:38</a:start_time>
        <a:status>C</a:status>
        <a:user_id>smithg</a:user_id>
      </a:APIPrescreenSurveyData>
    </a:Result>
  </SonaGetPrescreenSurveyDataByDateRangeResult>
</SonaGetPrescreenSurveyDataByDateRangeResponse>

Back to contents

SonaGetPrescreenDataByExperimentID

Description¶

Returns prescreen responses for participants with credit records for the specified experiment_id.

Input Parameters¶

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

Parameter	Description / Possible Values
`api_key`	Use API key generated for Sona admin user
`experiment_id`	Numeric ID of the study whose participants' prescreen responses are requested.

Output Parameters¶

Will return APIPrescreenSurveyData class and display data in an array.

Returns up to 299 participant records per request. Results may be incomplete for larger groups.

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	-8	No prescreen is configured for the site.
Error Code	-10	`experiment_id` is missing or non-numeric.
Error Code	-12	No participant prescreen records were found for the study.

Sample Input¶

Request URL

https://myschool.sona-systems.com/services/SonaAPI.svc/SonaGetPrescreenDataByExperimentID?api_key=YOUR_API_KEY&experiment_id=1234

URL components

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

Query parameters

api_key = YOUR_API_KEY
experiment_id = 1234

Sample Output¶

<SonaGetPrescreenDataByExperimentIDResponse
  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">
  <SonaGetPrescreenDataByExperimentIDResult>
    <a:Errors i:nil="true" />
    <a:Result>
      <a:APIPrescreenSurveyData>
        <a:anon_id_code />
        <a:data_status>S</a:data_status>
        <a:end_time>2013-04-24T15:28:58</a:end_time>
        <a:first_name>Frank</a:first_name>
        <a:last_name>Bass</a:last_name>
        <a:person_id>9394</a:person_id>
        <a:pretest_id>10</a:pretest_id>
        <a:responses>
          <a:APIPrescreenSurveyResponseItem>
            <a:choice_id>57</a:choice_id>
            <a:opt_out_choice>0</a:opt_out_choice>
            <a:question_id>17</a:question_id>
            <a:response_id>1005</a:response_id>
            <a:response_numeric>0</a:response_numeric>
            <a:response_text>külm</a:response_text>
          </a:APIPrescreenSurveyResponseItem>
          <a:APIPrescreenSurveyResponseItem>
            <a:choice_id>129</a:choice_id>
            <a:opt_out_choice>1</a:opt_out_choice>
            <a:question_id>27</a:question_id>
            <a:response_id>1006</a:response_id>
            <a:response_numeric>0</a:response_numeric>
            <a:response_text>[Decline to Answer]</a:response_text>
          </a:APIPrescreenSurveyResponseItem>
          <a:APIPrescreenSurveyResponseItem>
            <a:choice_id>145</a:choice_id>
            <a:opt_out_choice>1</a:opt_out_choice>
            <a:question_id>32</a:question_id>
            <a:response_id>1007</a:response_id>
            <a:response_numeric>0</a:response_numeric>
            <a:response_text>[Decline to Answer]</a:response_text>
          </a:APIPrescreenSurveyResponseItem>
        </a:responses>
        <a:start_time>2013-04-24T15:28:45</a:start_time>
        <a:status>C</a:status>
        <a:user_id>bass</a:user_id>
      </a:APIPrescreenSurveyData>
      <a:APIPrescreenSurveyData>
        <a:anon_id_code />
        <a:data_status>S</a:data_status>
        <a:end_time>2013-04-29T23:31:55</a:end_time>
        <a:first_name>Greg</a:first_name>
        <a:last_name>Smith</a:last_name>
        <a:person_id>9308</a:person_id>
        <a:pretest_id>10</a:pretest_id>
        <a:responses>
          <a:APIPrescreenSurveyResponseItem>
            <a:choice_id>57</a:choice_id>
            <a:opt_out_choice>0</a:opt_out_choice>
            <a:question_id>17</a:question_id>
            <a:response_id>1010</a:response_id>
            <a:response_numeric>0</a:response_numeric>
            <a:response_text>külm</a:response_text>
          </a:APIPrescreenSurveyResponseItem>
          <a:APIPrescreenSurveyResponseItem>
            <a:choice_id>130</a:choice_id>
            <a:opt_out_choice>0</a:opt_out_choice>
            <a:question_id>27</a:question_id>
            <a:response_id>1011</a:response_id>
            <a:response_numeric>1</a:response_numeric>
            <a:response_text>Yes</a:response_text>
          </a:APIPrescreenSurveyResponseItem>
          <a:APIPrescreenSurveyResponseItem>
            <a:choice_id>146</a:choice_id>
            <a:opt_out_choice>0</a:opt_out_choice>
            <a:question_id>32</a:question_id>
            <a:response_id>1012</a:response_id>
            <a:response_numeric>2</a:response_numeric>
            <a:response_text>No</a:response_text>
          </a:APIPrescreenSurveyResponseItem>
        </a:responses>
        <a:start_time>2013-04-29T23:31:38</a:start_time>
        <a:status>C</a:status>
        <a:user_id>smithg</a:user_id>
      </a:APIPrescreenSurveyData>
    </a:Result>
  </SonaGetPrescreenDataByExperimentIDResult>
</SonaGetPrescreenDataByExperimentIDResponse>

Back to contents

SonaGetPrescreenDataByTimeslotID

Description¶

Returns prescreen responses for participants signed up for the specified timeslot_id.

Input Parameters¶

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

Parameter	Description / Possible Values
`api_key`	Use API key generated for Sona admin user
`timeslot_id`	Numeric ID of the timeslot whose participants' prescreen responses are requested.

Output Parameters¶

Will return APIPrescreenSurveyData class and display data in an array.

Returns up to 299 participant records per request. Results may be incomplete for larger groups.

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	-8	No prescreen is configured for the site.
Error Code	-11	`timeslot_id` is missing or non-numeric.
Error Code	-12	No participant prescreen records were found for the timeslot.

Sample Input¶

Request URL

https://myschool.sona-systems.com/services/SonaAPI.svc/SonaGetPrescreenDataByTimeslotID?api_key=YOUR_API_KEY&timeslot_id=1234

URL components

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

Query parameters

api_key = YOUR_API_KEY
timeslot_id = 1234

Sample Output¶

<SonaGetPrescreenDataByTimeslotIDResponse
  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">
  <SonaGetPrescreenDataByTimeslotIDResult>
    <a:Errors i:nil="true" />
    <a:Result>
      <a:APIPrescreenSurveyData>
        <a:anon_id_code />
        <a:data_status>S</a:data_status>
        <a:end_time>2013-04-24T15:28:58</a:end_time>
        <a:first_name>Frank</a:first_name>
        <a:last_name>Bass</a:last_name>
        <a:person_id>9394</a:person_id>
        <a:pretest_id>10</a:pretest_id>
        <a:responses>
          <a:APIPrescreenSurveyResponseItem>
            <a:choice_id>57</a:choice_id>
            <a:opt_out_choice>0</a:opt_out_choice>
            <a:question_id>17</a:question_id>
            <a:response_id>1005</a:response_id>
            <a:response_numeric>0</a:response_numeric>
            <a:response_text>külm</a:response_text>
          </a:APIPrescreenSurveyResponseItem>
          <a:APIPrescreenSurveyResponseItem>
            <a:choice_id>129</a:choice_id>
            <a:opt_out_choice>1</a:opt_out_choice>
            <a:question_id>27</a:question_id>
            <a:response_id>1006</a:response_id>
            <a:response_numeric>0</a:response_numeric>
            <a:response_text>[Decline to Answer]</a:response_text>
          </a:APIPrescreenSurveyResponseItem>
          <a:APIPrescreenSurveyResponseItem>
            <a:choice_id>145</a:choice_id>
            <a:opt_out_choice>1</a:opt_out_choice>
            <a:question_id>32</a:question_id>
            <a:response_id>1007</a:response_id>
            <a:response_numeric>0</a:response_numeric>
            <a:response_text>[Decline to Answer]</a:response_text>
          </a:APIPrescreenSurveyResponseItem>
        </a:responses>
        <a:start_time>2013-04-24T15:28:45</a:start_time>
        <a:status>C</a:status>
        <a:user_id>bass</a:user_id>
      </a:APIPrescreenSurveyData>
      <a:APIPrescreenSurveyData>
        <a:anon_id_code />
        <a:data_status>S</a:data_status>
        <a:end_time>2013-04-29T23:31:55</a:end_time>
        <a:first_name>Greg</a:first_name>
        <a:last_name>Smith</a:last_name>
        <a:person_id>9308</a:person_id>
        <a:pretest_id>10</a:pretest_id>
        <a:responses>
          <a:APIPrescreenSurveyResponseItem>
            <a:choice_id>57</a:choice_id>
            <a:opt_out_choice>0</a:opt_out_choice>
            <a:question_id>17</a:question_id>
            <a:response_id>1010</a:response_id>
            <a:response_numeric>0</a:response_numeric>
            <a:response_text>külm</a:response_text>
          </a:APIPrescreenSurveyResponseItem>
          <a:APIPrescreenSurveyResponseItem>
            <a:choice_id>130</a:choice_id>
            <a:opt_out_choice>0</a:opt_out_choice>
            <a:question_id>27</a:question_id>
            <a:response_id>1011</a:response_id>
            <a:response_numeric>1</a:response_numeric>
            <a:response_text>Yes</a:response_text>
          </a:APIPrescreenSurveyResponseItem>
          <a:APIPrescreenSurveyResponseItem>
            <a:choice_id>146</a:choice_id>
            <a:opt_out_choice>0</a:opt_out_choice>
            <a:question_id>32</a:question_id>
            <a:response_id>1012</a:response_id>
            <a:response_numeric>2</a:response_numeric>
            <a:response_text>No</a:response_text>
          </a:APIPrescreenSurveyResponseItem>
        </a:responses>
        <a:start_time>2013-04-29T23:31:38</a:start_time>
        <a:status>C</a:status>
        <a:user_id>smithg</a:user_id>
      </a:APIPrescreenSurveyData>
    </a:Result>
  </SonaGetPrescreenDataByTimeslotIDResult>
</SonaGetPrescreenDataByTimeslotIDResponse>

Back to contents

This function updates the credit status for the specified signup_id. This allows for granting credit, marking a no-show, and updating comments. Variable credit granting is supported. Only 1 signup can be updated at a time. Internal online survey studies are not supported.

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

Parameter	Description / Possible Values
`api_key`	Use API key generated for Sona admin user
`signup_id`	Numeric ID of the signup to adjust the credit status for.
`credit_type`	The new credit status for the sign-up. It should be one of the following single characters: G = credit grant W = awaiting action E = Excused No-Show I = Unexcused No-Show
`comments`	Comment for credit status (may be empty)
`credits`	Decimal value of credit to set (e.g. 2.0). Set to -1 for paid studies or to use the study’s default credit value if a credit study. If Variable Credit Granting is enabled, then value may be set to a value from 0-2x the study’s credit value, following the acceptable values as specified in Credit Increment in System Settings.
`skip_credit_email`	Whether an email should be sent to the participant about the change in credit status. false will send an email and true will not send the email

Returns a Boolean value. If Errors contains messages, the request failed and Result is false. Otherwise, true means the requested update was applied. A result of false with no errors means no update was needed because the signup already matched the requested values.

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	-8	`signup_id` not found
Error Code	-9	`credit_type` invalid
Error Code	-10	credits value invalid
Error Code	-11	credits value increment invalid
Error Code	-12	`skip_credit_email` value is invalid
Error Code	-13	invalid study type
Error Code	-14	`signup_id` not valid (non-numeric)
Error Code	-15	The signup is awaiting payment confirmation or has already been paid and cannot be updated.

Request URL

https://myschool.sona-systems.com/services/SonaAPI.svc/SonaGrantCreditBySignupID?api_key=YOUR_API_KEY&signup_id=123&credit_type=G&comments=Test%20Comment&credits=1&skip_credit_email=false

URL components

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

Query parameters

api_key = YOUR_API_KEY
signup_id = 123
credit_type = G
comments = Test Comment
credits = 1
skip_credit_email = false

<SonaGrantCreditBySignupIDResponse
  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">
  <SonaGrantCreditBySignupIDResult>
    <a:Errors i:nil="true" />
    <a:Result>true</a:Result>
  </SonaGrantCreditBySignupIDResult>
</SonaGrantCreditBySignupIDResponse>

If the output returned is similar to the output above, but the value of Result is false instead of true, this indicates that the information provided was valid, but that the signup was already marked with the same credit status (and comments) so there was no action to be taken.

Back to contents

SonaFixStudyCreditAssignmentMismatch

Description¶

This function adjusts all cases where there is a credit assignment mismatch. A credit assignment mismatch is a case where a study has course restrictions for a certain set of courses, and the participant (who is in one of those courses) has assigned the credit to another one of their courses that was not in the restriction list. An example would be if a study has course restrictions such that only participants in courses A and B may sign up. A participant who is in courses B and C signs up, and assigns the credit to course C. This situation is entirely normal and usually allowable.

This API call will look for all cases of a mismatch. When it finds one, it will go through that participant’s courses in order based on the course name, and reassign the credit to the first course that is within the course restrictions for the study. If there are no courses to assign the credit to (a rare case), it will un-assign the credit from the current course.

Use SonaGetStudyCreditAssignmentMismatch to review the affected credit assignments before making these changes.

The return value indicates the number of cases where a credit was reassigned or unassigned.

This API call was added for a specific customer, and may not generally be of use in most situations.

Input Parameters¶

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

Parameter	Description / Possible Values
`api_key`	Use API key generated for Sona admin user

Output Parameters¶

Will return the number of mismatches fixed.

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

Sample Input¶

Request URL

https://myschool.sona-systems.com/services/SonaAPI.svc/SonaFixStudyCreditAssignmentMismatch?api_key=YOUR_API_KEY

URL components

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

Query parameters

api_key = YOUR_API_KEY

Sample Output¶

<SonaFixStudyCreditAssignmentMismatchResponse
  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">
  <SonaFixStudyCreditAssignmentMismatchResult>
    <a:Errors i:nil="true" />
    <a:Result>4</a:Result>
  </SonaFixStudyCreditAssignmentMismatchResult>
</SonaFixStudyCreditAssignmentMismatchResponse>

Back to contents

SonaGetStudyCreditAssignmentMismatch

Description¶

This function returns study credit assignments where the participant assigned the credit to a course that is not included in the study's course restrictions. For example, a study may be restricted to courses A and B, while a participant enrolled in courses B and C assigns the study credit to course C.

This is a read-only function. It can be used to review the affected credit assignments before calling SonaFixStudyCreditAssignmentMismatch, which reassigns or unassigns the mismatched credits.

Input Parameters¶

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

Parameter	Description / Possible Values
`api_key`	Use API key generated for Sona admin user

Output Parameters¶

Returns an array of APICreditItem values, with one item for each mismatched credit assignment.

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	-8	No credit item record was found. This should not ordinarily occur.
Error	-9	No course-restriction mismatches were found.

Sample Input¶

Request URL

https://myschool.sona-systems.com/services/SonaAPI.svc/SonaGetStudyCreditAssignmentMismatch?api_key=YOUR_API_KEY

URL components

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

Query parameters

api_key = YOUR_API_KEY

Sample Output¶

<SonaGetStudyCreditAssignmentMismatchResponse
  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">
  <SonaGetStudyCreditAssignmentMismatchResult>
    <a:Errors i:nil="true" />
    <a:Result>
      <a:APICreditItem>
        <a:class_id>202</a:class_id>
        <a:comments />
        <a:credit_id>1369</a:credit_id>
        <a:credit_type>G</a:credit_type>
        <a:date_granted>2026-08-18T00:00:00</a:date_granted>
        <a:email>[email protected]</a:email>
        <a:experiment_id>159</a:experiment_id>
        <a:first_name>Jamie</a:first_name>
        <a:grantor_id>11818</a:grantor_id>
        <a:last_name>Smith</a:last_name>
        <a:manual_credit_flag>0</a:manual_credit_flag>
        <a:payment_amount>0</a:payment_amount>
        <a:payment_status>W</a:payment_status>
        <a:payment_status_last_updated>0001-01-01T00:00:00</a:payment_status_last_updated>
        <a:penalty_credit>0</a:penalty_credit>
        <a:person_id>11498</a:person_id>
        <a:show_credit>0.50</a:show_credit>
        <a:signup_id>1369</a:signup_id>
        <a:student_id_num />
        <a:user_id>jsmith</a:user_id>
      </a:APICreditItem>
    </a:Result>
  </SonaGetStudyCreditAssignmentMismatchResult>
</SonaGetStudyCreditAssignmentMismatchResponse>

Back to contents

SonaGetPersonInfoByPersonID

Description¶

Returns information about a user identified by their person_id. It supports all user types. The fields populated depend on the user type.

Input Parameters¶

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

Parameter	Description / Possible Values
`api_key`	Use API key generated for Sona admin user
`person_id`	The numeric identifier of the user

Output Parameters¶

Will return APIPerson 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	-8	Invalid `person_id`

Sample Input¶

Request URL

https://myschool.sona-systems.com/services/SonaAPI.svc/SonaGetPersonInfoByPersonID?api_key=YOUR_API_KEY&person_id=4321

URL components

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

Query parameters

api_key = YOUR_API_KEY
person_id = 4321

Sample Output¶

<SonaGetPersonInfoByPersonIDResponse
  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">
  <SonaGetPersonInfoByPersonIDResult>
    <a:Errors i:nil="true" />
    <a:Result>
      <a:APIPerson>
        <a:admin_comments>Taking course again</a:admin_comments>
        <a:alt_email>[email protected]</a:alt_email>
        <a:anon_id_code>32290</a:anon_id_code>
        <a:approved>1</a:approved>
        <a:birthdate>1975-07-20T00:00:00</a:birthdate>
        <a:classes_needed>0</a:classes_needed>
        <a:creation_date>2013-01-12T00:00:00</a:creation_date>
        <a:credits_earned>4.50</a:credits_earned>
        <a:credits_needed>4.00</a:credits_needed>
        <a:daily_reminder>1</a:daily_reminder>
        <a:email_needed>0</a:email_needed>
        <a:first_name>Jake</a:first_name>
        <a:hipaa_ack_date>2013-09-13T09:00:56</a:hipaa_ack_date>
        <a:hipaa_ack_date_nonp>2013-09-13T09:00:56</a:hipaa_ack_date_nonp>
        <a:language_pref>EN</a:language_pref>
        <a:last_login>2013-09-13T09:00:53</a:last_login>
        <a:last_name>Rogers</a:last_name>
        <a:limit_date>2013-03-15T08:35:05</a:limit_date>
        <a:limit_type />
        <a:limited>0</a:limited>
        <a:login_allowed>1</a:login_allowed>
        <a:login_days>16</a:login_days>
        <a:login_sent_date>2013-04-21T07:11:00</a:login_sent_date>
        <a:noshow_count>0</a:noshow_count>
        <a:office />
        <a:password_change_needed>0</a:password_change_needed>
        <a:password_failed_count>0</a:password_failed_count>
        <a:person_id>4321</a:person_id>
        <a:person_type_a>0</a:person_type_a>
        <a:person_type_e>0</a:person_type_e>
        <a:person_type_i>0</a:person_type_i>
        <a:person_type_p>0</a:person_type_p>
        <a:person_type_pref>S</a:person_type_pref>
        <a:person_type_s>1</a:person_type_s>
        <a:phone>867-5309</a:phone>
        <a:pretest>1</a:pretest>
        <a:student_id_num />
        <a:study_invitation>0</a:study_invitation>
        <a:usage_limit>0</a:usage_limit>
        <a:user_id>jake</a:user_id>
        <a:weekly_reminder>1</a:weekly_reminder>
      </a:APIPerson>
    </a:Result>
  </SonaGetPersonInfoByPersonIDResult>
</SonaGetPersonInfoByPersonIDResponse>

Back to contents

SonaGetPersonInfoByStudentID

Description¶

This function returns one participant matching the supplied student_id_num value (University ID number). It works for participants and multi-role users with the Participant role enabled (person_type_s = 1).

Input Parameters¶

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

Parameter	Description / Possible Values
`api_key`	Use API key generated for Sona admin user
`student_id`	The `student_id_num` of the user.

Output Parameters¶

Returns one matching participant in an APIPerson array. If multiple participants share the student ID, only one is returned.

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	-8	invalid `student_id`

Sample Input¶

Request URL

https://myschool.sona-systems.com/services/SonaAPI.svc/SonaGetPersonInfoByStudentID?api_key=YOUR_API_KEY&student_id=s54321

URL components

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

Query parameters

api_key = YOUR_API_KEY
student_id = s54321

Sample Output¶

<SonaGetPersonInfoByStudentIDResponse
  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">
  <SonaGetPersonInfoByStudentIDResult>
    <a:Errors i:nil="true" />
    <a:Result>
      <a:APIPerson>
        <a:admin_comments>This is an old student</a:admin_comments>
        <a:alt_email>[email protected]</a:alt_email>
        <a:anon_id_code>32290</a:anon_id_code>
        <a:approved>1</a:approved>
        <a:birthdate>1975-07-20T00:00:00</a:birthdate>
        <a:classes_needed>0</a:classes_needed>
        <a:creation_date>2015-01-12T00:00:00</a:creation_date>
        <a:credits_earned>4.50</a:credits_earned>
        <a:credits_needed>4.00</a:credits_needed>
        <a:daily_reminder>1</a:daily_reminder>
        <a:email_needed>0</a:email_needed>
        <a:first_name>William</a:first_name>
        <a:hipaa_ack_date>2015-09-13T09:00:56</a:hipaa_ack_date>
        <a:hipaa_ack_date_nonp>2015-09-13T09:00:56</a:hipaa_ack_date_nonp>
        <a:language_pref>EN</a:language_pref>
        <a:last_login>2015-09-13T09:00:53</a:last_login>
        <a:last_name>Blake</a:last_name>
        <a:limit_date>2015-03-15T08:35:05</a:limit_date>
        <a:limit_type />
        <a:limited>0</a:limited>
        <a:login_allowed>1</a:login_allowed>
        <a:login_days>26</a:login_days>
        <a:login_sent_date>2015-04-21T07:11:00</a:login_sent_date>
        <a:noshow_count>0</a:noshow_count>
        <a:office />
        <a:password_change_needed>0</a:password_change_needed>
        <a:password_failed_count>0</a:password_failed_count>
        <a:person_id>12340</a:person_id>
        <a:person_type_a>0</a:person_type_a>
        <a:person_type_e>0</a:person_type_e>
        <a:person_type_i>0</a:person_type_i>
        <a:person_type_p>0</a:person_type_p>
        <a:person_type_pref>S</a:person_type_pref>
        <a:person_type_s>1</a:person_type_s>
        <a:phone>888-5399</a:phone>
        <a:pretest>1</a:pretest>
        <a:student_id_num>s54321</a:student_id_num>
        <a:study_invitation>0</a:study_invitation>
        <a:usage_limit>0</a:usage_limit>
        <a:user_id>william</a:user_id>
        <a:weekly_reminder>1</a:weekly_reminder>
      </a:APIPerson>
    </a:Result>
  </SonaGetPersonInfoByStudentIDResult>
</SonaGetPersonInfoByStudentIDResponse>

Back to contents

SonaGetPersonInfoByUserID

Description¶

Returns information about a user identified by their user_id. It supports all user types. The fields populated depend on the user type.

Input Parameters¶

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

Parameter	Description / Possible Values
`api_key`	Use API key generated for Sona admin user
`user_id`	The alphanumeric User ID of the user

Output Parameters¶

Will return APIPerson 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	-8	Invalid `user_id`

Sample Input¶

Request URL

https://myschool.sona-systems.com/services/SonaAPI.svc/SonaGetPersonInfoByUserID?api_key=YOUR_API_KEY&user_id=userid

URL components

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

Query parameters

api_key = YOUR_API_KEY
user_id = userid

Sample Output¶

<SonaGetPersonInfoByUserIDResponse
  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">
  <SonaGetPersonInfoByUserIDResult>
    <a:Errors i:nil="true" />
    <a:Result>
      <a:APIPerson>
        <a:admin_comments>Taking course again</a:admin_comments>
        <a:alt_email>[email protected]</a:alt_email>
        <a:anon_id_code>32290</a:anon_id_code>
        <a:approved>1</a:approved>
        <a:birthdate>1975-07-20T00:00:00</a:birthdate>
        <a:classes_needed>0</a:classes_needed>
        <a:creation_date>2013-01-12T00:00:00</a:creation_date>
        <a:credits_earned>4.50</a:credits_earned>
        <a:credits_needed>4.00</a:credits_needed>
        <a:daily_reminder>1</a:daily_reminder>
        <a:email_needed>0</a:email_needed>
        <a:first_name>Jake</a:first_name>
        <a:hipaa_ack_date>2013-09-13T09:00:56</a:hipaa_ack_date>
        <a:hipaa_ack_date_nonp>2013-09-13T09:00:56</a:hipaa_ack_date_nonp>
        <a:language_pref>EN</a:language_pref>
        <a:last_login>2013-09-13T09:00:53</a:last_login>
        <a:last_name>Rogers</a:last_name>
        <a:limit_date>2013-03-15T08:35:05</a:limit_date>
        <a:limit_type />
        <a:limited>0</a:limited>
        <a:login_allowed>1</a:login_allowed>
        <a:login_days>16</a:login_days>
        <a:login_sent_date>2013-04-21T07:11:00</a:login_sent_date>
        <a:noshow_count>0</a:noshow_count>
        <a:office />
        <a:password_change_needed>0</a:password_change_needed>
        <a:password_failed_count>0</a:password_failed_count>
        <a:person_id>4321</a:person_id>
        <a:person_type_a>0</a:person_type_a>
        <a:person_type_e>0</a:person_type_e>
        <a:person_type_i>0</a:person_type_i>
        <a:person_type_p>0</a:person_type_p>
        <a:person_type_pref>S</a:person_type_pref>
        <a:person_type_s>1</a:person_type_s>
        <a:phone>867-5309</a:phone>
        <a:pretest>1</a:pretest>
        <a:student_id_num />
        <a:study_invitation>0</a:study_invitation>
        <a:usage_limit>0</a:usage_limit>
        <a:user_id>userid</a:user_id>
        <a:weekly_reminder>0</a:weekly_reminder>
      </a:APIPerson>
    </a:Result>
  </SonaGetPersonInfoByUserIDResult>
</SonaGetPersonInfoByUserIDResponse>

Back to contents

SonaGetPersonInfoByIDCode

Description¶

Returns information about a user identified by their anon_id_code. It supports all user types. The fields populated depend on the user type.

Input Parameters¶

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

Parameter	Description / Possible Values
`api_key`	Use API key generated for Sona admin user
`anon_id_code`	The numeric anonymous ID code assigned to the user.

Output Parameters¶

Will return APIPerson 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	-8	Invalid `anon_id_code`

Sample Input¶

Request URL

https://myschool.sona-systems.com/services/SonaAPI.svc/SonaGetPersonInfoByIDCode?api_key=YOUR_API_KEY&anon_id_code=32290

URL components

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

Query parameters

api_key = YOUR_API_KEY
anon_id_code = 32290

Sample Output¶

<SonaGetPersonInfoByIDCodeResponse
  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">
  <SonaGetPersonInfoByIDCodeResult>
    <a:Errors i:nil="true" />
    <a:Result>
      <a:APIPerson>
        <a:admin_comments>Taking course again</a:admin_comments>
        <a:alt_email>[email protected]</a:alt_email>
        <a:anon_id_code>32290</a:anon_id_code>
        <a:approved>1</a:approved>
        <a:birthdate>1975-07-20T00:00:00</a:birthdate>
        <a:classes_needed>0</a:classes_needed>
        <a:creation_date>2013-01-12T00:00:00</a:creation_date>
        <a:credits_earned>4.50</a:credits_earned>
        <a:credits_needed>4.00</a:credits_needed>
        <a:daily_reminder>1</a:daily_reminder>
        <a:email_needed>0</a:email_needed>
        <a:first_name>Jake</a:first_name>
        <a:hipaa_ack_date>2013-09-13T09:00:56</a:hipaa_ack_date>
        <a:hipaa_ack_date_nonp>2013-09-13T09:00:56</a:hipaa_ack_date_nonp>
        <a:language_pref>EN</a:language_pref>
        <a:last_login>2013-09-13T09:00:53</a:last_login>
        <a:last_name>Rogers</a:last_name>
        <a:limit_date>2013-03-15T08:35:05</a:limit_date>
        <a:limit_type />
        <a:limited>0</a:limited>
        <a:login_allowed>1</a:login_allowed>
        <a:login_days>16</a:login_days>
        <a:login_sent_date>2013-04-21T07:11:00</a:login_sent_date>
        <a:noshow_count>0</a:noshow_count>
        <a:office />
        <a:password_change_needed>0</a:password_change_needed>
        <a:password_failed_count>0</a:password_failed_count>
        <a:person_id>4321</a:person_id>
        <a:person_type_a>0</a:person_type_a>
        <a:person_type_e>0</a:person_type_e>
        <a:person_type_i>0</a:person_type_i>
        <a:person_type_p>0</a:person_type_p>
        <a:person_type_pref>S</a:person_type_pref>
        <a:person_type_s>1</a:person_type_s>
        <a:phone>867-5309</a:phone>
        <a:pretest>1</a:pretest>
        <a:student_id_num />
        <a:study_invitation>0</a:study_invitation>
        <a:usage_limit>0</a:usage_limit>
        <a:user_id>jake</a:user_id>
        <a:weekly_reminder>0</a:weekly_reminder>
      </a:APIPerson>
    </a:Result>
  </SonaGetPersonInfoByIDCodeResult>
</SonaGetPersonInfoByIDCodeResponse>

Back to contents

This function will provide all information about a particular study signup, with the specified signup_id.

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

Parameter	Description / Possible Values
`api_key`	Use API key generated for Sona admin user
`signup_id`	The numeric identifier of the sign-up.

Will return a single APICreditItem class (here can only be one signup per signup_id).

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	-8	Sign-up (`signup_id`) not found
Error Code	-9	Credit record not found
Error Code	-10	Invalid `signup_id`

Request URL

https://myschool.sona-systems.com/services/SonaAPI.svc/SonaGetCreditBySignupID?api_key=YOUR_API_KEY&signup_id=100

URL components

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

Query parameters

api_key = YOUR_API_KEY
signup_id = 100

<SonaGetCreditBySignupIDResponse
  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">
  <SonaGetCreditBySignupIDResult>
    <a:Errors i:nil="true" />
    <a:Result>
      <a:class_id>99</a:class_id>
      <a:comments />
      <a:credit_id>100</a:credit_id>
      <a:credit_type>G</a:credit_type>
      <a:date_granted>2013-09-08T00:00:00</a:date_granted>
      <a:email>[email protected]</a:email>
      <a:experiment_id>149</a:experiment_id>
      <a:first_name>Mike</a:first_name>
      <a:grantor_id>10144</a:grantor_id>
      <a:last_name>Donlon</a:last_name>
      <a:manual_credit_flag>0</a:manual_credit_flag>
      <a:payment_amount>12.34</a:payment_amount>
      <a:payment_status>E</a:payment_status>
      <a:payment_status_last_updated>2013-09-08T12:30:00</a:payment_status_last_updated>
      <a:penalty_credit>0</a:penalty_credit>
      <a:person_id>11622</a:person_id>
      <a:show_credit>1.00</a:show_credit>
      <a:signup_id>100</a:signup_id>
      <a:student_id_num />
      <a:user_id>1671835</a:user_id>
    </a:Result>
  </SonaGetCreditBySignupIDResult>
</SonaGetCreditBySignupIDResponse>

Back to contents

SonaGetCreditsByPersonID

Description¶

This function will provide information on each credit and signup for the specified participant, including non-study credit grants.

Input Parameters¶

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

Parameter	Description / Possible Values
`api_key`	Use API key generated for Sona admin user
`person_id`	The numeric identifier of the participant.

Output Parameters¶

Will return an array of APICreditItem class.

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	-8	Person (`person_id`) not found
Error Code	-9	Credit record not found
Error Code	-10	Invalid `person_id`

Sample Input¶

Request URL

https://myschool.sona-systems.com/services/SonaAPI.svc/SonaGetCreditsByPersonID?api_key=YOUR_API_KEY&person_id=11498

URL components

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

Query parameters

api_key = YOUR_API_KEY
person_id = 11498

Sample Output¶

<SonaGetCreditsByPersonIDResponse
  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">
  <SonaGetCreditsByPersonIDResult>
    <a:Errors i:nil="true" />
    <a:Result>
      <a:APICreditItem>
        <a:class_id>115</a:class_id>
        <a:comments />
        <a:credit_id>1369</a:credit_id>
        <a:credit_type>G</a:credit_type>
        <a:date_granted>2013-11-10T00:00:00</a:date_granted>
        <a:email>[email protected]</a:email>
        <a:experiment_id>159</a:experiment_id>
        <a:first_name>Jake</a:first_name>
        <a:grantor_id>11818</a:grantor_id>
        <a:last_name>Ferry</a:last_name>
        <a:manual_credit_flag>0</a:manual_credit_flag>
        <a:occur_date>2012-06-26T15:00:08</a:occur_date>
        <a:payment_amount>0</a:payment_amount>
        <a:payment_status>W</a:payment_status>
        <a:payment_status_last_updated>0001-01-01T00:00:00</a:payment_status_last_updated>
        <a:penalty_credit>0</a:penalty_credit>
        <a:person_id>11498</a:person_id>
        <a:show_credit>0.50</a:show_credit>
        <a:signup_id>1369</a:signup_id>
        <a:student_id_num />
        <a:user_id>jferry</a:user_id>
      </a:APICreditItem>
      <a:APICreditItem>
        <a:class_id>115</a:class_id>
        <a:comments />
        <a:credit_id>1554</a:credit_id>
        <a:credit_type>G</a:credit_type>
        <a:date_granted>2013-11-16T00:00:00</a:date_granted>
        <a:email>[email protected]</a:email>
        <a:experiment_id>153</a:experiment_id>
        <a:first_name>Jake</a:first_name>
        <a:grantor_id>10144</a:grantor_id>
        <a:last_name> Ferry </a:last_name>
        <a:manual_credit_flag>0</a:manual_credit_flag>
        <a:occur_date>2012-06-26T15:00:08</a:occur_date>
        <a:payment_amount>12.34</a:payment_amount>
        <a:payment_status>E</a:payment_status>
        <a:payment_status_last_updated>2013-11-16T12:30:00</a:payment_status_last_updated>
        <a:penalty_credit>0</a:penalty_credit>
        <a:person_id>11498</a:person_id>
        <a:show_credit>0.50</a:show_credit>
        <a:signup_id>1554</a:signup_id>
        <a:student_id_num />
        <a:user_id>jferry</a:user_id>
      </a:APICreditItem>
      <a:APICreditItem>
        <a:class_id>115</a:class_id>
        <a:comments />
        <a:credit_id>1555</a:credit_id>
        <a:credit_type>G</a:credit_type>
        <a:date_granted>2013-11-16T00:00:00</a:date_granted>
        <a:email>[email protected]</a:email>
        <a:experiment_id>155</a:experiment_id>
        <a:first_name>Jake</a:first_name>
        <a:grantor_id>10144</a:grantor_id>
        <a:last_name>Ferry</a:last_name>
        <a:manual_credit_flag>0</a:manual_credit_flag>
        <a:occur_date>2012-06-26T15:00:08</a:occur_date>
        <a:payment_amount>12.34</a:payment_amount>
        <a:payment_status>P</a:payment_status>
        <a:payment_status_last_updated>2013-11-16T14:30:00</a:payment_status_last_updated>
        <a:penalty_credit>0</a:penalty_credit>
        <a:person_id>11498</a:person_id>
        <a:show_credit>0.50</a:show_credit>
        <a:signup_id>1555</a:signup_id>
        <a:student_id_num />
        <a:user_id>jferry</a:user_id>
      </a:APICreditItem>
    </a:Result>
  </SonaGetCreditsByPersonIDResult>
</SonaGetCreditsByPersonIDResponse>

Back to contents

SonaGetCreditsByTimeslotID

Description¶

This function will provide information on every sign up for the specified timeslot.

Input Parameters¶

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

Parameter	Description / Possible Values
`api_key`	Use API key generated for Sona admin user
`timeslot_id`	The numeric identifier of the time slot.

Output Parameters¶

Will return an array of APICreditItem class.

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	-8	timeslot (`timeslot_id`) not found
Error Code	-9	no sign-ups for timeslot found
Error Code	-10	Invalid `timeslot_id`

Sample Input¶

Request URL

https://myschool.sona-systems.com/services/SonaAPI.svc/SonaGetCreditsByTimeslotID?api_key=YOUR_API_KEY&timeslot_id=4321

URL components

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

Query parameters

api_key = YOUR_API_KEY
timeslot_id = 4321

Sample Output¶

<SonaGetCreditsByTimeslotIDResponse
  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">
  <SonaGetCreditsByTimeslotIDResult>
    <a:Errors i:nil="true" />
    <a:Result>
      <a:APICreditItem>
        <a:class_id>99</a:class_id>
        <a:comments />
        <a:credit_id>1749</a:credit_id>
        <a:credit_type>E</a:credit_type>
        <a:date_granted>2013-11-22T00:00:00</a:date_granted>
        <a:email>[email protected]</a:email>
        <a:experiment_id>152</a:experiment_id>
        <a:first_name>Jay</a:first_name>
        <a:grantor_id>11507</a:grantor_id>
        <a:last_name>Smith</a:last_name>
        <a:manual_credit_flag>0</a:manual_credit_flag>
        <a:occur_date>2012-06-26T15:00:08</a:occur_date>
        <a:payment_amount>0</a:payment_amount>
        <a:payment_status>W</a:payment_status>
        <a:payment_status_last_updated>0001-01-01T00:00:00</a:payment_status_last_updated>
        <a:penalty_credit>0</a:penalty_credit>
        <a:person_id>11570</a:person_id>
        <a:show_credit>0</a:show_credit>
        <a:signup_id>1749</a:signup_id>
        <a:student_id_num />
        <a:user_id>1666134</a:user_id>
      </a:APICreditItem>
      <a:APICreditItem>
        <a:class_id>97</a:class_id>
        <a:comments />
        <a:credit_id>1897</a:credit_id>
        <a:credit_type>G</a:credit_type>
        <a:date_granted>2013-12-09T00:00:00</a:date_granted>
        <a:email>[email protected]</a:email>
        <a:experiment_id>152</a:experiment_id>
        <a:first_name>Bill</a:first_name>
        <a:grantor_id>11423</a:grantor_id>
        <a:last_name>Jones</a:last_name>
        <a:manual_credit_flag>0</a:manual_credit_flag>
        <a:occur_date>2012-06-26T15:00:08</a:occur_date>
        <a:payment_amount>12.34</a:payment_amount>
        <a:payment_status>E</a:payment_status>
        <a:payment_status_last_updated>2013-12-09T12:30:00</a:payment_status_last_updated>
        <a:penalty_credit>0</a:penalty_credit>
        <a:person_id>11672</a:person_id>
        <a:show_credit>0.50</a:show_credit>
        <a:signup_id>1897</a:signup_id>
        <a:student_id_num />
        <a:user_id>4523445</a:user_id>
      </a:APICreditItem>
      <a:APICreditItem>
        <a:class_id>101</a:class_id>
        <a:comments />
        <a:credit_id>1948</a:credit_id>
        <a:credit_type>G</a:credit_type>
        <a:date_granted>2013-12-09T00:00:00</a:date_granted>
        <a:email>[email protected]</a:email>
        <a:experiment_id>152</a:experiment_id>
        <a:first_name>Lisa</a:first_name>
        <a:grantor_id>11423</a:grantor_id>
        <a:last_name>Goodman</a:last_name>
        <a:manual_credit_flag>0</a:manual_credit_flag>
        <a:occur_date>2012-06-26T15:00:08</a:occur_date>
        <a:payment_amount>12.34</a:payment_amount>
        <a:payment_status>C</a:payment_status>
        <a:payment_status_last_updated>2013-12-09T14:30:00</a:payment_status_last_updated>
        <a:penalty_credit>0</a:penalty_credit>
        <a:person_id>11661</a:person_id>
        <a:show_credit>0.50</a:show_credit>
        <a:signup_id>1948</a:signup_id>
        <a:student_id_num />
        <a:user_id>1657823</a:user_id>
      </a:APICreditItem>
    </a:Result>
  </SonaGetCreditsByTimeslotIDResult>
</SonaGetCreditsByTimeslotIDResponse>

Back to contents

SonaGetCreditsByDateRange

Description¶

This function will provide information on each credit within a given date range.

Input Parameters¶

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

Parameter	Description / Possible Values
`api_key`	Use API key generated for Sona admin user
`start_date`	The start date of the date range to include. Date must be formatted as: YYYY-MM-DD.
`end_date`	The end date of the date range to include. Date must be formatted as: YYYY-MM-DD.

Output Parameters¶

Will return an array of APICreditItem class.

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	-8	Invalid end date
Error Code	-9	Start date is after end date
Error Code	-10	Invalid start date
Error Code	-11	No credit record found for selected date range

Sample Input¶

Request URL

https://myschool.sona-systems.com/services/SonaAPI.svc/SonaGetCreditsByDateRange?api_key=YOUR_API_KEY&start_date=2014-01-01&end_date=2014-12-31

URL components

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

Query parameters

api_key = YOUR_API_KEY
start_date = 2014-01-01
end_date = 2014-12-31

Sample Output¶

<SonaGetCreditsByDateRangeResponse
  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">
  <SonaGetCreditsByDateRangeResult>
    <a:Errors i:nil="true" />
    <a:Result>
      <a:APICreditItem>
        <a:class_id>99</a:class_id>
        <a:comments />
        <a:credit_id>1749</a:credit_id>
        <a:credit_type>E</a:credit_type>
        <a:date_granted>2014-11-22T00:00:00</a:date_granted>
        <a:email>[email protected]</a:email>
        <a:experiment_id>152</a:experiment_id>
        <a:first_name>Jay</a:first_name>
        <a:grantor_id>11507</a:grantor_id>
        <a:last_name>Smith</a:last_name>
        <a:manual_credit_flag>0</a:manual_credit_flag>
        <a:occur_date>2014-06-26T15:00:08</a:occur_date>
        <a:payment_amount>0</a:payment_amount>
        <a:payment_status>W</a:payment_status>
        <a:payment_status_last_updated>0001-01-01T00:00:00</a:payment_status_last_updated>
        <a:penalty_credit>0</a:penalty_credit>
        <a:person_id>11570</a:person_id>
        <a:show_credit>0</a:show_credit>
        <a:signup_id>1749</a:signup_id>
        <a:student_id_num />
        <a:user_id>1666134</a:user_id>
      </a:APICreditItem>
      <a:APICreditItem>
        <a:class_id>97</a:class_id>
        <a:comments />
        <a:credit_id>1897</a:credit_id>
        <a:credit_type>G</a:credit_type>
        <a:date_granted>2014-12-09T00:00:00</a:date_granted>
        <a:email>[email protected]</a:email>
        <a:experiment_id>152</a:experiment_id>
        <a:first_name>Bill</a:first_name>
        <a:grantor_id>11423</a:grantor_id>
        <a:last_name>Jones</a:last_name>
        <a:manual_credit_flag>0</a:manual_credit_flag>
        <a:occur_date>2014-06-26T15:00:08</a:occur_date>
        <a:payment_amount>12.34</a:payment_amount>
        <a:payment_status>E</a:payment_status>
        <a:payment_status_last_updated>2013-12-09T12:30:00</a:payment_status_last_updated>
        <a:penalty_credit>0</a:penalty_credit>
        <a:person_id>11672</a:person_id>
        <a:show_credit>0.50</a:show_credit>
        <a:signup_id>1897</a:signup_id>
        <a:student_id_num />
        <a:user_id>4523445</a:user_id>
      </a:APICreditItem>
      <a:APICreditItem>
        <a:class_id>101</a:class_id>
        <a:comments />
        <a:credit_id>1948</a:credit_id>
        <a:credit_type>G</a:credit_type>
        <a:date_granted>2014-12-09T00:00:00</a:date_granted>
        <a:email>[email protected]</a:email>
        <a:experiment_id>152</a:experiment_id>
        <a:first_name>Lisa</a:first_name>
        <a:grantor_id>11423</a:grantor_id>
        <a:last_name>Goodman</a:last_name>
        <a:manual_credit_flag>0</a:manual_credit_flag>
        <a:occur_date>2014-06-26T15:00:08</a:occur_date>
        <a:payment_amount>12.34</a:payment_amount>
        <a:payment_status>C</a:payment_status>
        <a:payment_status_last_updated>2013-12-09T14:30:00</a:payment_status_last_updated>
        <a:penalty_credit>0</a:penalty_credit>
        <a:person_id>11661</a:person_id>
        <a:show_credit>0.50</a:show_credit>
        <a:signup_id>1948</a:signup_id>
        <a:student_id_num />
        <a:user_id>1657823</a:user_id>
      </a:APICreditItem>
    </a:Result>
  </SonaGetCreditsByDateRangeResult>
</SonaGetCreditsByDateRangeResponse>

Back to contents

SonaGetPersonListByClassID

Description¶

This API retrieves a list of all participants in the specified course.

Input Parameters¶

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

Parameter	Description / Possible Values
`api_key`	Use API key generated for Sona admin user
`class_id`	The `class_id` of the course

Output Parameters¶

Will return APIPerson 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	-8	Invalid `class_id`. No record found.

Sample Input¶

Request URL

https://myschool.sona-systems.com/services/SonaAPI.svc/SonaGetPersonListByClassID?api_key=YOUR_API_KEY&class_id=1234

URL components

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

Query parameters

api_key = YOUR_API_KEY
class_id = 1234

Sample Output¶

<SonaGetPersonListByClassIDResponse
  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">
  <SonaGetPersonListByClassIDResult>
    <a:Errors i:nil="true" />
    <a:Result>
      <a:APIPerson>
        <a:admin_comments />
        <a:alt_email>[email protected]</a:alt_email>
        <a:anon_id_code>32290</a:anon_id_code>
        <a:approved>1</a:approved>
        <a:birthdate>0001-01-01T00:00:00</a:birthdate>
        <a:classes_needed>0</a:classes_needed>
        <a:creation_date>2019-09-05T15:51:37</a:creation_date>
        <a:credits_earned>0</a:credits_earned>
        <a:credits_needed>4.00</a:credits_needed>
        <a:daily_reminder>1</a:daily_reminder>
        <a:email_needed>0</a:email_needed>
        <a:first_name>Carol</a:first_name>
        <a:hipaa_ack_date>0001-01-01T00:00:00</a:hipaa_ack_date>
        <a:hipaa_ack_date_nonp>0001-01-01T00:00:00</a:hipaa_ack_date_nonp>
        <a:language_pref>EN</a:language_pref>
        <a:last_login>0001-01-01T00:00:00</a:last_login>
        <a:last_name>Spruce</a:last_name>
        <a:limit_date>0001-01-01T00:00:00</a:limit_date>
        <a:limit_type />
        <a:limited>0</a:limited>
        <a:login_allowed>1</a:login_allowed>
        <a:login_days>0</a:login_days>
        <a:login_sent_date>0001-01-01T00:00:00</a:login_sent_date>
        <a:noshow_count>0</a:noshow_count>
        <a:office />
        <a:password_change_needed>0</a:password_change_needed>
        <a:password_failed_count>0</a:password_failed_count>
        <a:person_id>9804</a:person_id>
        <a:person_type_a>0</a:person_type_a>
        <a:person_type_e>0</a:person_type_e>
        <a:person_type_i>0</a:person_type_i>
        <a:person_type_p>0</a:person_type_p>
        <a:person_type_pref>S</a:person_type_pref>
        <a:person_type_s>1</a:person_type_s>
        <a:phone />
        <a:pretest>0</a:pretest>
        <a:student_id_num />
        <a:study_invitation>0</a:study_invitation>
        <a:usage_limit>0</a:usage_limit>
        <a:user_id>cspru</a:user_id>
        <a:weekly_reminder>0</a:weekly_reminder>
      </a:APIPerson>
      <a:APIPerson>
        <a:admin_comments />
        <a:alt_email>[email protected]</a:alt_email>
        <a:anon_id_code>32290</a:anon_id_code>
        <a:approved>1</a:approved>
        <a:birthdate>0001-01-01T00:00:00</a:birthdate>
        <a:classes_needed>0</a:classes_needed>
        <a:creation_date>2019-09-19T06:18:05</a:creation_date>
        <a:credits_earned>0</a:credits_earned>
        <a:credits_needed>4.00</a:credits_needed>
        <a:daily_reminder>0</a:daily_reminder>
        <a:email_needed>0</a:email_needed>
        <a:first_name>Doc</a:first_name>
        <a:hipaa_ack_date>0001-01-01T00:00:00</a:hipaa_ack_date>
        <a:hipaa_ack_date_nonp>0001-01-01T00:00:00</a:hipaa_ack_date_nonp>
        <a:language_pref>EN</a:language_pref>
        <a:last_login>0001-01-01T00:00:00</a:last_login>
        <a:last_name>Rivers</a:last_name>
        <a:limit_date>0001-01-01T00:00:00</a:limit_date>
        <a:limit_type />
        <a:limited>0</a:limited>
        <a:login_allowed>1</a:login_allowed>
        <a:login_days>0</a:login_days>
        <a:login_sent_date>0001-01-01T00:00:00</a:login_sent_date>
        <a:noshow_count>0</a:noshow_count>
        <a:office />
        <a:password_change_needed>0</a:password_change_needed>
        <a:password_failed_count>0</a:password_failed_count>
        <a:person_id>9846</a:person_id>
        <a:person_type_a>0</a:person_type_a>
        <a:person_type_e>0</a:person_type_e>
        <a:person_type_i>0</a:person_type_i>
        <a:person_type_p>0</a:person_type_p>
        <a:person_type_pref>S</a:person_type_pref>
        <a:person_type_s>1</a:person_type_s>
        <a:phone />
        <a:pretest>0</a:pretest>
        <a:student_id_num />
        <a:study_invitation>0</a:study_invitation>
        <a:usage_limit>0</a:usage_limit>
        <a:user_id>[email protected]</a:user_id>
        <a:weekly_reminder>0</a:weekly_reminder>
      </a:APIPerson>
    </a:Result>
  </SonaGetPersonListByClassIDResult>
</SonaGetPersonListByClassIDResponse>

Back to contents

SonaGetTimeslotsByExperimentID

Description¶

This API retrieves a list of timeslots for a particular study.

Input Parameters¶

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

Parameter	Description / Possible Values
`api_key`	Use API key generated for Sona admin user
`experiment_id`	The `experiment_id` of the study
`fill_status`	Optional. Defaults to `S`. A = all timeslots, regardless of signups F = full timeslots E = empty timeslots S = timeslots with at least one signup

Output Parameters¶

Returns an array of APIStudySchedule records. If no records match the request, Errors contains No records found. and Result is not populated.

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	-8	Invalid `experiment_id`
Error Code	Not supplied	No records match the supplied filters.

Sample Input¶

Request URL

https://myschool.sona-systems.com/services/SonaAPI.svc/SonaGetTimeslotsByExperimentID?api_key=YOUR_API_KEY&experiment_id=123&fill_status=A

URL components

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

Query parameters

api_key = YOUR_API_KEY
experiment_id = 123
fill_status = A

Sample Output¶

<SonaGetTimeslotsByExperimentIDResponse
  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">
  <SonaGetTimeslotsByExperimentIDResult>
    <a:Errors i:nil="true" />
    <a:Result>
      <a:APIStudySchedule>
        <a:duration>30</a:duration>
        <a:experiment_id>123</a:experiment_id>
        <a:location>Miller Hall</a:location>
        <a:num_signed_up>9</a:num_signed_up>
        <a:num_students>10</a:num_students>
        <a:researcher_id>0</a:researcher_id>
        <a:study_name>Physics Study</a:study_name>
        <a:survey_flag>0</a:survey_flag>
        <a:timeslot_date>2012-06-26T09:00:00</a:timeslot_date>
        <a:timeslot_id>282</a:timeslot_id>
        <a:videoconf_flag>1</a:videoconf_flag>
        <a:videoconf_url>https://www.zoom.com/123</a:videoconf_url>
        <a:web_flag>0</a:web_flag>
      </a:APIStudySchedule>
      <a:APIStudySchedule>
        <a:duration>30</a:duration>
        <a:experiment_id>123</a:experiment_id>
        <a:location>Miller Hall</a:location>
        <a:num_signed_up>1</a:num_signed_up>
        <a:num_students>10</a:num_students>
        <a:researcher_id>0</a:researcher_id>
        <a:study_name>Physics Study</a:study_name>
        <a:survey_flag>0</a:survey_flag>
        <a:timeslot_date>2012-10-05T10:00:00</a:timeslot_date>
        <a:timeslot_id>305</a:timeslot_id>
        <a:videoconf_flag>1</a:videoconf_flag>
        <a:videoconf_url>https://www.zoom.com/123</a:videoconf_url>
        <a:web_flag>0</a:web_flag>
      </a:APIStudySchedule>
      <a:APIStudySchedule>
        <a:duration>30</a:duration>
        <a:experiment_id>123</a:experiment_id>
        <a:location>Miller Hall</a:location>
        <a:num_signed_up>3</a:num_signed_up>
        <a:num_students>10</a:num_students>
        <a:researcher_id>0</a:researcher_id>
        <a:study_name>Physics Study</a:study_name>
        <a:survey_flag>0</a:survey_flag>
        <a:timeslot_date>2014-07-15T10:30:00</a:timeslot_date>
        <a:timeslot_id>470</a:timeslot_id>
        <a:videoconf_flag>1</a:videoconf_flag>
        <a:videoconf_url>https://www.zoom.com/123</a:videoconf_url>
        <a:web_flag>0</a:web_flag>
      </a:APIStudySchedule>
    </a:Result>
  </SonaGetTimeslotsByExperimentIDResult>
</SonaGetTimeslotsByExperimentIDResponse>

Back to contents

SonaGetTimeslotsByExperimentIDDateRange

Description¶

This API retrieves the list of timeslots, for a particular study, within a given date range.

Input Parameters¶

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

Parameter	Description / Possible Values
`api_key`	Use API key generated for Sona admin user
`experiment_id`	The `experiment_id` of the study
`start_date`	Date to use for beginning of listing. Date must be formatted as: YYYY-MM-DD.
`end_date`	Date to use for end of listing. Date must be formatted as: YYYY-MM-DD.
`fill_status`	Optional. Defaults to `S`. A = all timeslots, regardless of signups F = full timeslots E = empty timeslots S = timeslots with at least one signup

Output Parameters¶

Returns an array of APIStudySchedule records. If no records match the request, Errors contains No records found. and Result is not populated.

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	-8	Invalid `experiment_id`
Error Code	Not supplied	`start_date` is not a valid date or is not properly formatted (must be YYYY-MM-DD)
Error Code	Not supplied	`end_date` is not a valid date or is not properly formatted (must be YYYY-MM-DD)
Error Code	Not supplied	`start_date` must the same as or earlier than `end_date`
Error Code	Not supplied	No records match the supplied filters.

Sample Input¶

Request URL

https://myschool.sona-systems.com/services/SonaAPI.svc/SonaGetTimeslotsByExperimentIDDateRange?api_key=YOUR_API_KEY&experiment_id=123&start_date=2014-01-01&end_date=2014-12-31&fill_status=A

URL components

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

Query parameters

api_key = YOUR_API_KEY
experiment_id = 123
start_date = 2014-01-01
end_date = 2014-12-31
fill_status = A

Sample Output¶

<SonaGetTimeslotsByExperimentIDDateRangeResponse
  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">
  <SonaGetTimeslotsByExperimentIDDateRangeResult>
    <a:Errors i:nil="true" />
    <a:Result>
      <a:APIStudySchedule>
        <a:duration>30</a:duration>
        <a:experiment_id>123</a:experiment_id>
        <a:location>Wick Bldg.</a:location>
        <a:num_signed_up>3</a:num_signed_up>
        <a:num_students>10</a:num_students>
        <a:researcher_id>0</a:researcher_id>
        <a:study_name>Revenge Study</a:study_name>
        <a:survey_flag>0</a:survey_flag>
        <a:timeslot_date>2014-07-15T10:30:00</a:timeslot_date>
        <a:timeslot_id>470</a:timeslot_id>
        <a:videoconf_flag>1</a:videoconf_flag>
        <a:videoconf_url>https://www.zoom.com/123</a:videoconf_url>
        <a:web_flag>0</a:web_flag>
      </a:APIStudySchedule>
      <a:APIStudySchedule>
        <a:duration>30</a:duration>
        <a:experiment_id>123</a:experiment_id>
        <a:location>Wick Bldg.</a:location>
        <a:num_signed_up>2</a:num_signed_up>
        <a:num_students>3</a:num_students>
        <a:researcher_id>0</a:researcher_id>
        <a:study_name>Revenge Study</a:study_name>
        <a:survey_flag>0</a:survey_flag>
        <a:timeslot_date>2014-10-19T11:00:00</a:timeslot_date>
        <a:timeslot_id>477</a:timeslot_id>
        <a:videoconf_flag>1</a:videoconf_flag>
        <a:videoconf_url>https://www.zoom.com/123</a:videoconf_url>
        <a:web_flag>0</a:web_flag>
      </a:APIStudySchedule>
    </a:Result>
  </SonaGetTimeslotsByExperimentIDDateRangeResult>
</SonaGetTimeslotsByExperimentIDDateRangeResponse>

Back to contents

SonaGetParticipantStats

Description¶

This API retrieves basic credit and usage information (summarized) for a particular course, or all courses in the system.

Input Parameters¶

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

Parameter	Description / Possible Values
`api_key`	Use API key generated for Sona admin user
`class_id`	The `class_id` of the course. 0 = all courses.

Output Parameters¶

Will return a single APIParticipantStats result.

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	-8	`class_id` is missing, non-numeric, or does not identify an existing course. Use `0` for all courses.

Sample Input¶

Request URL

https://myschool.sona-systems.com/services/SonaAPI.svc/SonaGetParticipantStats?api_key=YOUR_API_KEY&class_id=4

URL components

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

Query parameters

api_key = YOUR_API_KEY
class_id = 4

Sample Output¶

<SonaGetParticipantStatsResponse
  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">
  <SonaGetParticipantStatsResult>
    <a:Errors i:nil="true" />
    <a:Result>
      <a:class_id>4</a:class_id>
      <a:class_name>PSYCH101</a:class_name>
      <a:complete_total>3</a:complete_total>
      <a:course_credits_earned_total>0</a:course_credits_earned_total>
      <a:incomplete_total>1</a:incomplete_total>
      <a:login_total>2</a:login_total>
      <a:no_login_total>2</a:no_login_total>
      <a:no_signups_total>3</a:no_signups_total>
      <a:overall_credits_earned_total>4</a:overall_credits_earned_total>
      <a:overall_credits_needed_total>14</a:overall_credits_needed_total>
    </a:Result>
  </SonaGetParticipantStatsResult>
</SonaGetParticipantStatsResponse>

Back to contents

SonaGetStudyStats

Description¶

This API retrieves basic usage information for a particular study. It’s similar to the Timeslot Usage Summary in the web interface.

Input Parameters¶

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

Parameter	Description / Possible Values
`api_key`	Use API key generated for Sona admin user
`experiment_id`	The `experiment_id` of the study. For multi-part studies, specify the `experiment_id` of the first part; results will be based on all parts of the study.

Output Parameters¶

Will return a single APIStudyStats result.

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	not a valid `experiment_id`

Sample Input¶

Request URL

https://myschool.sona-systems.com/services/SonaAPI.svc/SonaGetStudyStats?api_key=YOUR_API_KEY&experiment_id=14

URL components

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

Query parameters

api_key = YOUR_API_KEY
experiment_id = 14

Sample Output¶

<SonaGetStudyStatsResponse
  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">
  <SonaGetStudyStatsResult>
    <a:Errors i:nil="true" />
    <a:Result>
      <a:awaiting_action_count>3</a:awaiting_action_count>
      <a:credits_granted_total>7.00</a:credits_granted_total>
      <a:experiment_id>14</a:experiment_id>
      <a:noshow_count>1</a:noshow_count>
      <a:noshow_excused_count>2</a:noshow_excused_count>
      <a:noshow_unexcused_count>7</a:noshow_unexcused_count>
      <a:open_spaces_future>10</a:open_spaces_future>
      <a:open_spaces_past>0</a:open_spaces_past>
      <a:participated_count>5</a:participated_count>
      <a:study_name>Behavioral Study 1</a:study_name>
      <a:timeslot_count>3</a:timeslot_count>
    </a:Result>
  </SonaGetStudyStatsResult>
</SonaGetStudyStatsResponse>

Back to contents

SonaGetStudyStatsByDateRange

Description¶

This API retrieves basic usage information for a particular study, within a given date range. It’s similar to the Timeslot Usage Summary in the web interface.

Input Parameters¶

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

Parameter	Description / Possible Values
`api_key`	Use API key generated for Sona admin user
`experiment_id`	The `experiment_id` of the study. For multi-part studies, specify the `experiment_id` of the first part; results will be based on all parts of the study.
`start_date`	Date to use for beginning of listing. Date must be formatted as: YYYY-MM-DD.
`end_date`	Date to use for end of listing. Date must be formatted as: YYYY-MM-DD.

Output Parameters¶

Will return a single APIStudyStats result.

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	not a valid `experiment_id`
Error Code	Not supplied	`start_date` is not a valid date or is not properly formatted (must be YYYY-MM-DD)
Error Code	Not supplied	`end_date` is not a valid date or is not properly formatted (must be YYYY-MM-DD)
Error Code	Not supplied	`start_date` must the same as or earlier than `end_date`

Sample Input¶

Request URL

https://myschool.sona-systems.com/services/SonaAPI.svc/SonaGetStudyStatsByDateRange?api_key=YOUR_API_KEY&experiment_id=4&start_date=2016-01-01&end_date=2016-12-31

URL components

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

Query parameters

api_key = YOUR_API_KEY
experiment_id = 4
start_date = 2016-01-01
end_date = 2016-12-31

Sample Output¶

<SonaGetStudyStatsByDateRangeResponse
  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">
  <SonaGetStudyStatsByDateRangeResult>
    <a:Errors i:nil="true" />
    <a:Result>
      <a:awaiting_action_count>0</a:awaiting_action_count>
      <a:credits_granted_total>7.00</a:credits_granted_total>
      <a:experiment_id>4</a:experiment_id>
      <a:noshow_count>0</a:noshow_count>
      <a:noshow_excused_count>0</a:noshow_excused_count>
      <a:noshow_unexcused_count>0</a:noshow_unexcused_count>
      <a:open_spaces_future>0</a:open_spaces_future>
      <a:open_spaces_past>10</a:open_spaces_past>
      <a:participated_count>5</a:participated_count>
      <a:study_name>A Study On Dreams</a:study_name>
      <a:timeslot_count>3</a:timeslot_count>
    </a:Result>
  </SonaGetStudyStatsByDateRangeResult>
</SonaGetStudyStatsByDateRangeResponse>

Back to contents

SonaGetInstructorByClassID

Description¶

This API retrieves the user information for the Instructors assigned to a particular course. A course may have up to two instructors.

Input Parameters¶

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

Parameter	Description / Possible Values
`api_key`	Use API key generated for Sona admin user
`class_id`	The `class_id` of the course.

Output Parameters¶

Will return APIPerson 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
Invalid `class_id`	-8	not a valid `class_id`
Invalid `person_id`	-9	not a valid `person_id` (no instructors assigned to the course)

Sample Input¶

Request URL

https://myschool.sona-systems.com/services/SonaAPI.svc/SonaGetInstructorByClassID?api_key=YOUR_API_KEY&class_id=2

URL components

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

Query parameters

api_key = YOUR_API_KEY
class_id = 2

Sample Output¶

<SonaGetInstructorByClassIDResponse
  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">
  <SonaGetInstructorByClassIDResult>
    <a:Errors i:nil="true" />
    <a:Result>
      <a:APIPerson>
        <a:admin_comments />
        <a:alt_email>[email protected]</a:alt_email>
        <a:anon_id_code>32290</a:anon_id_code>
        <a:approved>1</a:approved>
        <a:birthdate>1975-07-20T00:00:00</a:birthdate>
        <a:classes_needed>0</a:classes_needed>
        <a:creation_date>0001-01-01T00:00:00</a:creation_date>
        <a:credits_earned>0</a:credits_earned>
        <a:credits_needed>3.00</a:credits_needed>
        <a:daily_reminder>0</a:daily_reminder>
        <a:email_needed>0</a:email_needed>
        <a:first_name>Victor</a:first_name>
        <a:hipaa_ack_date>0001-01-01T00:00:00</a:hipaa_ack_date>
        <a:hipaa_ack_date_nonp>0001-01-01T00:00:00</a:hipaa_ack_date_nonp>
        <a:language_pref>EN</a:language_pref>
        <a:last_login>2016-11-08T11:52:52</a:last_login>
        <a:last_name>Smith</a:last_name>
        <a:limit_date>0001-01-01T00:00:00</a:limit_date>
        <a:limit_type />
        <a:limited>0</a:limited>
        <a:login_allowed>1</a:login_allowed>
        <a:login_days>48</a:login_days>
        <a:login_sent_date>0001-01-01T00:00:00</a:login_sent_date>
        <a:noshow_count>0</a:noshow_count>
        <a:office />
        <a:password_change_needed>0</a:password_change_needed>
        <a:password_failed_count>0</a:password_failed_count>
        <a:person_id>9256</a:person_id>
        <a:person_type_a>0</a:person_type_a>
        <a:person_type_e>0</a:person_type_e>
        <a:person_type_i>1</a:person_type_i>
        <a:person_type_p>0</a:person_type_p>
        <a:person_type_pref>I</a:person_type_pref>
        <a:person_type_s>0</a:person_type_s>
        <a:phone>202-244-3993</a:phone>
        <a:pretest>0</a:pretest>
        <a:student_id_num>12345</a:student_id_num>
        <a:study_invitation>1</a:study_invitation>
        <a:usage_limit>0</a:usage_limit>
        <a:user_id>ints</a:user_id>
        <a:weekly_reminder>1</a:weekly_reminder>
      </a:APIPerson>
    </a:Result>
  </SonaGetInstructorByClassIDResult>
</SonaGetInstructorByClassIDResponse>

Back to contents

Returns users filtered by user type, login permission, and last recorded login date.

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

Parameter	Description / Possible Values
`api_key`	Use API key generated for Sona admin user
`person_type`	Possible values: A = admin \| E = researcher \| P = PI \| I = instructor \| S = student (participant) \| X = all
`login_allowed`	Possible values: 0 = login not allowed \| 1 = login allowed \| 2 = all users
`login_date`	User’s last login date. Date must be formatted as: YYYY-MM-DD.

Will return APIPerson class and display data in an array.

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	-8	`person_type` is missing or numeric. Use a documented letter code.
Error Code	-9	`login_allowed` is missing or non-numeric.
Error Code	-10	`login_date` is not a valid date. Use `YYYY-MM-DD`.

Request URL

https://myschool.sona-systems.com/services/SonaAPI.svc/SonaGetPersonListByLoginDate?api_key=YOUR_API_KEY&person_type=X&login_allowed=1&login_date=2017-08-30

URL components

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

Query parameters

api_key = YOUR_API_KEY
person_type = X
login_allowed = 1
login_date = 2017-08-30

<SonaGetPersonListByLoginDateResponse
  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">
  <SonaGetPersonListByLoginDateResult>
    <a:Errors i:nil="true" />
    <a:Result>
      <a:APIPerson>
        <a:admin_comments>comments go here</a:admin_comments>
        <a:alt_email>[email protected]</a:alt_email>
        <a:anon_id_code>32290</a:anon_id_code>
        <a:approved>1</a:approved>
        <a:birthdate>1975-07-20T00:00:00</a:birthdate>
        <a:classes_needed>0</a:classes_needed>
        <a:creation_date>2013-01-12T00:00:00</a:creation_date>
        <a:credits_earned>4.50</a:credits_earned>
        <a:credits_needed>4.00</a:credits_needed>
        <a:daily_reminder>1</a:daily_reminder>
        <a:email_needed>0</a:email_needed>
        <a:first_name>Jake</a:first_name>
        <a:hipaa_ack_date>2013-09-13T09:00:56</a:hipaa_ack_date>
        <a:hipaa_ack_date_nonp>0001-01-01T00:00:00</a:hipaa_ack_date_nonp>
        <a:language_pref>EN</a:language_pref>
        <a:last_login>2017-08-30T09:00:53</a:last_login>
        <a:last_name>Rogers</a:last_name>
        <a:limit_date>2013-03-15T08:35:05</a:limit_date>
        <a:limit_type />
        <a:limited>0</a:limited>
        <a:login_allowed>1</a:login_allowed>
        <a:login_days>16</a:login_days>
        <a:login_sent_date>2013-04-21T07:11:00</a:login_sent_date>
        <a:noshow_count>0</a:noshow_count>
        <a:office />
        <a:password_change_needed>0</a:password_change_needed>
        <a:password_failed_count>0</a:password_failed_count>
        <a:person_id>4321</a:person_id>
        <a:person_type_a>0</a:person_type_a>
        <a:person_type_e>0</a:person_type_e>
        <a:person_type_i>0</a:person_type_i>
        <a:person_type_p>0</a:person_type_p>
        <a:person_type_pref>S</a:person_type_pref>
        <a:person_type_s>1</a:person_type_s>
        <a:phone>867-5309</a:phone>
        <a:pretest>1</a:pretest>
        <a:student_id_num />
        <a:study_invitation>1</a:study_invitation>
        <a:usage_limit>500</a:usage_limit>
        <a:user_id>jake</a:user_id>
        <a:weekly_reminder>1</a:weekly_reminder>
      </a:APIPerson>
      <a:APIPerson>
        <a:admin_comments>comments go here</a:admin_comments>
        <a:alt_email>[email protected]</a:alt_email>
        <a:anon_id_code>32290</a:anon_id_code>
        <a:approved>1</a:approved>
        <a:birthdate>1975-07-20T00:00:00</a:birthdate>
        <a:classes_needed>0</a:classes_needed>
        <a:creation_date>2013-01-12T00:00:00</a:creation_date>
        <a:credits_earned>4.50</a:credits_earned>
        <a:credits_needed>4.00</a:credits_needed>
        <a:daily_reminder>1</a:daily_reminder>
        <a:email_needed>0</a:email_needed>
        <a:first_name>Miles</a:first_name>
        <a:hipaa_ack_date>2013-09-13T09:00:56</a:hipaa_ack_date>
        <a:hipaa_ack_date_nonp>0001-01-01T00:00:00</a:hipaa_ack_date_nonp>
        <a:language_pref>EN</a:language_pref>
        <a:last_login>2017-08-30T09:00:53</a:last_login>
        <a:last_name>Teller</a:last_name>
        <a:limit_date>2013-03-15T08:35:05</a:limit_date>
        <a:limit_type />
        <a:limited>0</a:limited>
        <a:login_allowed>1</a:login_allowed>
        <a:login_days>16</a:login_days>
        <a:login_sent_date>2013-04-21T07:11:00</a:login_sent_date>
        <a:noshow_count>0</a:noshow_count>
        <a:office />
        <a:password_change_needed>0</a:password_change_needed>
        <a:password_failed_count>0</a:password_failed_count>
        <a:person_id>1234</a:person_id>
        <a:person_type_a>0</a:person_type_a>
        <a:person_type_e>0</a:person_type_e>
        <a:person_type_i>0</a:person_type_i>
        <a:person_type_p>0</a:person_type_p>
        <a:person_type_pref>S</a:person_type_pref>
        <a:person_type_s>1</a:person_type_s>
        <a:phone>867-5309</a:phone>
        <a:pretest>1</a:pretest>
        <a:student_id_num />
        <a:study_invitation>1</a:study_invitation>
        <a:usage_limit>500</a:usage_limit>
        <a:user_id>miles</a:user_id>
        <a:weekly_reminder>1</a:weekly_reminder>
      </a:APIPerson>
    </a:Result>
  </SonaGetPersonListByLoginDateResult>
</SonaGetPersonListByLoginDateResponse>

Back to contents

SonaGetPersonListByCreationDate

Description¶

Returns users created on or after the specified date, including their user type and login permission.

Input Parameters¶

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

Parameter	Description / Possible Values
`api_key`	Use API key generated for Sona admin user
`person_type`	Possible values: A = admin \| E = researcher \| P = PI \| I = instructor \| S = student (participant) \| X = all
`login_allowed`	Possible values: 0 = login not allowed \| 1 = login allowed \| 2 = all users
`creation_date`	The date the users’ accounts were created on or after. Date must be formatted as: YYYY-MM-DD.

Output Parameters¶

Will return APIPerson 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	-8	`person_type` is missing or numeric. Use a documented letter code.
Error Code	-9	`login_allowed` is missing or non-numeric.
Error Code	-10	`creation_date` is not a valid date. Use `YYYY-MM-DD`.

Sample Input¶

Request URL

https://myschool.sona-systems.com/services/SonaAPI.svc/SonaGetPersonListByCreationDate?api_key=YOUR_API_KEY&person_type=S&login_allowed=1&creation_date=2017-01-01

URL components

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

Query parameters

api_key = YOUR_API_KEY
person_type = S
login_allowed = 1
creation_date = 2017-01-01

Sample Output¶

<SonaGetPersonListByCreationDateResponse
  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">
  <SonaGetPersonListByCreationDateResult>
    <a:Errors i:nil="true" />
    <a:Result>
      <a:APIPerson>
        <a:admin_comments>good student</a:admin_comments>
        <a:alt_email>[email protected]</a:alt_email>
        <a:anon_id_code>32290</a:anon_id_code>
        <a:approved>1</a:approved>
        <a:birthdate>1975-07-20T00:00:00</a:birthdate>
        <a:classes_needed>0</a:classes_needed>
        <a:creation_date>2017-01-01T00:00:00</a:creation_date>
        <a:credits_earned>4.50</a:credits_earned>
        <a:credits_needed>4.00</a:credits_needed>
        <a:daily_reminder>1</a:daily_reminder>
        <a:email_needed>0</a:email_needed>
        <a:first_name>William</a:first_name>
        <a:hipaa_ack_date>2013-09-13T09:00:56</a:hipaa_ack_date>
        <a:hipaa_ack_date_nonp>2017-01-01T00:00:00</a:hipaa_ack_date_nonp>
        <a:language_pref>EN</a:language_pref>
        <a:last_login>2013-09-13T09:00:53</a:last_login>
        <a:last_name>Bliss</a:last_name>
        <a:limit_date>2013-03-15T08:35:05</a:limit_date>
        <a:limit_type />
        <a:limited>0</a:limited>
        <a:login_allowed>1</a:login_allowed>
        <a:login_days>16</a:login_days>
        <a:login_sent_date>2013-04-21T07:11:00</a:login_sent_date>
        <a:noshow_count>0</a:noshow_count>
        <a:office />
        <a:password_change_needed>0</a:password_change_needed>
        <a:password_failed_count>0</a:password_failed_count>
        <a:person_id>1122</a:person_id>
        <a:person_type_a>0</a:person_type_a>
        <a:person_type_e>0</a:person_type_e>
        <a:person_type_i>0</a:person_type_i>
        <a:person_type_p>0</a:person_type_p>
        <a:person_type_pref>S</a:person_type_pref>
        <a:person_type_s>1</a:person_type_s>
        <a:phone>867-5309</a:phone>
        <a:pretest>1</a:pretest>
        <a:student_id_num />
        <a:study_invitation>1</a:study_invitation>
        <a:usage_limit>500</a:usage_limit>
        <a:user_id>william</a:user_id>
        <a:weekly_reminder>1</a:weekly_reminder>
      </a:APIPerson>
      <a:APIPerson>
        <a:admin_comments>average student</a:admin_comments>
        <a:alt_email>[email protected]</a:alt_email>
        <a:anon_id_code>32290</a:anon_id_code>
        <a:approved>1</a:approved>
        <a:birthdate>1975-07-20T00:00:00</a:birthdate>
        <a:classes_needed>0</a:classes_needed>
        <a:creation_date>2017-01-01T00:00:00</a:creation_date>
        <a:credits_earned>4.50</a:credits_earned>
        <a:credits_needed>4.00</a:credits_needed>
        <a:daily_reminder>1</a:daily_reminder>
        <a:email_needed>0</a:email_needed>
        <a:first_name>Henry</a:first_name>
        <a:hipaa_ack_date>2013-09-13T09:00:56</a:hipaa_ack_date>
        <a:hipaa_ack_date_nonp>2017-01-01T00:00:00</a:hipaa_ack_date_nonp>
        <a:language_pref>EN</a:language_pref>
        <a:last_login>2013-09-13T09:00:53</a:last_login>
        <a:last_name>McCormick</a:last_name>
        <a:limit_date>2013-03-15T08:35:05</a:limit_date>
        <a:limit_type />
        <a:limited>0</a:limited>
        <a:login_allowed>1</a:login_allowed>
        <a:login_days>16</a:login_days>
        <a:login_sent_date>2013-04-21T07:11:00</a:login_sent_date>
        <a:noshow_count>0</a:noshow_count>
        <a:office />
        <a:password_change_needed>0</a:password_change_needed>
        <a:password_failed_count>0</a:password_failed_count>
        <a:person_id>3344</a:person_id>
        <a:person_type_a>0</a:person_type_a>
        <a:person_type_e>0</a:person_type_e>
        <a:person_type_i>0</a:person_type_i>
        <a:person_type_p>0</a:person_type_p>
        <a:person_type_pref>S</a:person_type_pref>
        <a:person_type_s>1</a:person_type_s>
        <a:phone>867-5309</a:phone>
        <a:pretest>1</a:pretest>
        <a:student_id_num />
        <a:study_invitation>1</a:study_invitation>
        <a:usage_limit>500</a:usage_limit>
        <a:user_id>henry</a:user_id>
        <a:weekly_reminder>1</a:weekly_reminder>
      </a:APIPerson>
    </a:Result>
  </SonaGetPersonListByCreationDateResult>
</SonaGetPersonListByCreationDateResponse>

Back to contents

SonaGetStudyInfoByExperimentID

Description¶

This function returns all information pertaining to a study based on its experiment_id.

Input Parameters¶

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

Parameter	Description / Possible Values
`api_key`	Use API key generated for Sona admin user
`experiment_id`	The `experiment_id` of the study. In the case of a multi-part study, each part has a different `experiment_id`, but most data fields are the same for each part.

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
Invalid `experiment_id`	-8	`experiment_id` entered is invalid
Experiment_id not found	-9	`experiment_id` entered is not found

Sample Input¶

Request URL

https://myschool.sona-systems.com/services/SonaAPI.svc/SonaGetStudyInfoByExperimentID?api_key=YOUR_API_KEY&experiment_id=144

URL components

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

Query parameters

api_key = YOUR_API_KEY
experiment_id = 144

Sample Output¶

<SonaGetStudyInfoByExperimentIDResponse
  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">
  <SonaGetStudyInfoByExperimentIDResult>
    <a:Errors i:nil="true" />
    <a:Result>
      <a:APIStudyInfo>
        <a:active>1</a:active>
        <a:age_maximum>99.0</a:age_maximum>
        <a:age_minimum>0.0</a:age_minimum>
        <a:auto_credit_enable>1</a:auto_credit_enable>
        <a:cancel_limit>24</a:cancel_limit>
        <a:course_restrictions />
        <a:creation_date>2011-01-01T00:00:00</a:creation_date>
        <a:credits>2.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>2</a:exp_signup_email>
        <a:experiment_id>144</a:experiment_id>
        <a:experiment_url />
        <a:experimenter_timeslot>0</a:experimenter_timeslot>
        <a:has_multipart>1</a:has_multipart>
        <a:has_prereqs>0</a:has_prereqs>
        <a:has_rests>0</a:has_rests>
        <a:irb_code>12345678901</a:irb_code>
        <a:irb_expiration_date>2018-06-17T00:00:00</a:irb_expiration_date>
        <a:is_neg_req>0</a:is_neg_req>
        <a:last_activity>2017-09-04T12:25:41</a:last_activity>
        <a:last_timeslot>2017-08-30T10:30:00</a:last_timeslot>
        <a:long_desc>This is a study</a:long_desc>
        <a:multipart_exact>0</a:multipart_exact>
        <a:multipart_max_days>-1</a:multipart_max_days>
        <a:multipart_min_days>-1</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>9263</a:pi_id>
        <a:preparation>None</a:preparation>
        <a:prereq_any>0</a:prereq_any>
        <a:previously_approved>1</a:previously_approved>
        <a:private_comments>comments go here</a:private_comments>
        <a:restrictions>None</a:restrictions>
        <a:short_desc>This is a study</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>This is a study on Studies</a:study_name>
        <a:survey_anon_flag>0</a:survey_anon_flag>
        <a:survey_flag>0</a:survey_flag>
        <a:total_credits>8.00</a:total_credits>
        <a:total_parts>4</a:total_parts>
        <a:total_payment />
        <a:total_payment_numeric>0.00</a:total_payment_numeric>
        <a:type>C</a:type>
        <a:usage_limit>10</a:usage_limit>
        <a:valid>1</a:valid>
        <a:web_flag>0</a:web_flag>
      </a:APIStudyInfo>
    </a:Result>
  </SonaGetStudyInfoByExperimentIDResult>
</SonaGetStudyInfoByExperimentIDResponse>

Back to contents

SonaGetStudyListByResearcher

Description¶

This function returns a detailed list of studies managed by a particular researcher.

Input Parameters¶

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

Parameter	Description / Possible Values
`api_key`	Use API key generated for Sona admin user
`active`	-1=all; 0=not active only; 1=active only
`approved`	-1=all; 0=not approved only; 1=approved only
`web_flag`	-1=all; 0=lab studies only; 1=web studies only (internal online and external web)
`survey_flag`	-1=all; 0=all except online surveys; 1=online surveys only
`researcher_username`	researcher's username

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	`active` is missing or is not `-1`, `0`, or `1`.
Error Code	Not supplied	`approved` is missing or is not `-1`, `0`, or `1`.
Error Code	Not supplied	`web_flag` is missing or is not `-1`, `0`, or `1`.
Error Code	Not supplied	`survey_flag` is missing or is not `-1`, `0`, or `1`.
Error Code	Not supplied	`researcher_username` does not identify an existing researcher.
Error Code	Not supplied	No studies matched the supplied filters.

Sample Input¶

Request URL

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

URL components

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

Query parameters

api_key = YOUR_API_KEY
active = 1
approved = 1
web_flag = 1
survey_flag = 1
researcher_username = john_researcher

Sample Output¶

<SonaGetStudyListByResearcherResponse
  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">
  <SonaGetStudyListByResearcherResult>
    <a:Errors i:nil="true" />
    <a:Result>
      <a:APIStudyInfo>
        <a:active>1</a:active>
        <a:age_maximum>99.0</a:age_maximum>
        <a:age_minimum>0.0</a:age_minimum>
        <a:auto_credit_enable>1</a:auto_credit_enable>
        <a:cancel_limit>24</a:cancel_limit>
        <a:course_restrictions />
        <a:creation_date>2011-01-01T00:00:00</a:creation_date>
        <a:credits>2.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>2</a:exp_signup_email>
        <a:experiment_id>144</a:experiment_id>
        <a:experiment_url />
        <a:experimenter_timeslot>0</a:experimenter_timeslot>
        <a:has_multipart>1</a:has_multipart>
        <a:has_prereqs>0</a:has_prereqs>
        <a:has_rests>0</a:has_rests>
        <a:irb_code>12345678901</a:irb_code>
        <a:irb_expiration_date>2018-06-17T00:00:00</a:irb_expiration_date>
        <a:is_neg_req>0</a:is_neg_req>
        <a:last_activity>2017-09-04T12:25:41</a:last_activity>
        <a:last_timeslot>2017-08-30T10:30:00</a:last_timeslot>
        <a:long_desc>This is a study</a:long_desc>
        <a:multipart_exact>0</a:multipart_exact>
        <a:multipart_max_days>-1</a:multipart_max_days>
        <a:multipart_min_days>-1</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>9263</a:pi_id>
        <a:preparation>None</a:preparation>
        <a:prereq_any>0</a:prereq_any>
        <a:previously_approved>1</a:previously_approved>
        <a:private_comments>comments go here</a:private_comments>
        <a:restrictions>None</a:restrictions>
        <a:short_desc>This is a study</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>The Study Name Goes Here</a:study_name>
        <a:survey_anon_flag>0</a:survey_anon_flag>
        <a:survey_flag>1</a:survey_flag>
        <a:total_credits>8.00</a:total_credits>
        <a:total_parts>4</a:total_parts>
        <a:total_payment />
        <a:total_payment_numeric>0.00</a:total_payment_numeric>
        <a:type>C</a:type>
        <a:usage_limit>10</a:usage_limit>
        <a:valid>1</a:valid>
        <a:web_flag>1</a:web_flag>
      </a:APIStudyInfo>
    </a:Result>
  </SonaGetStudyListByResearcherResult>
</SonaGetStudyListByResearcherResponse>

Back to contents

SonaGetStudyListByPI

Description¶

This function returns a detailed list of studies managed by a particular PI.

Input Parameters¶

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

Parameter	Description / Possible Values
`api_key`	Use API key generated for Sona admin user
`active`	-1=all; 0=not active only; 1=active only
`approved`	-1=all; 0=not approved only; 1=approved only
`web_flag`	-1=all; 0=lab studies only; 1=web studies only (internal online and external web)
`survey_flag`	-1=all; 0=all except online surveys; 1=online surveys only
`pi_username`	principal investigator's username

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	`active` is missing or is not `-1`, `0`, or `1`.
Error Code	Not supplied	`approved` is missing or is not `-1`, `0`, or `1`.
Error Code	Not supplied	`web_flag` is missing or is not `-1`, `0`, or `1`.
Error Code	Not supplied	`survey_flag` is missing or is not `-1`, `0`, or `1`.
Error Code	Not supplied	`pi_username` does not identify an existing PI.
Error Code	Not supplied	No studies matched the supplied filters.

Sample Input¶

Request URL

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

URL components

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

Query parameters

api_key = YOUR_API_KEY
active = 1
approved = 1
web_flag = 1
survey_flag = 1
pi_username = john_pi

Sample Output¶

<SonaGetStudyListByPIResponse
  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">
  <SonaGetStudyListByPIResult>
    <a:Errors i:nil="true" />
    <a:Result>
      <a:APIStudyInfo>
        <a:active>1</a:active>
        <a:age_maximum>99.0</a:age_maximum>
        <a:age_minimum>0.0</a:age_minimum>
        <a:auto_credit_enable>1</a:auto_credit_enable>
        <a:cancel_limit>24</a:cancel_limit>
        <a:course_restrictions />
        <a:creation_date>2011-01-01T00:00:00</a:creation_date>
        <a:credits>2.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>2</a:exp_signup_email>
        <a:experiment_id>144</a:experiment_id>
        <a:experiment_url />
        <a:experimenter_timeslot>0</a:experimenter_timeslot>
        <a:has_multipart>1</a:has_multipart>
        <a:has_prereqs>0</a:has_prereqs>
        <a:has_rests>0</a:has_rests>
        <a:irb_code>12345678901</a:irb_code>
        <a:irb_expiration_date>2018-06-17T00:00:00</a:irb_expiration_date>
        <a:is_neg_req>0</a:is_neg_req>
        <a:last_activity>2017-09-04T12:25:41</a:last_activity>
        <a:last_timeslot>2017-08-30T10:30:00</a:last_timeslot>
        <a:long_desc>This is a study</a:long_desc>
        <a:multipart_exact>0</a:multipart_exact>
        <a:multipart_max_days>-1</a:multipart_max_days>
        <a:multipart_min_days>-1</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>9263</a:pi_id>
        <a:preparation>None</a:preparation>
        <a:prereq_any>0</a:prereq_any>
        <a:previously_approved>1</a:previously_approved>
        <a:private_comments>comments go here</a:private_comments>
        <a:restrictions>None</a:restrictions>
        <a:short_desc>This is a study</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>The Study Name Goes Here</a:study_name>
        <a:survey_anon_flag>0</a:survey_anon_flag>
        <a:survey_flag>1</a:survey_flag>
        <a:total_credits>8.00</a:total_credits>
        <a:total_parts>4</a:total_parts>
        <a:total_payment />
        <a:total_payment_numeric>0.00</a:total_payment_numeric>
        <a:type>C</a:type>
        <a:usage_limit>10</a:usage_limit>
        <a:valid>1</a:valid>
        <a:web_flag>1</a:web_flag>
      </a:APIStudyInfo>
    </a:Result>
  </SonaGetStudyListByPIResult>
</SonaGetStudyListByPIResponse>

Back to contents

SonaActivateUser

Description¶

This function activates a user’s inactive account. If the user’s account is already active, the function’s numeric output will indicate as such. This is the login_allowed field in the user’s account.

Input Parameters¶

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

Parameter	Description / Possible Values
`api_key`	Use API key generated for Sona admin user
`person_id`	The numeric identifier of the user.

Output Parameters¶

Will return an integer value of 1 indicating a successful activation, or 2 indicating that the user’s account is already activated.

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
Invalid `person_id`	-8	`person_id` entered is invalid
Person_id not found	-9	`person_id` entered is not found

Sample Input¶

Request URL

https://myschool.sona-systems.com/services/SonaAPI.svc/SonaActivateUser?api_key=YOUR_API_KEY&person_id=15

URL components

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

Query parameters

api_key = YOUR_API_KEY
person_id = 15

Sample Output¶

<SonaActivateUserResponse
  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">
  <SonaActivateUserResult>
    <a:Errors i:nil="true" />
    <a:Result>1</a:Result>
  </SonaActivateUserResult>
</SonaActivateUserResponse>

Back to contents

SonaCreateUser

Description¶

This function allows for the creation of a new user in the system by providing necessary details such as name, user ID, and person type.

Input Parameters¶

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

Parameter	Description / Possible Values
`api_key`	Use API key generated for Sona admin user
`first_name`	User’s first name
`last_name`	User’s last name
`user_id`	Unique identifier for the user. If an SSO user (`sso_user`=1), then this is the user’s SSO ID.
`person_type`	Possible values: E = researcher \| P = PI \| I = instructor \| S = participant
`sso_user`	Specifies if the user is an SSO user: 1 = yes \| 0 = no. Optional. Defaults to `0`.
`password`	User's password. Leave blank for auto-assigned password. Not applicable for SSO users. Optional.
`alt_email`	User’s alternate email address (or main email address, if @ suffix is not enabled in System Settings, or SSO user). Optional for non-SSO users when @ suffix is enabled.
`birthdate`	User's date of birth. YYYY-MM-DD format. Only applies to participants, only if date of birth features is enabled. Optional.
`phone`	User’s phone number. Optional.
`student_id_num`	User’s student ID/university ID number. Optional.
`office`	User’s office location. Only applies to non-participant users. Optional.
`admin_comments`	Comments seen by administrators only. Optional.
`course_list`	An optional comma-separated list of numeric course identifiers relevant only when `person_type` = "S" (Participant). If no valid courses are provided, the system flags the user as needing to choose courses on next login. This field is ignored for non-participants.
`login_allowed`	Is user allowed to log in? 0/1 value. Optional. Defaults to `1`.
`send_login_info`	Send login information to user by email. 1/0 value. Optional. Defaults to `0`.
`language_pref`	User's preferred language (2-char or 5-char abbreviation): EN = English, ZH = Simplified Chinese, JA = Japanese, KO = Korean, FR = French, PT = Portuguese, DE = German, etc. The default language for the system will be used if not specified. Only languages enabled on the site are allowed. Optional.

Output Parameters¶

Will return an integer value of the unique person_id of the newly created user, if successful.

When the site uses per-Researcher or per-P.I. timeslot usage limits, pass the returned person_id to SonaSetUserTimeslotUsageLimit to replace the site's default limit for the new user.

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
Invalid input parameter	-15	Input validation failures such as missing fields, invalid formats, or conflicts like duplicate IDs or unsupported configurations. Correct the input to resolve the issue before retrying.
Error adding user	-16	An unexpected issue occurred while processing your request, such as a system or database error. Please check the error message for details and contact support if the problem persists

Sample Input¶

Request URL

https://myschool.sona-systems.com/services/SonaAPI.svc/SonaCreateUser?api_key=YOUR_API_KEY&first_name=John&last_name=Doe&user_id=jdoe123&person_type=S&sso_user=0&password=password&alt_email=[email protected]&birthdate=1970-01-01&phone=123-456-7890&student_id_num=123456789&office=&admin_comments=New%20student%20enrollment&course_list=123,456&login_allowed=1&send_login_info=0&language_pref=EN

URL components

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

Query parameters

api_key = YOUR_API_KEY
first_name = John
last_name = Doe
user_id = jdoe123
person_type = S
sso_user = 0
password = password
alt_email = [email protected]
birthdate = 1970-01-01
phone = 123-456-7890
student_id_num = 123456789
office =
admin_comments = New%20student%20enrollment
course_list = 123,456
login_allowed = 1
send_login_info = 0
language_pref = EN

Sample Output¶

<SonaCreateUserResponse
  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">
  <SonaCreateUserResult>
    <a:Errors i:nil="true" />
    <a:Result>42</a:Result>
  </SonaCreateUserResult>
</SonaCreateUserResponse>

Back to contents

SonaDeactivateUser

Description¶

This function deactivates a user’s active account. If the user’s account is already deactivated, the function’s numeric output will indicate as such. This is the login_allowed field in the user’s account.

Input Parameters¶

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

Parameter	Description / Possible Values
`api_key`	Use API key generated for Sona admin user
`person_id`	The numeric identifier of the user.

Output Parameters¶

Will return an integer value of 1 indicating a successful deactivation, or 2 indicating that the user’s account is already deactivated.

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
Invalid `person_id`	-8	`person_id` entered is invalid
Person_id not found	-9	`person_id` entered is not found

Sample Input¶

Request URL

https://myschool.sona-systems.com/services/SonaAPI.svc/SonaDeactivateUser?api_key=YOUR_API_KEY&person_id=15

URL components

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

Query parameters

api_key = YOUR_API_KEY
person_id = 15

Sample Output¶

<SonaDeactivateUserResponse
  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">
  <SonaDeactivateUserResult>
    <a:Errors i:nil="true" />
    <a:Result>1</a:Result>
  </SonaDeactivateUserResult>
</SonaDeactivateUserResponse>

Back to contents

SonaApproveUser

Description¶

This function approves a participant’s user account. If the user’s account is already approved, the function’s numeric output will indicate as such. This is the approved field in the user’s account, and only applies if Automatic Account Approval is turned off in System Settings. Unlike approving a user from the Approve Users page, this function does not send the user an email that their account has been approved.

Input Parameters¶

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

Parameter	Description / Possible Values
`api_key`	Use API key generated for Sona admin user
`person_id`	The numeric identifier of the user.

Output Parameters¶

Will return an integer value of 1 indicating a successful approval, or 2 indicating that the user’s account is already approved.

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
Invalid `person_id`	-8	`person_id` entered is invalid
Person_id not found	-9	`person_id` entered is not found

Sample Input¶

Request URL

https://myschool.sona-systems.com/services/SonaAPI.svc/SonaApproveUser?api_key=YOUR_API_KEY&person_id=18

URL components

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

Query parameters

api_key = YOUR_API_KEY
person_id = 18

Sample Output¶

<SonaApproveUserResponse
  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">
  <SonaApproveUserResult>
    <a:Errors i:nil="true" />
    <a:Result>2</a:Result>
  </SonaApproveUserResult>
</SonaApproveUserResponse>

Back to contents

SonaMergeUser

Description¶

This function merges one user account into another. Associated records and roles are transferred from person_id_to_remove to person_id_to_keep, and the account identified by person_id_to_remove is then deleted. The merge is allowed only when both accounts exist, the person IDs are different, and the users have no roles in common. For example, two participants or two administrators cannot be merged.

Input Parameters¶

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

Parameter	Description / Possible Values
`api_key`	Use API key generated for Sona admin user
`person_id_to_keep`	Numeric identifier of the account that remains and receives the other account’s data and roles.
`person_id_to_remove`	Numeric identifier of the account whose data and roles are transferred. This account is deleted after a successful merge.

Output Parameters¶

Returns integer value 1 when the users are merged successfully.

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
Invalid `person_id`	-8	`person_id_to_keep` or `person_id_to_remove` entered is invalid
User not found	-9	`person_id_to_keep` or `person_id_to_remove` entered is not found
Merge failed	-15	The users could not be merged
Same user	-16	`person_id_to_keep` and `person_id_to_remove` refer to the same user
Conflicting roles	-17	The users have one or more roles in common. The error message lists the conflicting role codes: A = admin \| E = researcher \| I = instructor \| P = PI \| S = participant. P may also be returned when `person_id_to_remove` has the PI role and the PI feature is disabled.

Sample Input¶

Request URL

https://myschool.sona-systems.com/services/SonaAPI.svc/SonaMergeUser?api_key=YOUR_API_KEY&person_id_to_keep=15&person_id_to_remove=27

URL components

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

Query parameters

api_key = YOUR_API_KEY
person_id_to_keep = 15
person_id_to_remove = 27

Sample Output¶

<SonaMergeUserResponse
  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">
  <SonaMergeUserResult>
    <a:Errors i:nil="true" />
    <a:Result>1</a:Result>
  </SonaMergeUserResult>
</SonaMergeUserResponse>

Back to contents

SonaSetUserTimeslotUsageLimit

Description¶

This function sets the Study Time Usage Limit, in participant-hours, for an existing user. It is available only when the site is configured for per-Researcher or per-P.I. timeslot usage limits and the user has the role required by that configuration.

When the site uses per-Researcher limits, the user must have the Researcher role. When the site uses per-P.I. limits, the user must have the P.I. role. Multi-role users are eligible when they have the role required by the site's configured mode. The request is rejected when usage limits are disabled or configured per study.

The function updates only the user's usage limit. A limit may be set below the user's current usage. Existing timeslots and previously calculated usage are not changed, and subsequent operations remain subject to normal quota enforcement. The updated value is returned as usage_limit by person-information functions that return APIPerson.

This function can be called after SonaCreateUser to replace the site's default limit for the newly created user.

Input Parameters¶

Below are the input parameters for use with the SonaSetUserTimeslotUsageLimit API function.

Parameter	Description / Possible Values
`api_key`	API key generated for a Sona administrator. Required.
`person_id`	Positive numeric identifier of the user whose limit will be updated. Required.
`usage_limit`	New usage limit in participant-hours. Must be a non-negative whole number. Decimals and negative values are invalid. Required.

Output Parameters¶

Will return an integer value of 1 when the usage limit is updated, or 2 when the requested limit is already set and no update is required.

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	-8	`person_id` must be a positive integer.
Error Code	-9	No user exists with the supplied `person_id`.
Error Code	-10	`usage_limit` must be a non-negative integer.
Error Code	-11	The site is not configured for per-Researcher or per-P.I. timeslot usage limits.
Error Code	-12	The user does not have the role required by the site's timeslot usage limit setting.

Sample Input¶

Request URL

https://myschool.sona-systems.com/services/SonaAPI.svc/SonaSetUserTimeslotUsageLimit?api_key=YOUR_API_KEY&person_id=15&usage_limit=10

URL components

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

Query parameters

api_key = YOUR_API_KEY
person_id = 15
usage_limit = 10

Sample Output¶

<SonaSetUserTimeslotUsageLimitResponse
  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">
  <SonaSetUserTimeslotUsageLimitResult>
    <a:Errors i:nil="true" />
    <a:Result>1</a:Result>
  </SonaSetUserTimeslotUsageLimitResult>
</SonaSetUserTimeslotUsageLimitResponse>

Back to contents

SonaSetUserAdminComments

Description¶

Appends, replaces, or deletes a user's administrator comments (admin_comments). Comments have a 500-character limit. Deleting comments removes the stored text. Returns a numeric value indicating the result.

Input Parameters¶

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

Parameter	Description / Possible Values
`api_key`	Use API key generated for Sona admin user
`person_id`	The numeric identifier of the user.
`action`	The action to be taken. D = delete \| A = append \| O = overwrite/add
`comments`	The text comment to be added or appended. Ignored if action=D

Output Parameters¶

On success, Result contains one of the following positive integers. On failure, check the messages in Errors. Negative error codes appear in those messages, not in Result.

Type	Return Value	Description
Success Code	1	The comment has been added or the previous comment overwritten.
Success Code	2	The comment has been added or the previous comment overwritten, but some characters were stripped off due to length limits.
Success Code	3	The comment has been appended.
Success Code	4	The comment has been appended, but some characters were stripped off due to length limits.
Success Code	5	The comment has been deleted.

Error Codes¶

When an error occurs, Errors contains the error message and Result remains 0.

Error Type	Error Code	Description
Authentication Failed	-1 through -7	Standard authentication errors
Error Code	-8	An invalid `person_id` was used.
Error Code	-9	No matching user was found.
Error Code	-10	An invalid action.

Sample Input¶

Request URL

https://myschool.sona-systems.com/services/SonaAPI.svc/SonaSetUserAdminComments?api_key=YOUR_API_KEY&person_id=15&action=O&comments=place%20comment%20here

URL components

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

Query parameters

api_key = YOUR_API_KEY
person_id = 15
action = O
comments = place comment here

Sample Output¶

<SonaSetUserAdminCommentsResponse
  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">
  <SonaSetUserAdminCommentsResult>
    <a:Errors i:nil="true" />
    <a:Result>1</a:Result>
  </SonaSetUserAdminCommentsResult>
</SonaSetUserAdminCommentsResponse>

Back to contents

SonaAddUserRole

Description¶

This function adds a role to an existing user. If the user already has the requested role, no duplicate assignment is created.

Input Parameters¶

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

Parameter	Description / Possible Values
`api_key`	Use API key generated for Sona admin user
`person_id`	Numeric identifier of the user whose role will be changed.
`role`	Uppercase role code to add: E = Researcher P = Principal Investigator I = Instructor S = Participant

The Administrator role (A) cannot be added through this function. The Principal Investigator role (P) can be added only when the PI feature is enabled for the site.

Output Parameters¶

The function returns an integer result.

Type	Return Value	Description
Success	1	The role was added.
No change	2	The user already had the requested role. No duplicate assignment was created.
Authentication Failed	-1 through -7	Standard authentication errors.
Error	-9	User not found.
Error	-10	Invalid role.
Error	-11	The PI feature is not enabled.
Error	-15	The role could not be added.

Sample Input¶

Request URL

https://myschool.sona-systems.com/services/SonaAPI.svc/SonaAddUserRole?api_key=YOUR_API_KEY&person_id=15&role=E

URL components

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

Query parameters

api_key = YOUR_API_KEY
person_id = 15
role = E

Sample Output¶

<SonaAddUserRoleResponse
  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">
  <SonaAddUserRoleResult>
    <a:Errors i:nil="true" />
    <a:Result>1</a:Result>
  </SonaAddUserRoleResult>
</SonaAddUserRoleResponse>

Back to contents

SonaRemoveUserRole

Description¶

This function removes a role from an existing user. If the user does not have the requested role, no change is made.

Warning

Removing a role may be blocked when it would remove participant signups, affect studies managed by the user, or leave the user without any role. Review the returned result and error message before treating the operation as successful.

Input Parameters¶

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

Parameter	Description / Possible Values
`api_key`	Use API key generated for Sona admin user
`person_id`	Numeric identifier of the user whose role will be changed.
`role`	Uppercase role code to remove: E = Researcher P = Principal Investigator I = Instructor S = Participant

The Administrator role (A) cannot be removed through this function.

Output Parameters¶

The function returns an integer result.

Type	Return Value	Description
Success	1	The role was removed.
No change	3	The user did not have the requested role.
Authentication Failed	-1 through -7	Standard authentication errors.
Error	-9	User not found.
Error	-10	Invalid role.
Error	-11	The PI feature is not enabled.
Error	-12	Removing the participant role would remove existing study signups. The error message includes the affected signup count.
Error	-13	Removing the role would affect studies managed by the user and may delete associated studies. The error message includes the affected signup count.
Error	-14	The requested role is the user's only remaining role. Delete the user instead.
Error	-15	The role could not be removed or another unclassified error occurred.

Sample Input¶

Request URL

https://myschool.sona-systems.com/services/SonaAPI.svc/SonaRemoveUserRole?api_key=YOUR_API_KEY&person_id=15&role=E

URL components

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

Query parameters

api_key = YOUR_API_KEY
person_id = 15
role = E

Sample Output¶

<SonaRemoveUserRoleResponse
  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">
  <SonaRemoveUserRoleResult>
    <a:Errors i:nil="true" />
    <a:Result>1</a:Result>
  </SonaRemoveUserRoleResult>
</SonaRemoveUserRoleResponse>

Back to contents

WebstudyCredit

Description¶

WebstudyCredit processes the server-side completion URL for an external online study. It grants the study's credit or records participation for a paid study. The participant must have a signup that is awaiting action. Internal online survey studies are not supported.

Use the server-side completion URL generated in the study information page. It contains the study's experiment_id and credit_token. Your survey software must replace the survey_code placeholder with the participant's survey code when they complete the study. Keep the credit_token private because it authorizes completion requests for the study.

This function does not use an administrator api_key. The generated completion URL uses HTTP GET. HTTP POST is also supported with the same fields in a JSON request body. Include the User-Agent header as described in Request Requirements.

For survey setup instructions, see Server-Side Completion URL Responses.

Input Parameters¶

The following input parameters are required for the WebstudyCredit API function.

Parameter	Description / Possible Values
`experiment_id`	Numeric ID of the external online study. Use the value in the generated completion URL.
`credit_token`	Study-specific token from the generated completion URL. This is different from an administrator API key.
`survey_code`	Numeric survey code for the participant who completed the study. Pass the code provided to the survey software by Sona. Do not substitute a signup ID or assume the code is a person ID.

Output Parameters¶

Returns one APISignup result on success. The result contains signup_id, survey_code, credit_status, signup_date, and link_click_date. Personal information such as the participant's name, email, and user ID is not populated by this function. Other fields can be empty or contain default values.

Check that Errors is empty and Result is present. A credit_status of G indicates that credit was granted or participation was recorded. An error response contains messages in Errors instead of a signup result. HTTP status 200 alone does not indicate success.

Error Codes¶

Errors are returned as messages containing a numeric code. The standard administrator authentication errors do not apply to this function.

Error Type	Error Code	Description
Error Code	-2	`experiment_id` is missing or non-numeric, `credit_token` is missing, or the study and token do not identify an external online study.
Error Code	-3	The participant has already received credit for the study.
Error Code	-4	The participant has already been marked as participated for the paid study.
Error Code	-5	The participant's signup is not eligible for completion, such as a signup marked as a no-show.
Error Code	-6	`survey_code` is missing, non-numeric, or does not identify a participant signup for this study.
Error Code	-7	The completion URL was tested with an administrator, researcher, or principal investigator account. The response message is `Unspecified Error`. Test the full completion flow with a participant account.

Sample Input¶

Request URL

https://myschool.sona-systems.com/services/SonaAPI.svc/WebstudyCredit?experiment_id=123&credit_token=STUDY_CREDIT_TOKEN&survey_code=12345

URL components

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

Query parameters

experiment_id = 123
credit_token = STUDY_CREDIT_TOKEN
survey_code = 12345

STUDY_CREDIT_TOKEN and the numeric IDs above are examples. Use the study token and participant survey code from your integration.

Sample Output¶

<WebstudyCreditResponse
  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">
  <WebstudyCreditResult>
    <a:Errors i:nil="true" />
    <a:Result>
      <a:anon_id_code i:nil="true" />
      <a:credit_status>G</a:credit_status>
      <a:email i:nil="true" />
      <a:first_name i:nil="true" />
      <a:last_name i:nil="true" />
      <a:link_click_date>2026-10-15T09:00:00</a:link_click_date>
      <a:occur_date>0001-01-01T00:00:00</a:occur_date>
      <a:phone i:nil="true" />
      <a:signup_date>2026-10-15T08:30:00</a:signup_date>
      <a:signup_id>456</a:signup_id>
      <a:student_id_num i:nil="true" />
      <a:survey_code>12345</a:survey_code>
      <a:user_id i:nil="true" />
    </a:Result>
  </WebstudyCreditResult>
</WebstudyCreditResponse>

Back to contents

API data classes

APICourse: Information about a course.
APICreditItem: Represents one credit record, including participant, study, and payment information.
APISignup: Represents one participant's signup for a study timeslot.
APIStudySchedule: Represents one study timeslot in a schedule or timeslot listing.
APIStudyInfo: General information about a study.
APIPrescreenSurveyData: Information about one participant's set of responses to a prescreen or online survey.
APIPrescreenSurveyResponseItem: One participant's response to one question. Multiple selections produce separate records.
APIPerson: Represents one user and their account details.
APIParticipantStats: Participant credit-completion statistics, primarily based on the Credit Completion Report.
APIStudyStats: Study timeslot-usage statistics, primarily based on the Timeslot Usage Summary.

Back to contents

APICourse

Information about a course.

Data Field	Data Type	Description
class_id	Int32	the numeric identifier of the course
class_name	String	the course’s name
instructor_id	Int32	The instructor’s person ID. 0 means no instructor selected
instructor_id2	Int32	A second instructor’s person ID, if applicable. 0 means no instructor selected
credits_required	Decimal	The number of credits required for the course.
selectable	Int32	possible values: 0 = participants cannot select this course \| 1 = participants can select this course

Back to contents

APICreditItem

Represents one credit record, including participant, study, and payment information. A function may return one record or an array of records.

Data Field	Data Type	Description
signup_id	Int32	the numeric identifier of the sign-up
first_name	String	the participant’s first name
last_name	String	the participant’s last name
student_id_num	String	the participant’s student ID number (if available)
credit_id	Int32	the unique numeric identifier of the credit record
user_id	String	the participant’s user ID
email	String	the participant’s email address
person_id	Int32	the numeric identifier of the participant
date_granted	Date	the date when the credit was granted
occur_date	Date	the date and time when the study is to occur
show_credit	Decimal	the credit value granted to the participant
penalty_credit	Decimal	the credit value penalized from the participant
credit_type	String	possible values: G = credit granted \| W = awaiting action \| E = excused no-show \| I = unexcused no-show
payment_amount	Decimal	the payment amount associated with this credit record
payment_status	String	the single-character payment status for this credit record
payment_status_last_updated	Date	the date and time when the payment status was last updated. If no date has been recorded, the API returns `0001-01-01T00:00:00`.
manual_credit_flag	Int32	possible values: 0 = system-granted \| 1 = admin-granted
comments	String	comments pertaining to the credit grant
experiment_id	Int32	the numeric identifier of the study
grantor_id	Int32	the numeric identifier of the researcher who granted credit
class_id	Int32	the numeric identifier of the course

The payment fields are returned for every credit record, including manual credits, credit studies, and unmanaged paid studies.

Payment Status Codes¶

Code	Status	Description
`W`	Waiting	The payment has not yet been earned or is not payable.
`E`	Earned	The payment has been earned and is pending payment.
`C`	Awaiting Payment Confirmation	The payment has been included in a payment batch.
`P`	Paid	The payment has been paid.

Cancelling a payment batch returns its associated credits to E (Earned). For this field, C means Awaiting Payment Confirmation, not Cancelled.

Back to contents

Represents one participant's signup for a study timeslot. A function may return one signup or an array of signups.

Data Field	Data Type	Description
signup_id	Int32	the numeric identifier of the sign-up
first_name	String	the participant’s first name
last_name	String	the participant’s last name
student_id_num	String	the participant’s student ID number (if available)
phone	String	the participant’s phone number (if available)
user_id	String	the participant’s user ID
email	String	the participant’s email address
anon_id_code	String	will apply only when Anonymous ID codes are enabled, otherwise blank
survey_code	String	will apply only when survey_code is used for an external web study, otherwise blank
credit_status	String	possible values: G = credit granted \| W = awaiting action \| N = no-show
signup_date	Date	the date the participant signed up for the study
link_click_date	Date	the date when the participant clicked the study link. Applies to external web studies and videoconference timeslots only.
occur_date	Date	the date and time when the study is to occur

Back to contents

APIStudySchedule

Represents one study timeslot in a schedule or timeslot listing. Schedule functions return an array of these records.

Data Field	Data Type	Description
experiment_id	Int32	the numeric identifier of the study
timeslot_id	Int32	the numeric identifier of the timeslot
study_name	String	the name of the study
location	String	the location of the study
timeslot_date	Date	the date and time when the study is to occur
duration	Int32	the duration (in minutes) of the study. Add this to timeslot_date to find end time for the timeslot.
web_flag	Int32	0 = standard (lab) study \| 1 = internal online survey or external web study
survey_flag	Int32	0 = standard (lab) or external web study \| 1 = internal online survey
num_signed_up	Int32	the total number of participants signed up for this timeslot
num_students	Int32	the total number of participants allowed for this timeslot. This is basically the number set when the timeslot is created (its capacity), and is not reduced when participants sign up for the timeslot.
researcher_id	Int32	the numeric identifier for the researcher assigned to this particular timeslot, if applicable. If not applicable, then this value will be 0. This will be set to a non-zero value when all of the following are true: Study has multiple researchers. Study is configured to allow researchers at timeslot-level. A particular researcher is assigned to this timeslot.
videoconf_flag	Int32	0 = not a videoconference (default) \| 1 = videoconference
videoconf_url	String	the URL of the videoconference

Back to contents

APIStudyInfo

General information about a study.

Data Field	Data Type	Description
experiment_id	Int32	the numeric identifier of the study
study_name	String	the name of the study
short_desc	String	the short description of the study
long_desc	String	the long description of the study
private_comments	String	admin-only comments
restrictions	String	participant-facing eligibility requirements for the study
pi_id	Int32	the numeric identifier of the PI
duration	Int32	duration (in mins.) of the study
preparation	String	participant-facing instructions describing any preparation required for the study
credits	Decimal	the credits for this part of the study (0 if a paid study)
type	String	the study’s compensation type: C = credit study \| M = paid study
exp_pay_managed	Int32	whether the study uses managed payments: 1 = managed by Sona \| 0 = not managed by Sona
valid	Int32	1 = valid \| 0 = invalid
previously_approved	Int32	indicates whether the study was previously approved
active	Int32	1 = active \| 0 = inactive
exp_signup_email	Int32	0 = no researcher email notifications \| 1 = sign-up and cancellation notifications \| 2 = cancellation notifications only
has_prereqs	Int32	1 = study has one or more prerequisite studies \| 0 = no prerequisite studies
has_rests	Int32	1 = study has prescreen participation restrictions \| 0 = no prescreen participation restrictions
is_neg_req	Int32	1 = study is used as a disqualifier for another study \| 0 = not used as a disqualifier
prereq_any	Int32	0 = participant must satisfy all prerequisite studies \| 1 = participant must satisfy at least one prerequisite study
neg_req_any	Int32	Returned but not used.
course_restrictions	String	comma-delimited list of numeric course IDs allowed to participate; empty if there are no course restrictions
last_timeslot	Date	the last timeslot for the study
double_signup_flag	Int32	1 = duplicate signups allowed \| 0 = no duplicate signups
signup_password	String	the invitation code
web_flag	Int32	0 = standard (lab) study \| 1 = internal online survey or external web study
survey_flag	Int32	0 = standard (lab) or external web study \| 1 = internal online survey
survey_anon_flag	Int32	1 = internal online survey responses are anonymous \| 0 = responses are not anonymous
experiment_url	String	the URL for the external study
irb_code	String	the IRB code
irb_expiration_date	Date	the IRB expiration date
has_multipart	Int32	1 = multipart study \| 0 = non-multipart study
multipart_exact	Int32	0 = can occur at any time compared to previous part \| 1 = must occur at same time as previous part
multipart_number	Int32	represents which part, of a multipart study, the study belongs to
parent_experiment_id	Int32	`0` for a single-part study or the first part of a multipart study. Otherwise, the `experiment_id` of part 1.
multipart_min_days	Int32	the minimum number of days of separation between this part of the study and the previous part (applies to multipart studies only)
multipart_max_days	Int32	the maximum number of days of separation between this part of the study and the previous part (applies to multipart studies only)
total_parts	Int32	the number of parts the study has
total_credits	Decimal	total credits for the entire study. Will be the same as the credits field, except in cases of multi-part studies. 0 for paid studies.
usage_limit	Int32	timeslot usage limit (quota) for study, in hours
signup_limit	Int32	signup deadline (in hours)
cancel_limit	Int32	cancellation deadline (in hours)
auto_credit_enable	Int32	1 = auto crediting enabled \| 0 = disabled
experimenter_timeslot	Int32	1 = researchers can be assigned at timeslot-level.
show_participants	Int32	(not implemented)
study_alternative	Int32	1 = research alternative \| 0 = not a research alternative
creation_date	Date	date when study was created. May be empty for older studies.
last_activity	Date	date when the study last underwent any changes
payment	String	display payment value for this study part; empty for credit studies
payment_numeric	Decimal	numeric payment amount for this study part; 0 for credit studies
total_payment	String	display value of the total payment across all parts of a multipart study; empty for credit studies
total_payment_numeric	Decimal	numeric total payment amount across all parts of a multipart study; 0 for credit studies
age_minimum	Decimal	Minimum age to sign up for the study. 0 = no age limits.
age_maximum	Decimal	Maximum age to sign up for the study. Ignore if age_minimum=0.

Back to contents

APIPrescreenSurveyData

Information about one participant's set of responses to a prescreen or online survey.

Data Field	Data Type	Description
pretest_id	Int32	the numeric identifier of the prescreen
person_id	Int32	the numeric identifier of the participant
start_time	Date	the start time of the prescreen/study
end_time	Date	the end time of the prescreen/study
status	String	completion status. Possible values: C = completed \| W = withdrew \| I = in progress
data_status	String	status of response data. Possible values: D = data deleted \| S = stored on system
first_name	String	the first name of the participant
last_name	String	the last name of the participant
user_id	String	the participant’s user ID
anon_id_code	String	applies only when Anonymous ID codes are enabled, otherwise blank
responses	Array	the participant’s responses to this prescreen/survey, an array of `APIPrescreenSurveyResponseItem` items

Back to contents

APIPrescreenSurveyResponseItem

One participant's response to one question. Multiple selections produce separate records.

Data Field	Data Type	Description
response_id	Int32	the unique identifier for the response
question_id	Int32	the question this is a response for
choice_id	Int32	the choice chosen
response_text	String	the text representation of the response
response_numeric	Decimal	the numeric representation of the response (applies to numeric questions only)
opt_out_choice	Int32	1 = response was to opt out of the question \| 0 = opted in

Back to contents

APIPerson

Represents one user and their account details. Refer to each function's output description for the number of users returned.

Data Field	Data Type	Description
person_id	Int32	the person_id of the user
first_name	String	the user’s first name
last_name	String	the user’s last name
user_id	String	the user’s user ID
anon_id_code	String	applies only when Anonymous ID codes are enabled, otherwise blank
student_id_num	String	the user’s student ID number (if available)
phone	String	the user’s phone number (if available)
office	String	the user’s office location (if available)
alt_email	String	the user’s alternate email address (or main email address, if @ Suffix is not enabled in System Settings)
person_type_a	Int32	possible values: 1 = admin \| 0 = not an admin
person_type_e	Int32	possible values: 1 = researcher \| 0 = not a researcher
person_type_p	Int32	possible values: 1 = PI \| 0 = not a PI
person_type_i	Int32	possible values: 1 = instructor \| 0 = not an instructor
person_type_s	Int32	possible values: 1 = student (participant) \| 0 = not a student (participant)
person_type_pref	String	possible values: A = admin \| E = researcher \| P = PI \| I = instructor \| S = student (participant)
credits_earned	Decimal	the total credits earned by the participant
credits_needed	Decimal	the total credits needed (requirements) by the participant
pretest	Int32	Whether the participant has completed the prescreen. possible values: 0 = prescreen not taken \| 1 = prescreen completed \| 2 = opted out \| 3 = currently taking prescreen
login_allowed	Int32	possible values: 0 = login not allowed \| 1 = login allowed
approved	Int32	possible values: 0 = account not approved \| 1 = account approved
admin_comments	String	comments seen by administrators only
hipaa_ack_date	Date	the date when the participant acknowledged privacy policy
hipaa_ack_date_nonp	Date	the date when the non-participant user role acknowledged privacy policy
login_sent_date	Date	the date when the user's login info was last sent
daily_reminder	Int32	possible values: 0 = no daily reminders \| 1 = receives daily reminders
weekly_reminder	Int32	possible values: 0 = no weekly reminders \| 1 = receives weekly reminders
study_invitation	Int32	possible values: 0 = no study invitations \| 1 = receives study invitations
classes_needed	Int32	possible values: 0 = already in at least one course \| 1 = needs to join a course
email_needed	Int32	possible values: 0 = email not needed \| 1 = email needed (currently not implemented)
password_change_needed	Int32	possible values: 0 = password change not required \| 1 = password change required on next login
password_failed_count	Int32	the number of failed password login attempts
last_login	Date	the user's last login date
creation_date	Date	the date when the user's account was created (if available)
login_days	Int32	the number of unique days the user has logged into the system
noshow_count	Int32	the number of unexcused no-shows accrued
limited	Int32	possible values: 0 = not limited to research alternatives \| 1 = limited to research alternatives
limit_date	Date	the date when the participant’s account was limited
limit_type	String	possible values: M = manual (administrator set the limit) \| A = automatic (limit was set based on no-show accrual)
language_pref	String	The user's preferred language code. Examples include `EN` = English, `ZH` = Simplified Chinese, `ZH-TW` = Traditional Chinese, `JA` = Japanese, `KO` = Korean, `FR` = French, `PT` = Brazilian Portuguese, and `DE` = German.
birthdate	Date	the date when the user was born
usage_limit	Int32	Study Time Usage Limit for this user, in participant-hours.

Back to contents

APIParticipantStats

Participant credit-completion statistics, primarily based on the Credit Completion Report.

Data Field	Data Type	Description
class_id	Int32	the class_id of the course (0 if for all courses together)
class_name	String	the name of the course (blank if no course specified)
complete_total	Int32	total participants where their overall credits_earned >= overall credits_needed
incomplete_total	Int32	total participants where overall credits_earned < overall credits_needed
no_signups_total	Int32	total participants with no study signups at all
no_login_total	Int32	total participants who have never logged in
login_total	Int32	total who have logged in
overall_credits_earned_total	Decimal	sum of overall credits_earned
overall_credits_needed_total	Decimal	sum of overall credits_needed
course_credits_earned_total	Decimal	sum of credits earned for course, net of no-show penalties [only if course specified]

Back to contents

APIStudyStats

Study timeslot-usage statistics, primarily based on the Timeslot Usage Summary.

Data Field	Data Type	Description
experiment_id	Int32	the experiment_id of the study
study_name	String	the name of the study
timeslot_count	Int32	total number of timeslots (number of timeslot_id's)
noshow_unexcused_count	Int32	total number of unexcused no-shows
noshow_excused_count	Int32	total number of excused no-shows
noshow_count	Int32	total number of no-shows (sum of noshow_unexcused_count and noshow_excused_count)
awaiting_action_count	Int32	total number of sign-ups in awaiting action status
participated_count	Int32	total number of sign-ups with participation marked (credit granted)
credits_granted_total	Decimal	total number of credits granted (credit studies only and does not include no-show penalties)
open_spaces_future	Int32	total number of open spaces in timeslots in the future (within date range, when specified)
open_spaces_past	Int32	total number of open spaces in timeslots in the past (within date range, when specified)

Back to contents

Revision history

Date of Change	Summary of Change
15 February 2022	Added revision history Added new API functions: `GetPersonListByClassID`, `GetCoursesByPersonID`, `GetPersonInfoByStudentID`, `GetPersonInfoByName`, `GrantCreditBySignupID`, `ConvertUserToSSOByPersonID`, `ConvertUserToSSOByUserID` Added example of POSTing with Curl Formatting updates
25 April 2022	Formatting updates
29 January 2023	Added direct WSDL reference Updated sample output for Decimal fields (credit value fields) Updated any reference to HTTP calls to HTTPS
9 March 2023	Added notes about requirement of User-Agent header
6 July 2023	Fixed typos in the `GetCreditsByTimeslotID` example
10 August 2024	Updated to use `api_key` for authentication instead of username/password (which has been deprecated) Added Sona prefix to all function names Added new API functions `SonaGetCreditsByDateRange` and `SonaGetSignupsByDateRange` Updated `APICreditItem` and `APISignup` to include new field occur_date
3 October 2024	Added code examples for various languages.
28 November 2024	Added new API function `SonaCreateUser`
5 January 2025	Updated revision history to add in new API functions that were previously added: `SonaGetPrescreenDataByExperimentID` `SonaGetPrescreenDataByTimeslotID` `SonaSignUpUserToATimeslot` `SonaGrantCreditBySignupID`
13 July 2025	Functions returning `APIPerson` can now return anon_id_code Added new API function: `SonaCreateTimeslot`
27 August 2025	Added new API function: `SonaSetCoursesByPersonID`
6 August 2026	Added new API function: `SonaMergeUser`
19 August 2026	Added `SonaAddUserRole` and `SonaRemoveUserRole` Added `SonaGetStudyCreditAssignmentMismatch` Added payment fields to `APIStudyInfo` and completed its field descriptions Corrected and URL-encoded the sample request URL for `SonaGrantCreditBySignupID` Corrected the documented Boolean result for `SonaGrantCreditBySignupID`
3 September 2026	Added new API function: `SonaSetUserTimeslotUsageLimit`
14 September 2026	Added payment fields and payment status details to `APICreditItem`
15 October 2026	Expanded `WebstudyCredit` documentation with parameters, results, error codes, and examples. Corrected its route and authentication in the OpenAPI specification.
16 October 2026	Corrected request examples, XML responses, and error-code descriptions across the API function reference. Clarified result formats, lookup behavior, and prescreen result limits. Corrected data-class field descriptions. Clarified authentication and JSON POST examples. Expanded the OpenAPI specification to include GET and JSON POST for all documented functions and corrected required parameters.
29 October 2026	Added guidance for downloading documentation files from scripts and AI tools.

Back to contents