Introduction to Pinnacle Series API Guidance

Quick Answer

The v3 Reporting API is the latest and preferred way to access Pinnacle Series data, with the v2 API used for tasks the v3 Reporting API does not cover, such as creating users and managing Group membership, and the v1 API kept only for existing integrations.

What This Article Helps With

This article introduces the Pinnacle Series APIs for technical administrators and developers who want to connect Pinnacle Series to another system, such as an HR platform, an identity provider, a reporting tool or an intranet. It explains which API to use for each type of task, how to identify which API an existing integration uses, and how to get access. Detailed instructions for each task are in the guides linked from this article and from the Pinnacle Series API Toolkit.

Which Pinnacle Series API to Use

Each Pinnacle Series API has its own address and its own authentication flow.

v3 Reporting API (reporting.pinnacleapis.com/api/...): the latest and preferred way to access Pinnacle Series data. The v3 Reporting API returns reporting data for registered users, logins, searches, resources accessed, Course enrollments, content and Assessments, and requires the Reporting Administrator or Reporting Manager permission.
v2 API (prodgenapi.azurewebsites.net/api/v2/...): manages users, Groups, user and Group properties, Assignments, automatic Assignments, Assessments, external learning and notifications. Use the v2 API for tasks the v3 Reporting API does not cover, such as creating users and managing Group membership.
v1 API (prodgenapi.azurewebsites.net/api/...): the original Pinnacle Series API, used by existing integrations. Eagle Point plans to retire the v1 API, so new integrations should use the v3 Reporting API, and the v2 API where the v3 Reporting API does not cover a task.
KnowledgeSmart API (online.knowledgesmart.net/api_dev/...): lists KnowledgeSmart Assessments, invites users to Assessments, and returns results and answers.

How to Identify Which API an Integration Uses

Find the address the integration sends its requests to, for example in the Power BI data source settings or the integration's configuration.
If the address starts with reporting.pinnacleapis.com, the integration uses the v3 Reporting API.
If the address starts with prodgenapi.azurewebsites.net and contains /api/v2/, the integration uses the v2 API.
If the address starts with prodgenapi.azurewebsites.net and does not contain /api/v2/, the integration uses the v1 API.
If the address starts with online.knowledgesmart.net, the integration uses the KnowledgeSmart API.

How to Get Started with the Pinnacle Series APIs

Decide which API the integration needs, using the list above.
Contact Eagle Point Support to request an API key, stating which API you plan to use and what the integration will do.
Create a dedicated Pinnacle Series account for the integration rather than using a person's own login.
Give the integration account only the permissions the integration needs.
Open the Swagger site for the chosen API.
Authenticate in Swagger using the API key and the integration account, following the authentication flow for the chosen API.
Run a simple read request in Swagger and confirm that it returns data from your tenant rather than an authentication error.

Authentication Flow for Each Pinnacle Series API

Every Pinnacle Series API request uses an API key issued by Eagle Point Support. Each API exchanges that key and the account's credentials for a token, which is then sent on every request that follows.

v3 Reporting API: GET /authinfo returns the tenant ID for an email address, then POST /authorize returns a bearer token. The full steps are in How to Authenticate with the v3 Reporting API.
v2 API: GET /api/v2/authorization/authinfo returns the tenant ID for an email address, then POST /api/v2/authorization returns a bearer token.
v1 API: GET /api/authorization/apiToken returns an API token, then POST /api/authorization/userToken returns a user access key.
KnowledgeSmart API: contact Eagle Point Support for KnowledgeSmart API access details.

How to Authenticate with the v3 Reporting API

The v3 Reporting API requires an API key issued by Eagle Point Support and an account with the Reporting Administrator or Reporting Manager permission. The base address is https://reporting.pinnacleapis.com/api.

Send GET /authinfo?email={email} with the API key in the ApiKey header.
Copy the tenantId value from the response.
Send POST /authorize with the API key in the ApiKey header and Email, Password and TenantId in the request body.
Copy the bearerToken value from the response.
Send Authorization: Bearer {bearerToken} on every request to a reporting endpoint.
Send a request to /reporting/courseEnrollments and confirm that it returns Course enrollment data for your tenant.

The POST /authorize request body also accepts the optional fields Language, TimeOffset, TimezoneName and ReturnLongLivedToken. The response includes an expiration value showing when the bearer token expires, and a longLivedToken when ReturnLongLivedToken is set to true.

Swagger Documentation for the Pinnacle Series APIs

Swagger lists every available request for an API, with its parameters and responses, and lets you send test requests. The v3 Reporting API has its own Swagger site. The v1 API and the v2 API share one Swagger site; select the version from the definition list at the top of the page.

Guides for Common Pinnacle Series API Tasks

Start here:
Pinnacle Series API Toolkit
Authenticate with the v2 API: ProdGenAPI V2 Authorization – Create a Bearer Token
Authenticate with the v3 Reporting API:
Pinnacle Series API Reporting Guide
Reporting and Power BI:
Pinnacle Series API Reporting Guide
and
Pinnacle Series Reporting API Data Dictionary
Creating and updating users:
User Provisioning Using the API
Directory synchronization: Configuring Synchronization with Microsoft Entra ID (video)
KnowledgeSmart: Configuring KnowledgeSmart Integration (video)

Helpful Tips

Store API keys and integration account passwords in a secrets vault, never in source code, scripts, spreadsheets or shared reports.
Pinnacle Series bearer tokens expire, so an integration must re-authenticate when its token expires.
Test a new integration against a small set of users before running it across the whole tenant.
Contact Eagle Point Support straight away if an API key is lost or exposed, so the key can be replaced.

Common Questions

Which Pinnacle Series API should I use for Power BI reporting?

Use the v3 Reporting API (reporting.pinnacleapis.com) for Power BI and other reporting tools. The account used for the connection needs the Reporting Administrator or Reporting Manager permission.

Should a new integration use the v1, v2 or v3 API?

A new integration should use the v3 Reporting API, which is the latest and preferred access route. Use the v2 API only for tasks the v3 Reporting API does not cover, such as creating users and managing Group membership. Eagle Point plans to retire the v1 API, which remains available for existing integrations.

Can I use the v3 Reporting API to create or update users?

No. The documented v3 Reporting API endpoints return reporting data only. Use the v2 API to create and update users and to manage Group membership.

Can a Ruleset use user attributes sent through the API?

No. A Ruleset evaluates only attributes synchronized from Entra ID, so an integration that sends custom attributes through the API must add users to Groups itself, using POST /api/v2/groups/{groupId}/members.

Does each Pinnacle Series API have its own Swagger site?

Not quite. The v1 API and the v2 API share one Swagger site at prodgenapi.azurewebsites.net/swagger/ui/index. The v3 Reporting API and the KnowledgeSmart API each have their own Swagger site.