Skip to main content

Search

KnowledgeSmart API

Resources related to the KnowledgeSmart API.

EP background

KnowledgeSmart API Guidance

Eagle Point Software Knowledge Base

Quick Answer

The KnowledgeSmart API lets you read account, user, results and assessment data and perform actions such as adding a user or inviting someone to an assessment, authenticated with an API key; on a tenant with KnowledgeSmart User Sync enabled, the Users calls should be treated as read-only, since Pinnacle Series is the source of truth for user records there.

What This Article Helps With

This article explains what the KnowledgeSmart API offers, how SSO login via the API works, what to check before using the Users calls on a Pinnacle Series–integrated tenant, and lists the most commonly used API calls with their exact URLs. It applies to KnowledgeSmart Principal Administrators and to anyone building an integration against a KnowledgeSmart account.

What Is an API?

An API (Application Programming Interface) is a set of rules that lets one piece of software request data or actions from another, without needing to know how that other system works internally. The KnowledgeSmart API lets you request data from your KnowledgeSmart account, or carry out actions such as adding a user or inviting someone to an assessment, directly from your own systems.

An API key is a unique identifier used to authenticate calls to the KnowledgeSmart API. It identifies which account is making the request and controls what that request is permitted to do.

What the API Can Do

Below is a summary of the types of action the current KnowledgeSmart API offers. See Full API Reference below for the complete, current list of calls.

Accounts

  • Get basic account information.
  • Specify UI settings.
  • Specify self-invite settings.

Users

Before you use the Users calls: check whether KnowledgeSmart User Sync is enabled.

If your organization has the Pinnacle Series–KnowledgeSmart integration with User Sync switched on, user records are created and maintained from Pinnacle Series automatically. In that case, manage users in Pinnacle Series rather than through these calls:

  • Changes to synced fields will not stick. Email address, full name and User ID are synced one way from Pinnacle Series. Updating them here is overwritten at the next sync, which runs about every fifteen minutes.
  • adduser sends a login email the integration deliberately suppresses. Users created by the sync do not receive a KnowledgeSmart account-creation email, because they sign in through Pinnacle Series. Adding a user through the API sends them login details they do not need and may not be able to use.
  • Do not change an email address this way. The email address is a user's unique identifier in KnowledgeSmart, so changing it is not a simple edit - see Managing, exporting and uploading users in KnowledgeSmart for what happens when an email address changes via upload, which is the closest documented parallel.

The Users calls remain the right tool for reading user data on any account, and for managing users on accounts without User Sync enabled. See FAQ - Pinnacle Series & KnowledgeSmart User Management Synchronization.

  • Request a login token - SSO authentication for logging into the platform. See How SSO Login via the API Works below for the full sequence.
  • Get a list of users (account ID, user ID, email address, data fields).
  • Get users by email address - for example, from an HR system or LMS.
  • Add a user to the current account and send them an email with login information.
  • Update user information - user name, email address, and additional data fields.
  • Check whether a user has accepted the terms and conditions.

Results

  • Get assessment results for a user - assessment date, score, assessment ID, user status.
  • Get detailed results for a user - user status, whether the result is from an Exam (with score bandings), score (with the option not to show it), test date, last active time, total elapsed time, test name, result ID, data fields, training tags, test ID, module ID, module names.

Assessments

  • Get a list of invitation email templates for the account.
  • Resend invitations from a list of invite IDs.
  • Get all assessments for the current account, or for the currently logged-on account.
  • Get assessment progress, or the status of a single assessment.
  • Extend or remove an expiry date.
  • Get assessments that are in progress, completed, or not started.
  • Get a user's assessments that are not started, or completed.
  • Get training gaps for a user, for an individual assessment or across assessments.
  • Assign an assessment for a user without sending an email, or create an invite that sends one.
  • Delete a specific invite.

How SSO Login via the API Works

This is the sequence behind the Request a login token call, used to log a user into the KnowledgeSmart admin site, their user page, a Skills assessment, or a results view without asking them for a separate KnowledgeSmart username and password.

  1. Authenticate using your standard API credentials.
  2. Obtain the relevant UserID, either by iterating /Users/GetAllUsers or by calling /Users/GetUserFromEmail.
  3. Call /Users/RequestLoginToken to obtain a LoginToken for that user. This call:
    • checks the UserID against your current API account;
    • checks a secret key - a second, separate secret key shared between KnowledgeSmart and the customer as part of a business process, distinct from your API key;
    • generates a LoginToken; and
    • stores the LoginToken against the user, together with a ValidUntil datetime set ten minutes from issue.
  4. Generate a URL with a query string containing the UserID, the LoginToken, and an optional Destination.
  5. Direct the user to that URL.
  6. On the KnowledgeSmart site, the /trafficcop.aspx page checks that the LoginToken and UserID combination is correct, and that the ValidUntil datetime has not passed.
  7. If both checks pass, the user is logged in and redirected to the Destination - or to the dashboard home page, if no Destination was given - and an audit record is added.
  8. If either check fails, the user is not logged in and is redirected to an error or information page. An audit record is added in this case too.

