How to use the API in practice

 1. Example: Register a new user


2. Example: Update user profile information


3. Example: Get user profile information


4. Example: Getting a group of users


5. Example: Getting unit progress and performance data for a feature group of users


6. Example: List all users in your organization


7. Example: SSO - getting a URL with an auth_token that will automatically log the user into Voxy


8. Common problems


  • 401 -  Unauthorized. The identity of the requester could not be verified 

This error means that your request did NOT include a valid Authorization header, and therefore we could not verify the identity of the requester and had to deny the request. Usually, this is due to an incorrectly generated REQUEST_SIGNATURE.

To generate the signature correctly, your code should execute the following steps:

  1. Get any parameters that were included in the request and sort them alphabetically by parameter name.
  2. URL encode the alphabetically sorted parameters.
  3. Create a text string that is a concatenation of your API signature and the URL encoded parameters from Step #2 (e.g. {{API_SECRET}}+{{URL_ENCODED_PARAMETERS}}.
  4. Encrypt the string using the sha-256 hashing algorithm.

The resulting signature is a 256-bit encrypted signature that looks like this: 24412158fe201e7d4d0a22f16b302c3252428ad129d1398eb5d2248d73223a67

This signature is used in the Authorization header included with your request to the Voxy Partner API. The Authorization header should look like this:


 "Authorization": "Voxy xPLo0vQ3opfMt9aV:24412158fe201e7d4d0a22f16b302c3252428ad129d1398eb5d2248d73223a67"


If you're using any parameters with special characters, make sure to do a urlencode not only in the parameters but also on the process of creating the signature. Otherwise they will not match and will generate different signatures and will result in your request being denied.



  • 400 - Bad request

This kind of error may appear if you have included incorrectly formatted parameters. For example, most date parameters in the Voxy Partner API require dates to be submitted as YYYY-MM-DD.  If you submit the date in some other format, you will get a 400 - Bad request error in the response from the API.

To make sure that your request has all the correct parameters, please review the Voxy Partner API docs on



  • 409 - Conflict. The user already belongs to another org

When trying to register a new user/learner, you may receive this error. This means that the email used on that user is already attached to another Voxy's account. That user probably has an account with a different organization than yours.

To solve that, use a different email. If that is not possible or desirable, reach your CSM and explain the problem.


  • 403 - Forbidden - You cannot access this endpoint because the user is expired

If a user is expired, you are forbidden to request a Single Sign-On login URL and will receive a 403 - Forbidden error in the API response.  

Users are expired when their expiration_date is set to an earlier date than today. For instance, if today is 2018-01-05, an user is expired if his expiration_date is 2018-01-04 or earlier.  

In order to update the user’s expiration date, you can make a PUT request  to{external_user_id} and include an expiration_date parameter with a date value that is in the future.

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request



Please sign in to leave a comment.