Reporting API

The AIHR Reporting API is a RESTful API designed to provide programmatic access to your organization’s learning data. It allows you to track and analyze learner engagement and progress at scale, integrating seamlessly with your existing analytics and reporting tools.

Core Functionality

Track Learner Progress: Get detailed insights into individual learner progress on specific courses and programs.
Monitor Course Completion: Access real-time data on course completion status, overall completion percentages, and total learning hours for each learner.
Programmatic Access: Automate data extraction and reporting, enabling you to build custom dashboards and reports that meet your organization’s unique needs.

Use Cases

Build Custom Dashboards: Create internal dashboards to visualize your team’s learning progress.
Automate Reporting: Schedule regular reports to stakeholders on learning adoption and ROI.
Integrate with BI Tools: Connect AIHR data with your existing Business Intelligence tools like Tableau or Power BI.

Key Data Points

The API provides access to the following key data points for each learner:

Field	Description
`userId`	A unique identifier for the learner.
`userName`	The name of the learner.
`userAvatarUrl`	A URL for the learner’s profile picture.
`totalHoursStudied`	The cumulative time a learner has spent on a course or program, in hours.
`progress`	An array of objects detailing progress on specific programs. Each object includes the following fields:
`progress.programName`	The full name of the program.
`progress.abbreviation`	The abbreviated name of the program.
`progress.value`	The completion percentage of the program (e.g., `75`).
`progress.timeSpentInMinutes`	The total time spent on the program, in minutes.
`progress.timeLeftInMinutes`	The remaining time to complete the program, in minutes.
`progress.totalDuration`	The total duration of the program.
`progress.date`	The date and time the progress was last updated, in ISO 8601 format.

Request/Response Schema

We use Scalar to provide interactive API documentation. Once authenticated, you can test the content API calls directly in your browser.

🔗 Reporting API Scalar Docs

POST/external/api/reports

Description: Retrieves a paginated list of adoption reports based on specified criteria. This endpoint allows you to filter reports by user or program.
Authentication: Requires an API key.
Parameters:
- api-version (query): The requested API version. (Required, default: 1.0)
- X-AIHR-API-Key (header): API Key Header used for authentication. (Required)
Request Body (application/json): GetExternalAdoptionsQuery This object defines the filters and pagination for your report request.
- programSKUs (string, nullable): A comma-separated list of program SKUs to filter the report.
- userIds (array of UUID): An array of user IDs (UUIDs) to filter the report.
- pageSize (integer): The number of items to return per page.
- page (integer): The page number to retrieve.

Example Request Body

{
  "userIds": ["550e8400-e29b-41d4-a716-446655440000"],
  "programSKUs": null,
  "pageSize": 20,
  "page": 1
}

Example Success Response (200 OK): AdoptionListResponse A successful response returns a paginated list of AdoptionViewModel objects.

{
  "pageSize": 20,
  "page": 1,
  "count": 1,
  "data": [
    {
      "userId": "550e8400-e29b-41d4-a716-446655440000",
      "userName": "John Doe",
      "userAvatarUrl": "https://cdn.aihr.com/avatars/john-doe.jpg",
      "totalHoursStudied": 15,
      "progress": [
        {
          "programName": "People Analytics",
          "abbreviation": "PA",
          "value": 75,
          "timeSpentInMinutes": 900,
          "timeLeftInMinutes": 300,
          "totalDuration": "PT20H",
          "date": "2025-10-03T14:30:00Z"
        }
      ]
    }
  ],
  "sort": {
    "sorts": [
      {
        "direction": "asc",
        "property": "userName"
      }
    ]
  },
  "filter": {
    "program": "People Analytics",
    "userIds": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Error Responses:

400 Bad Request: The request parameters are invalid.
401 Unauthorized: Authentication failed (e.g., invalid API key).
403 Forbidden: The API key does not have the necessary permissions.

Schema Definitions:

AdoptionViewModel: Contains a user’s ID, name, avatar URL, total hours studied, and an array of AdoptionProgressViewModel objects.
AdoptionProgressViewModel: Details the progress for a specific program, including time spent, time left, and overall progress value.
GetExternalAdoptionsQuery: The object used to filter and paginate the report request.
AdoptionListResponse: The top-level response object containing the report data and pagination details.