Skip to main content

Search

Pinnacle Series API

Resources related to the Pinnacle Series API.

EP background

Moving from the v1 to the v3 Reporting API

Eagle Point Software Knowledge Base

Quick Answer

The v3 Reporting API is the recommended way to pull Pinnacle Series reporting data: each of the six v1 reports has a v3 endpoint that returns the same kind of data, and the v3 Reporting API adds paging, filtering, Group, attribute and manager data on user-based records, and data the v1 reports do not provide, such as content access, external learning and KnowledgeSmart assessment results.

What This Article Helps With

This article compares the Pinnacle Series v1 reporting API with the v3 Reporting API, shows which v3 endpoint replaces each v1 report, and explains how to move an existing v1 report to v3. It also keeps a short reference for organizations that still run v1 reporting integrations. It is intended for technical administrators, developers and data analysts.

v1 and v3 Reporting API Comparison

v1 reporting API v3 Reporting API
Base URL https://prodgenapi.azurewebsites.net (paths under /api/) https://reporting.pinnacleapis.com/api
Authentication ApplicationID → apiToken → userToken; report calls send the apiKey and userAccessKey headers API key → GET /authinfo → POST /authorize; calls send the API key in the ApiKey header and the Bearer token in the Authorization header
Who can call it Results depend on the permissions of the signed-in user Requires the Reporting Administrator or Reporting Manager permission
Report endpoints 6 documented reports, all GET requests 10 endpoints, all POST requests
Large data sets No paging parameters documented Paging with page size, page number and a total count
Filtering and sorting Start and end date on some reports Filters on non-array fields with =, !=, <, >, <=, >=, combined with AND, and sorting by a column
User context on each record User name, email and IDs on enrollment reports; no user data on search and sign-in totals User name, email and IDs, plus attributes, Groups and managers, on every user-based record
Searches and sign-ins Totals only (counts per search term, unique sign-ins per day for the last 7 days) Every search and login event, with user, date and, for logins, device and Pinnacle Series version
KnowledgeSmart data Not included Assessments, assessment assignments with scores, and KnowledgeSmart logins
Field documentation Sample responses only A data dictionary describing every field

Where Each v1 Report Lives in the v3 Reporting API

v3 results are paged. Where a v1 total is reproduced by counting v3 records, read every page until the number of records retrieved matches the totalCount value in the response.

  • All User Progress (/api/reports/allUserProgress): use POST /reporting/courseEnrollments, which returns every Course enrollment.
  • Completed Courses (/api/reports/completedCourses): use POST /reporting/courseEnrollments with a filter of is_completed = true.
  • Current Enrollments (/api/reports/currentEnrollments): use POST /reporting/courseEnrollments. To list enrollments that are neither completed nor dropped, filter on is_completed = false and is_dropped = false.
  • Learning Path Progress (/api/reports/LPProgress): use POST /reporting/courseEnrollments. Like the v1 report, v3 returns one record per Course enrollment, and each record includes learning_path_id and learning_path. Filter on learning_path_id to list the Course enrollments for a Learning Path. The v3 Reporting API documentation does not include a Learning Path-level progress record.
  • Top Searches (/api/reports/topSearches): use POST /reporting/searches, which returns each search with its user and date. Count records by search_term to reproduce the v1 totals.
  • Unique User Sign-Ins (/api/reports/uniqueUsers): use POST /reporting/logins, which returns each login with a full login_date timestamp. Count distinct user_id values for each calendar day to reproduce the v1 totals, for any date range rather than only the last 7 days. Days with no logins do not appear in v3 results.

Data Not Available in v1 Reports

  • POST /reporting/registeredUsers: every user record, including created and deleted dates, anonymization status and lifetime login count.
  • POST /reporting/resourcesAccessed: every content access event, with the content, its Libraries and how the user found it.
  • POST /reporting/content: content metadata, including Courses, Learning Paths, Libraries, Learning Tags, folders and durations.
  • POST /reporting/externalLearning: learning completed outside Pinnacle Series, such as certifications and third-party training.
  • POST /reporting/assessments, POST /reporting/assessmentAssignments and POST /reporting/KSlogins (written as ksLogins in some guides): KnowledgeSmart assessments, assessment assignments with scores and completion, and KnowledgeSmart logins.

