APIs Spec (LLM friendly)

Download here

This document is the complete, plain-text reference for the BlueVolt APIs, designed to be read by developers and AI assistants. It covers authentication, all API versions and endpoints, data semantics, and answers to the most common integration questions. Interactive testing and key management live in the BlueVolt Developer Portal.

BlueVolt is a learning management platform for channel and extended enterprise training. Each partner organization runs a university — a branded training site with its own courses, learners, groups, and enrollments. The APIs give you programmatic access to your university's data.

The BlueVolt APIs:

• Reporting API (versions 1–4) — read-only access to enrollments, users, groups, courses, modules, SCORM data, scores, Training Tracks, categories, schedules, and billing transactions.
• User Management API (UserSync) — add, update, remove, and merge user profiles.
• Salesforce API — Salesforce-specific integration (documented separately; see the Knowledge Base).

Authentication

Every request needs two keys, both found under Profile → API Keys in the Developer Portal after your key request is approved:

Example:

GET https://apigw.bluevolt.com/devapi4/api/EnrollmentsForUser?APIkey={api-key}&userId=9012
Ocp-Apim-Subscription-Key: {primary-key}

Note: the v4 endpoint reference in the Developer Portal does not list the APIkey parameter, but it is required on v4 as on every other version.

v4 additionally requires that the Developer Portal account that requested the keys uses an email address belonging to a user inside your university. Keys requested from an account outside the university work on v2 but fail on v4 with a 500 error (see Troubleshooting). For team integrations, use a shared service email (e.g., data.analytics@yourcompany.com) that exists as a university user, so access survives staff changes.

Getting keys: create a Developer Portal account → confirm your API add-on with your CSM → select the APIs you need and Request Keys → an admin approves the request → both keys appear under Profile → API Keys.

Rate Limits

30 requests per minute. Design integrations around bulk endpoints with incremental filters (lastUpdatedUTCStart) rather than per-learner request loops.

Choosing an API Version

Four Reporting API versions are active. Use v4 — it has the most complete endpoint set, consistent pagination, and server-side filtering. The table shows what each version can and cannot do:

Known trap: v3 removed the per-user enrollment, user, group, and custom-field capabilities that existed in v2. If you need those, use v4 (or v2). Billing transactions are the one capability that currently still requires v1–v3.

Base URLs: v2 https://apigw.bluevolt.com/devapi2/webapi/v2/, v3 https://apigw.bluevolt.com/devapi3/webapi/v3/, v4 https://apigw.bluevolt.com/devapi4/api/.

Endpoint Reference — Reporting API v4 (Recommended)

All endpoints are GET, return JSON arrays, and accept limit/offset for pagination. If limit is omitted, a default page size applies — always pass an explicit limit and page until a response returns fewer records than the limit.

Key Response Fields — Enrollment Object

An enrollment is one learner-course pair. The fields that matter most:

• Id — enrollment record ID. UserId / Username, CourseId — who and what.
• EnrollmentStatus — the learner's state in the course. Values: Active (enrolled, in progress), Complete (finished the course), Closed (the enrollment's access duration expired before the learner completed the course), Terminated (enrollment ended before completion), PendingRequestApproval (awaiting enrollment approval).
• EnrollmentDate, CompletionDate, WorkDoneDate, LastUpdatedUTC — LastUpdatedUTC changes on every mutation to the record (completion, status change, etc.), which makes it reliable for incremental sync.
• Passed, Score, ManualPass, HasStartedCourse, PercentComplete — outcome and progress.
• CourseSeatTime — time spent in the course, in seconds.
• AccessExpirationDate, AccessDuration, RenewalDuration — enrollment access window.
• AmountSpent, PaymentMethod, PaymentPromoCode, BlueBucksEarned — commerce fields.

Important: when a learner is unenrolled from a course, the enrollment record disappears from API responses entirely — there is no "unenrolled" status. All enrollment queries and counts are point-in-time; the API cannot reconstruct historical enrollment state.

Key Response Fields — User Object

• ID, UserName, FirstName, LastName, EmailAddress, SSOUsername, EmployeeCode, DateCreated, DateModified, LastLoginDate
• MailingAddress — nested object (AddressLine1/2, City, State, Region, CountryCode, PostalCode, PhoneNumber)
• Licenses — array of professional license records (State, LicenseNumber, ExpirationDate, …)
• CustomFields — array of { UserId, FieldName, CustomFieldValue }. These are your university's admin-configured profile fields (e.g., "Branch/Dept", "Region"). Field names vary per university; values are always strings. Query one user to discover the field names your university uses.

Endpoint Reference — Reporting API v2

No pagination — endpoints return complete result sets. No server-side status filter. The APIkey query parameter is required on every call (omitted from the table).

Note: the v2 enrollment object uses CourseEnrollmentStatusId — a numeric status ID with no published integer-to-status mapping. If you need to filter or interpret enrollment status, use v4, which returns the EnrollmentStatus string.

Endpoint Reference — Reporting API v3

v3 is useful primarily for billing transactions (split by type, which v2 lacks) and its enrollment envelope. It has no user, group, per-user enrollment, or custom field endpoints — use v4 for those.