Because the LoginToken expires ten minutes after it's issued, generate the URL and direct the user to it promptly - a token that's sat unused for longer than that will fail both checks on /trafficcop.aspx and send the user to the error page instead of logging them in.

The 10 Most Used API Calls

  1. List assessments for the logged-in account:
    https://online.knowledgesmart.net/api/api/assessments/getallassessments
  2. Invite a user to an assessment (replace the parameters as required):
    https://online.knowledgesmart.net/api/api/assessments/GetNewInvite?UserEmail=john@xyz.com&TestID={testId}&FirstName=john&LastName=smith&Status=1
  3. List users for the account:
    https://online.knowledgesmart.net/api/api/users/getallusers
  4. Search users by name (replace the name value):
    https://online.knowledgesmart.net/api/api/users/getusersbyname?name=john
  5. Search users by ID (replace the userid value):
    https://online.knowledgesmart.net/api/api/users/getuserbyid?userid={userId}
  6. List results for the account:
    https://online.knowledgesmart.net/api/api/results/GetAllResults
  7. List results for a user (replace the userid value):
    https://online.knowledgesmart.net/api/api/results/GetResultsForUser?userid={userId}
  8. Show all results for a particular test ID — returns the results for that test ID, for the logged-in account:
    https://online.knowledgesmart.net/api/api/results/GetResultsForAssessment?testid={testId}
  9. Add a new user (replace the email, firstname and lastname values). If a user already exists with that email address, that user is added to the account rather than a new one being created:
    https://online.knowledgesmart.net/api/api/users/adduser?email=john@xyz.com&firstname=john&lastname=smith
  10. Get answers for a result (replace the resultid value) — use GetAllResults or GetResultsForUser first to find the result ID you need:
    https://online.knowledgesmart.net/api/api/results/getanswersforresult?resultid={resultId}

Full API Reference

For the full, current list of available API calls, see the KnowledgeSmart Swagger documentation.

If Your Organization Uses Pinnacle Series

KnowledgeSmart User Sync decides whether these calls are the right tool. With sync enabled, Pinnacle Series is the source of truth for user records, and the Users calls above should be treated as read-only. Without sync - including on accounts that have both platforms but have not switched sync on - they work exactly as documented.

What the sync covers, and what it doesn't. Email address, full name and User ID sync one way from Pinnacle Series to KnowledgeSmart. Custom user data fields, teams and manager relationships are not synced, so those are still managed in KnowledgeSmart - see Managing, exporting and uploading users in KnowledgeSmart.

Users who exist only in KnowledgeSmart are left alone. The sync ignores them, so Interviewees and other KnowledgeSmart-only records are not affected.

Pinnacle Series has its own API. If you're automating against an integrated tenant, user provisioning belongs on that side - see Pinnacle Series API Guidance.

Helpful Tips

Common Questions

My organization has KnowledgeSmart User Sync enabled - can I still use the Users calls?

Yes, for reading user data. Treat them as read-only for managing users - Pinnacle Series is the source of truth for synced accounts, and changes made here to synced fields are overwritten at the next sync.

Why did a user added through adduser receive a login email they didn't need?

The API doesn't know about User Sync, so it sends the standard login email regardless. That suppression only happens for users created by the sync itself. If you add a user through the API on a synced account, they'll get login details for an account they may not need to sign in to directly.

Can I change a user's email address through updateuser?

We recommend against it. Email address is a user's unique identifier in KnowledgeSmart, and changing it is not a simple edit via the equivalent CSV upload route - it creates a second record rather than updating the existing one. The safer path is to change the address in Pinnacle Series (on a synced account) and let the sync carry it across, or raise a support ticket.

My generated login URL isn't working - why?

The LoginToken has likely expired. It's only valid for ten minutes from when RequestLoginToken is called - generate the URL and send the user to it promptly rather than storing it for later use.

Where do I find the full, current list of API calls?

See the Full API Reference section above for the Swagger documentation link.

Still Need Help

Log a support ticket