Knowledge Base

Popular Search teststart testhow tocertificatehow
View Categories

Integrating YouTestMe Tests with External Systems Using the Authorizations REST API

Article verified for Release 14.2 on May 15, 2025.

Integrating YouTestMe’s testing engine into an external platform, such as a Learning Management System (LMS) or an online test store, enables a smooth and automated testing experience for users. This guide outlines the step-by-step process of syncing users, creating test authorizations, handling test results, and enabling seamless access via SSO. For a comprehensive overview of all available endpoints, refer to the YouTestMe API documentation.

Integration Overview

  1. Preparing a Test and Testing Session in YouTestMe

  2. Test Purchase or Assignment in External System

  3. User Synchronization

  4. Test Authorization Creation

  5. Launching the Test via SSO

  6. Attempt Results Webhook Subscription

Preparing a Test and Testing Session in YouTestMe

Before users can be authorized to take a test, the actual test and testing session must be set up within the YouTestMe platform. This preparation involves:

  • Creating the test with questions, settings, and scoring rules.

  • Assigning a unique external identifier (externalTestId) to the test to allow external systems to refer to it without relying on internal IDs.
  • Creating a testing session or many testing sessions that require authorization.

The starting point is to create a test in YouTestMe. It is possible to create simple or generated tests.

As a part of the test creation, the External ID from the external system can be assigned to the created test by following the steps below:

  1. Open the “Settings tab” for the created test.
  2. Navigate to the “External attributes”.
  3. Add “External ID”, matching the External ID in the external system. (For example, product or activity ID)
  4. Click on the “Save” button.

If the Exteranl ID is not set, the YouTestMe internal ID must be stored in the external system to create authorizations.

To allow users to book and start the test for which they are authorized, it is necessary to create at least one testing sessions that require authorization.

  1. Click on the “Tests” button in the side menu.
  2. Click on the “Manage tests” button and open the previously created test.
  3. After opening the desired test, navigate to the “Testing sessions” menu.
  4. Click on the “New testing session” to start the creation of the test session.
  5. Enable the option to “Allow candidates to self-enroll”.
  6. Enable the “Required authorization” feature. Enabling this option will allow only users with authorization to enroll in the test.
  7. Click on the Save button to save the testing session.

To explore all options in the Testing Session module, refer to this article.

Test Purchase or Assignment in External System

The idea of the integration is to have an activity or product in the external system that is linked by an external ID or a YouTestMe internal ID with a YouTestMe test. After the test purchase or assignment in the external system, the external system should synchronize the user and create an authorization for the purchased or assigned test. That way user is authorized to start the test in YouTestMe.

User Synchronization

The external system should check if the user account exists in YouTestMe and create it doesn’t. If required user account can be updated as well.

To check if a user exists, use either of the following endpoints, depending on the identifier chosen for synchronization:

  • By External ID: GET /users/externalId={externalId}

  • By Username: GET /users/username={username}

  • By YouTestMe internal ID: GET /users/{internalId}

To create a user, use the following endpoint:

POST /users/
{
"username": "tom.palmer@example.com",
"status": "ACT",
"roleCode": "ADM",
"timeZoneId": "UTC",
"interfaceLanguageId": 15,
"examLanguageId": 15,
"firstName": "Tom",
"lastName": "Palmer",
"email": "tom.palmer@example.com",
"externalId": "user-5678"
}

Use externalId or username consistently across all steps for account synchronization.

See the REST API documentation for the detailed specification of the Users endpoints.

Test Authorization Creation

Test authorization allows a user to book a test and complete it.  To create a test authorization, use the following endpoint:

POST /authorizations
{
"authorizationExternalId": "exampleAuthorizationId",
"testId": 100320,
"externalTestId": "EXT_TEST_001",
"candidateId": 100001,
"candidateExternalId": "user-5678",
"candidateUsername": "tom.palmer@example.com",
"expirationDatetime": "2025-12-31T23:59:59Z"
}

You can provide either internal or external identifiers for the test (testId, externalTestId) and the candidate (candidateId, candidateExternalId, candidateUsername).

See the REST API documentation for the detailed specification of the Test attempt authorizations endpoints.

To review the list of all created test authorizations, follow the steps below:

  1. Click on the “Tests” button in the side menu.
  2. Click on the “Manage tests” button and open the desired test.
  3. After opening the desired test, navigate to the “Test administration” menu.
  4. Navigate to the Authorizations tab.
  5. Preview the created authorization.

Launching the Test via SSO

It is recommended to offer a seamless experience to users taking the test after the purchase or assignment in the external system. There are two options to achieve that:

Option 1: Generate a Unique Direct SSO Link

Generate a unique direct SSO link for a user via the REST API and present it in the external system to access the My tests page seamlessly.

To  generate a direct link, use the following endpoint:

POST /ssoLinks
{
"userId": 100001,
"username": "tom.palmer@example.com",
"userExternalId": "user-5678",
"page": "myTests.xhtml",
"refererUrl": "https://www.external-system.com/assignment/12345",
"expirationTime": "2025-05-31T23:59:59Z"
}
See Create SSO link endpoint specification for more details.
The same method is applicable for other pages as well.

Option 2: Static SSO Link to Assignment Page

Connect YouTestMe to the same SSO identity provider as the external system. YouTestMe offers a link to the test that enforces the SSO authorization, which can be stored in the external system and presented to the users after purchase or assignment. Keep in mind that this link is general for all users taking a specific test.

To set up the Open ID based SSO, see the following article.

To set up the SAML 2.0 based SSO, see the following article.

To find a link to the test which enforces an SSO authorization, see the folloing article.

Upon visiting the link,k users will be automatically logged in and redirected to the My tests page, where they can start or book the test depending on the scenario.

Attempt Results Webhook Subscription

To receive the attempt results, subscribe to a webhook for the Attempt finished event using the following endpoint:

POST /webhooks
{
"event": "attempt",
"resource": "finish",
"url": "https://your-system.com/webhook/receive",
"secret": "your-shared-secret",
"active": true
}
See the REST API documentation for the detailed specification of the Webooks endpoints.
It is sufficient to create a single webhook, and all results will be sent over it. The external system should implement the endpoint that can receive the following requests:

POST https://your-system.com/webhook/receive

{

"id": 100001,
"attemptNumber": 1,
"candidateId": 100001,
"candidate": {
"id": 100001,
"username": "tom.palmer@example.com",
"email": "tom.palmer@example.com",
"firstName": "Tom",
"lastName": "Palmer",
"externalId": "user-5678"
},
"testName": "Geograhpy test",
"maxPoints": 120,
"pointsScored": 60,
"percentScored": 50,
"testingSessionId": 5033,
"testVersionId": 10004,
"passed": true,
"status": "not_attempted",
"started": "2020-01-01T12:00:00Z",
"finished": "2020-01-01T12:00:00Z",
"authorization": {
"id": 100002,
"externalId": "assignment-12345"
}
}

This article provides a step-by-step guide for integrating YouTestMe tests with your test store, learning management system (LMS), or similar applications using the Authorizations REST API.

API
What are your Feelings

Powered by BetterDocs

How to Create a Test with a SCORM Package