Reporting API v1 remains operational for legacy integrations but offers nothing v2 doesn't; new work should not target it.

Endpoint Reference — User Management API (UserSync)

All endpoints are POST to https://apigw.bluevolt.com/usersync/UserSyncApi.svc/… with ApiKey in the JSON body and the subscription key header. This is the only write API.

Profile fields in AddUsers: UserName (match key), FirstName, LastName, Email, Password, JobTitle, CompanyName, EmployeeCode, Address1, Address2, City, State, Zip, Country, WorkPhone, SSOLogoutUrl, and CustomFieldList for university-defined fields:

{
  "Profiles": [{
    "UserName": "jsmith",
    "Email": "jsmith@example.com",
    "JobTitle": "Service Technician",
    "CustomFieldList": [
      { "FieldName": "Department", "CustomFieldValue": "Field Service" },
      { "FieldName": "Supervisor",  "CustomFieldValue": "R. Alvarez" }
    ]
  }],
  "ApiKey": "{api-key}",
  "SendWelcomeEmails": false
}

Custom field names must match fields already configured in your university (discover them via GetUser — see the user object above).

Note: the AddUsers schema also shows EnrollmentList, TrainingTrackList, CourseRoleList, and related sync-type options. Enrollment creation via the API is not supported — do not use these fields. See "What the APIs Cannot Do" below.

What the APIs Cannot Do

Stated explicitly so integrations (and AI assistants) don't assume endpoints that don't exist:

• Create enrollments or unenroll learners — enrollment management happens in the university admin UI only. (The EnrollmentList fields in the UserSync schema are not supported.)
• Create or modify courses, modules, schedules, or content — all Reporting endpoints are read-only; UserSync only manages user profiles.
• Retrieve certificates — certificate documents and records are not exposed by any version. Use completion data (CompletionDate, EnrollmentStatus = Complete, Passed) as the system of record; learners access their certificates in the university UI.
• Reconstruct historical enrollment state — unenrolled records disappear entirely, so all queries are point-in-time.
• Filter v2 enrollments by status meaningfully — no published mapping for CourseEnrollmentStatusId; use v4.

Common Questions

How do I get the total number of courses a learner is enrolled in?

There is no count field. Call GET /api/EnrollmentsForUser?APIkey={api-key}&userId={id}&limit=200 (v4) and count the records, paging with offset until a response returns fewer than limit records. Decide first what "enrolled" means for your display: enrollmentStatus=Active for courses in progress, or Active + Complete for all-time. Remember counts are point-in-time — unenrolled courses vanish from the results. On v2, EnrollmentsForUser returns the complete set with no paging; the count is the array length, but status filtering must happen client-side.

How do I display completions, training hours, or compliance data in my BI system?

Use bulk incremental sync, not per-learner calls (30 req/min limit): initial load via paged GetEnrollments, then periodic re-queries with lastUpdatedUTCStart set to your last sync time — LastUpdatedUTC updates on every record mutation, so nothing is missed. Sync GetAllUsers the same way for the learner dimension, joining branch/department from CustomFields on UserId. Completions: CompletionDate + EnrollmentStatus = Complete. Training hours: sum CourseSeatTime (seconds) ÷ 3600.

How do I update user attributes like job title, department, or supervisor?

POST /UserSyncApi.svc/AddUsers with the existing UserName — it updates the matched profile. JobTitle is a first-class field; department, supervisor, location, branch, and similar attributes are university-configured custom fields set via CustomFieldList (names must match your university's configuration exactly).

How do I know which custom fields my university has?

Call GetUser for any learner and read the CustomFields array — the FieldName values are your university's configured fields.

Why does the same query work on v2 but not v3?

v3 has a reduced endpoint set — no user, group, per-user enrollment, or custom-field endpoints. Check the version capability map above; what's missing from v3 is in v4.

Can I authenticate learners through the API?

POST /webapi/v3/users/authenticate validates credentials. For single sign-on integration (SAML/Entra/Okta), contact your CSM — SSO setup is handled with BlueVolt's integration engineers, not through these APIs.

Troubleshooting

v4 returns 500 — "An error occurred while processing your request. Ensure the user is enrolled in a university." Your v4 keys were requested from a Developer Portal account whose email is not a user in your university (v2 tolerates this; v4 does not). Fix: create a portal account with an email that exists as a university user and request keys from it, or add the developer's email to the university's user list.

401 / subscription key rejected. Confirm the Ocp-Apim-Subscription-Key header carries the Primary Key (not the API Key), and that your key request was approved (Profile → API Keys).

Empty results that should have data. Check you're on the right version for the capability (see the version map — especially anything user- or group-related on v3), and that the APIkey query parameter is present.

Pre-2025 integration stopped working. Connections not migrated to the Developer Portal were deactivated after May 30, 2025. Follow Updating existing API connections.

Rate limiting (429 or throttling). Stay under 30 requests/minute — switch per-learner loops to bulk endpoints with lastUpdatedUTC filters.

Support

Questions not covered here: submit a request or email support@bluevolt.com. Platform status incidents are announced via the BlueVolt status page.