---
title: "Retrieves monthly beneficiary rankings"
method: GET
path: "/api/companies/v1/analytic/monthly_beneficiary_rankings"
tags: ["Analytics"]
---

# Retrieves monthly beneficiary rankings

`GET /api/companies/v1/analytic/monthly_beneficiary_rankings`

## Request

- Base URL: `https://hr.totalpass.com`
- URL: `https://hr.totalpass.com/api/companies/v1/analytic/monthly_beneficiary_rankings`
- Auth: API key in header `x-api-key`

This endpoint generates a ranking of beneficiaries based on their usage frequency within a specific month. It highlights the top users (both holders and dependents), showing their ranking position, total usage count, and the moment the goal was completed.

## Response `200`

returns the monthly beneficiary rankings summary details

- object
  - `data` object[]
    - `key` string
    - `value` string
    - `reference` string
    - `type` string
    - `ranking_position` string
    - `completion_moment` string

## Other responses

- `401`: returns unauthorized when api key is invalid
- `404`: returns not found when there is no data
- `422`: returns unprocessable entity on unexpected errors

---

[API](https://skmtc.dev/totalpass/apis/api-companies.md) - [All operations](https://skmtc.dev/totalpass/apis/api-companies/llms.txt) - [OpenAPI document](https://skmtc.dev/totalpass/apis/api-companies/revisions/62259afde09a?raw)