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>