v1 Fields to Check Before Migrating

The v3 Reporting API documentation does not list a direct equivalent for these fields returned by v1 reports. If a v1 report depends on any of them, confirm how to source the data before switching:

  • employeeID (returned as employeeId by LPProgress). Check whether your organization holds employee IDs in the v3 user attributes.
  • quizComposite, returned by completedCourses and LPProgress. The v1 quizScoreStatus field maps to v3 quiz_status (pass or fail), but v3 does not list a matching quiz score field.
  • courseProducts, returned by completedCourses and LPProgress.
  • videoWatchPercent and statusDate, returned by LPProgress.

How to Move a v1 Report to the v3 Reporting API

  1. Request a v3 Reporting API key from Eagle Point Support. The v3 API key is separate from the v1 ApplicationID.
  2. Set up a dedicated Pinnacle Series account for API calls, excluded from SSO and with a password managed in Pinnacle Series.
  3. Give the API account the Reporting Administrator permission, so the v3 Reporting API returns data for the whole organization.
  4. Call GET /authinfo with the account email address, sending the API key in the ApiKey header, to get the tenant ID.
  5. Call POST /authorize with the email address, password and tenant ID to get a Bearer token.
  6. Send the Bearer token in the Authorization header on each v3 call.
  7. Call the v3 endpoint that replaces the v1 report, using the mapping in this article.
  8. Add paging to the request body, and add filters and sorting to match the v1 report.
  9. Map the v3 response fields to the fields your report or dashboard uses. v3 field names use snake_case, for example completed_date instead of enrollmentCompletedDate.
  10. Compare the v3 results with the v1 report output and confirm that the record counts and key values match before switching off the v1 report.

Using the v1 Reporting API

The v1 reporting API remains supported for existing integrations. v1 calls use the base URL https://prodgenapi.azurewebsites.net, and report calls send two headers: apiKey and userAccessKey.

  1. Get an apiKey by calling GET /api/authorization/apiToken with the ApplicationID issued by Eagle Point Support.
  2. If your organization has more than one tenant, get the tenant ID by calling GET /api/authorization/userOrgInfo with the user's email address. Organizations with one tenant can get the tenant ID from Eagle Point Support instead.
  3. Get a userAccessKey by calling POST /api/authorization/userToken with the email address, password and tenant ID, sending the apiKey header.
  4. Call a report: allUserProgress, completedCourses, currentEnrollments, LPProgress, topSearches or uniqueUsers, under /api/reports/. Most reports accept optional startDate and endDate parameters in YYYY-MM-DD format.

The same authorization steps work for other v1 endpoints. For worked examples and sample responses, open the v1 API Guide or watch the v1 Authorization and Reporting video.

Helpful Tips

  • Join v3 data sets on IDs rather than names or email addresses, for example user_id in registered users and logins, and assigned_to_user_id in enrollments.
  • The attributes, Groups and managers fields are arrays and cannot be filtered on directly. Retrieve them and filter in your reporting tool.
  • Use a small page size while developing a v3 integration and a larger page size in production.

Common Questions

Do I need new credentials to use the v3 Reporting API?

Yes. The v3 Reporting API uses its own API key, issued by Eagle Point Support and sent in the ApiKey header, and a Bearer token from POST /authorize, sent in the Authorization header. The v1 ApplicationID, apiKey and userAccessKey do not work with the v3 Reporting API.

Why does the v3 Reporting API return less data than v1 for the same user?

This may occur when the API account has the Reporting Manager permission. The v3 Reporting API limits results by reporting permission, and a Reporting Manager sees only the Groups they own or manage, including child Groups. To retrieve data for the whole organization, call the v3 Reporting API with an account that has the Reporting Administrator permission.

Can I get Learning Path progress from the v3 Reporting API?

The v3 courseEnrollments endpoint returns Course-level enrollment records that include the Learning Path ID and name, which is the same level of detail as the v1 LPProgress report. Filter on learning_path_id to list the Course enrollments for a Learning Path. The v3 Reporting API documentation does not include a separate Learning Path-level progress record.

Where can I find every v3 field and its meaning?

Open the Reporting API Guide or open the Reporting API Data Dictionary. Both are in the Pinnacle Series platform.

Related Articles

Still Need Help

Log a support ticket