SonaGrantCreditBySignupID
Description¶
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.
Input Parameters¶
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 |
Output Parameters¶
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.
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 | 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. |
Sample Input¶
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=falseURL 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
Sample Output¶
<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.