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>