# Bonusly Documentation > Documentation for Bonusly ## Guides: Documentation - [Documentation](https://docs.bonus.ly/docs.md): Bonusly documentation ## API Reference: Introduction - [Changelog](https://docs.bonus.ly/reference/changelog.md): What's new, what's changed, and what's going on with Bonusly's MCP Server ## API Reference: MCP Protocol Methods - MCP Protocol Methods - [Ping](https://docs.bonus.ly/reference/ping.md): MCP spec health check. Returns an empty result. Per MCP spec, `ping` requires no authentication. - [Initialize](https://docs.bonus.ly/reference/initialize.md): MCP handshake. Returns the server's advertised protocol version, capabilities, and identity. The Bonusly MCP server advertises the `tools` capability. - [List tools](https://docs.bonus.ly/reference/tools_list.md): Returns the paginated list of tools available to the caller. Accepts an opaque `cursor` to fetch subsequent pages. Returns a `nextCursor` when more results are available. - [Call a tool](https://docs.bonus.ly/reference/tools_call.md): Invokes a tool by name with arguments. The `result` envelope wraps the tool's output in `content` (an array of MCP content blocks) and `isError`. The per-tool request and response shapes are… - [List prompts](https://docs.bonus.ly/reference/prompts_list.md): Returns the list of prompts advertised by the server. The Bonusly MCP server does not advertise prompts, so this always returns an empty array. - [List resources](https://docs.bonus.ly/reference/resources_list.md): Returns the list of resources advertised by the server. The Bonusly MCP server does not advertise resources, so this always returns an empty array. ## API Reference: Awards Program Management - Awards Program Management - [List Awards](https://docs.bonus.ly/reference/adminlistawards.md): List custom awards in the caller's company. Supports filtering by state ('active' or 'inactive') and cursor pagination. Pass page_size and (optionally) state on the first call; on subsequent calls… - [Show Award](https://docs.bonus.ly/reference/adminshowaward.md): Fetch a single award in the caller's company by id. Required OAuth scope: `awards:administer` - [Create Award](https://docs.bonus.ly/reference/admincreateaward.md): Create a new custom award in the caller's company. Defines conditions, budget, period, approval levels, and giver-bot metadata. Required OAuth scope: `awards:administer` - [Update Award](https://docs.bonus.ly/reference/adminupdateaward.md): Update an existing award in the caller's company. Any subset of mutable fields may be passed. Required OAuth scope: `awards:administer` - [Delete Award](https://docs.bonus.ly/reference/admindeleteaward.md): Soft-delete an award in the caller's company and deactivate its giver bot. Required OAuth scope: `awards:administer` - [List Awards](https://docs.bonus.ly/reference/listawards.md): List custom awards in the caller's company. Supports cursor pagination. Pass type ('claimable' or 'manual') and page_size on the first call; on subsequent calls pass only the returned next_cursor.… - [Show Award](https://docs.bonus.ly/reference/showaward.md): Fetch a single award in the caller's company by id. Required OAuth scope: `awards:read` - [Admin Rewards Totals Report](https://docs.bonus.ly/reference/adminrewardstotalsreport-1.md): Returns per-user or grouped reward spend totals for the caller's company. Use group_by to aggregate by a custom property or country. Use filters to pre-scope the report to specific users, e.g.… - [Admin Rewards Redemptions Report](https://docs.bonus.ly/reference/adminrewardsredemptionsreport-1.md): Returns paginated reward redemption records for the caller's company. Supports filtering by state, user email, date range, and fulfillment status. Required OAuth scope: `rewards:administer` - [Claim Incentive](https://docs.bonus.ly/reference/claimincentive.md): Claim a claimable award ("incentive") for yourself in the caller's company. Inputs: - `award_id` (string) — the BSON id of the incentive to claim. Use the `listAwards` tool with `type:… - [List Approval Requests](https://docs.bonus.ly/reference/listawardapprovalrequests.md): List award and incentive approval requests for the caller — either requests awaiting their decision (state 'pending', the default) or requests they've already decided on ('approved', 'declined',… - [Get Approval Request](https://docs.bonus.ly/reference/getawardapprovalrequest.md): Fetch a single approval request by id, including the full inbox view with attachment, claim reason, bonus reason, review log, approvers, and recipients. Required OAuth scope: `awards:administer` - [Approve Approval Request](https://docs.bonus.ly/reference/approveawardapprovalrequest.md): Approve a pending award or incentive approval request. Resolves the current approval level (or a specific level by position), enforces the peer-race guard, and runs the same Approval service every… - [Deny Approval Request](https://docs.bonus.ly/reference/denyawardapprovalrequest.md): Deny a pending award or incentive approval request. Resolves the current approval level (or a specific level by position), enforces the peer-race guard, and runs the same Denial service every other… ## API Reference: General Organization - General Organization - [Me](https://docs.bonus.ly/reference/me.md): Returns the authenticated user's profile (identity, locale, account state). Does not include company information, balances, or permissions. Required OAuth scope: `user:read` - [Get user](https://docs.bonus.ly/reference/getuser.md): Resolve a single user within the caller's company by id, email or name. Returns the user's profile fields. Pass the user's BSON ObjectId, email, or full display name as `identifier`. When the name… - [Get users](https://docs.bonus.ly/reference/getusers.md): Bulk-fetch users by a list of user IDs within the authenticated caller's company. Required OAuth scope: `user:read` - [Search users](https://docs.bonus.ly/reference/searchusers.md): Search users in the authenticated caller's company by name or email, with optional filters on location, department, manager, and reports. Supports cursor pagination — pass the returned `next_cursor`… - [Get company](https://docs.bonus.ly/reference/getcompany.md): Returns metadata for the authenticated caller's company — name, locale, plan, feature flags, subscription state, and other profile fields. Required OAuth scope: `company:read` - [List departments](https://docs.bonus.ly/reference/listdepartments.md): List the distinct departments configured for users in the authenticated caller's company, with a user count for each. Supports prefix-match search on the department name and cursor pagination.… - [List locations](https://docs.bonus.ly/reference/listlocations.md): List the distinct locations configured for users in the authenticated caller's company, with a user count for each. Supports prefix-match search on the location name and cursor pagination. Required… - [List users in a department](https://docs.bonus.ly/reference/listusersindepartment.md): List the users in the authenticated caller's company who belong to a specific department (exact match). Supports a name/email search and cursor pagination. Required OAuth scope: `user:read` - [List users in a location](https://docs.bonus.ly/reference/listusersinlocation.md): List the users in the authenticated caller's company who belong to a specific location (exact match). Supports a name/email search and cursor pagination. Required OAuth scope: `user:read` - [List top-level users](https://docs.bonus.ly/reference/listtoplevelusers.md): List the users in the authenticated caller's company who have no manager. These are the entry points into the org chart — pair with `getReportingTree` or `getDirectReports` to walk down. Supports a… - [Get direct reports](https://docs.bonus.ly/reference/getdirectreports.md): Get the users in the authenticated caller's company who report directly to a given manager. Cross-company manager IDs return no results. Supports a name/email search and cursor pagination. Required… - [Get manager chain](https://docs.bonus.ly/reference/getmanagerchain.md): Walk the manager chain upward from a given user in the authenticated caller's company, returning the user's manager, that manager's manager, and so on up to a top-level user. The chain is ordered… - [Get reporting tree](https://docs.bonus.ly/reference/getreportingtree.md): Walk the reporting tree below a given user in the authenticated caller's company. Returns layers: layer 0 is direct reports, layer 1 is direct reports' reports, etc. `depth` controls how many layers… - [List meetings](https://docs.bonus.ly/reference/listmeetings.md): Return a page of the authenticated caller's V2 1:1 meetings — the same content shown in Bonusly's 1:1s index (upcoming first, then complete, newest first). Filters (all optional, all combined as… - [Get meeting](https://docs.bonus.ly/reference/getmeeting.md): Fetch a single V2 1:1 meeting by its id, scoped to your company. Returns the meeting's title, status, participants, transcript text, AI-generated summary brief, structured summary (topics, discussion… - [Get meeting transcript](https://docs.bonus.ly/reference/getmeetingtranscript.md): Fetch the transcript of a single V2 1:1 meeting by its id, scoped to your company. Returns the full meeting — title, status, participants, the complete `transcript_text`, AI-generated summary brief,… - [List System User Groups](https://docs.bonus.ly/reference/listsystemusergroups.md): List system user groups (everyone, team, department, location) for the caller's company. Returns member_count for each group — does not include the full user_ids list. Optionally filter by type:… - [Get System User Group](https://docs.bonus.ly/reference/getsystemusergroup.md): Get a single system user group by slug (e.g. 'everyone', 'engineering.department', 'jane-doe.team'). Returns the full user_ids array for the matched group. Company-scoped to the caller. Required… - [List Custom User Groups](https://docs.bonus.ly/reference/listcustomusergroups.md): List custom user groups for the caller's company: admin-defined groups (kind 'derived', 'explicit', or 'hybrid') and communities' own groups (kind 'community', whose members are the community's… - [Get Custom User Group](https://docs.bonus.ly/reference/getcustomusergroup.md): Get a single custom user group by id (an admin-defined group, or a community's own group with kind 'community'), including its resolved member_ids array. Returns the group's slug, display_name,… ## API Reference: Recognition Program Management - Recognition Program Management - [Get give balance](https://docs.bonus.ly/reference/admingetgivebalance.md): Fetch a user's giving balance line items with pagination. Required OAuth scope: `user:administer` or `finance:administer` - [Create give balance increment](https://docs.bonus.ly/reference/admincreategivebalanceincrement.md): Add a giving balance increment (e.g. admin_initiated_boost) to a user in the caller's company. Required OAuth scope: `user:administer` or `finance:administer` - [Admin Participation Report](https://docs.bonus.ly/reference/adminparticipationreport-1.md): Returns participation report data for the caller's company, including giving/receiving rates by group (department, location, etc.) or manager and team metrics. Supports two views:… - [Admin Users Last Recognized](https://docs.bonus.ly/reference/adminuserslastrecognized-1.md): Returns a paginated list of users along with when they were last recognized by a specified manager. Pass a full array of user IDs (up to 20 per page) and optionally a manager_id. Pagination is… ## API Reference: Rewards Program Management - Rewards Program Management - [Admin Rewards Approve Redemption](https://docs.bonus.ly/reference/adminrewardsapproveredemption.md): Approves a pending reward redemption for the caller's company. Required OAuth scope: `rewards:administer` - [Admin Rewards Decline Redemption](https://docs.bonus.ly/reference/adminrewardsdeclineredemption.md): Declines a reward redemption for the caller's company. Required OAuth scope: `rewards:administer` - [Admin Rewards Refund Redemption](https://docs.bonus.ly/reference/adminrewardsrefundredemption.md): Refunds a custom reward redemption for the caller's company. Superadmins must use the super_admin path instead. Required OAuth scope: `rewards:administer` - [Admin Rewards Fulfill Redemption](https://docs.bonus.ly/reference/adminrewardsfulfillredemption.md): Fulfills a custom reward redemption for the caller's company. Required OAuth scope: `rewards:administer` - [Admin Rewards Unfulfill Redemption](https://docs.bonus.ly/reference/adminrewardsunfulfillredemption.md): Marks a fulfilled custom reward redemption as unfulfilled for the caller's company. Required OAuth scope: `rewards:administer` ## API Reference: Giving and Receiving Recognition - Giving and Receiving Recognition - [Get points balance](https://docs.bonus.ly/reference/getpointsbalance.md): Get the authenticated user's current points balances and lifetime stats. Returns giving balance, earned/redeemable balance (earnings), monthly budget, currency, exchange rate, lifetime earnings,… - [Give recognition](https://docs.bonus.ly/reference/giverecognition-1.md): Send recognition (a bonus) to one or more colleagues on behalf of the authenticated caller. Inputs: one or more recipients, an integer points amount, a free-form reason, and one company hashtag.… - [Get recognition received](https://docs.bonus.ly/reference/getrecognitionreceived-1.md): List recognition (bonuses) received BY a user within your company. Returns who gave them recognition, the hashtags used, and the recognition message. Use this to understand what someone has been… - [Get recognition given](https://docs.bonus.ly/reference/getrecognitiongiven-1.md): List recognition (bonuses) given BY a user to others within your company. Returns recipients, hashtags, the recognition message, and the giver's per-recognition spend. Use for "When did a user… - [Get group recognition recipient count](https://docs.bonus.ly/reference/getgrouprecognitionrecipientcount-1.md): Resolve a Bonusly user group by name, slug, or type and return how many recipients an actual group post would reach within your company — plus a paginated roster of those recipients (id and name).… - [Get recognition feed](https://docs.bonus.ly/reference/getrecognitionfeed-1.md): Return a page of the recognition feed for the authenticated caller's company — the same content shown in Bonusly's web home feed (top-level posts in reverse-chronological order). Filters (all… - [List recognition types](https://docs.bonus.ly/reference/listrecognitiontypes-1.md): Return the recognition-type values accepted by the `recognition_types` filter on `getRecognitionFeed`. Each entry has a machine-readable `value` (pass this into the filter) and a human-readable… - [Search recognitions](https://docs.bonus.ly/reference/searchrecognitions.md): Search recognition (bonuses) in your company using natural language. Combines semantic (vector) and keyword (BM25) retrieval, so themes like "leadership during difficult times" and exact terms like a… - [Get recognition given to users](https://docs.bonus.ly/reference/getrecognitiongiventousers.md): Returns when the authenticated caller last gave peer recognition to each of the specified users. Pass up to 20 user IDs; the response includes one entry per requested user with a `last_recognized_at`… - [Get recognition](https://docs.bonus.ly/reference/getrecognition.md): Fetch a single recognition (bonus) by its id, scoped to your company. Returns the recognition's giver, hashtags, amount, the cleaned message, and family position — the same shape the other… - [Update recognition](https://docs.bonus.ly/reference/updaterecognition.md): Edit the message (reason) of an existing recognition you gave, scoped to your company. Mirrors the `PATCH /api/v1/bonuses/:id` endpoint. Inputs: - `id` (string) — the recognition's BSON ObjectId. -… - [Delete recognition](https://docs.bonus.ly/reference/deleterecognition.md): Delete (undo) a recognition you gave, scoped to your company. Mirrors the `DELETE /api/v1/bonuses/:id` endpoint. Input: - `id` (string, required) — the recognition's BSON ObjectId. Undoing is only… - [Give Award](https://docs.bonus.ly/reference/giveaward.md): Give a custom award to one or more recipients in the caller's company. Inputs: - `award_id` (string) — the BSON id of the award to give. Use the `listAwards` / `showAward` tools to discover awards… ## API Reference: Organization Administration - Organization Administration - [Create user](https://docs.bonus.ly/reference/admincreateuser.md): Invite a new user to the caller's company by work email. Optional fields include first_name, last_name, manager_email, hired_on (YYYY-MM-DD), company_admin, and custom_properties (for example… - [Update user](https://docs.bonus.ly/reference/adminupdateuser.md): Update admin-managed attributes for a user in the caller's company (names, email, manager_email, clear_manager (remove manager), company_admin, time_zone, custom_properties such as department,… - [Deactivate user](https://docs.bonus.ly/reference/admindeactivateuser.md): Schedule deactivation (archive) for a user in the caller's company. Requires user_id. Cannot deactivate the last remaining admin or integration-protected users when manual management is disabled.… - [Admin get user](https://docs.bonus.ly/reference/admingetuser.md): Get a single ACTIVE user's full admin profile by ID, email, or name. Deactivated users surface as not found in this phase. Returns id, names, email, department, manager, custom_properties, locale,… - [Admin list users](https://docs.bonus.ly/reference/adminlistusers.md): List active users in the authenticated caller's company with optional filters: name/email search, department (exact match), role (admin / employee), manager presence (managers / without_manager),… - [Activate user](https://docs.bonus.ly/reference/adminactivateuser.md): Reactivate a deactivated user in the caller's company. Schedules background activation. Required OAuth scope: `user:administer` - [Admin get MCP usage totals](https://docs.bonus.ly/reference/admingetmcpusagetotals.md): Get MCP usage totals by company, user, date range, class, method, or name. Does not track usage. Required OAuth scope: `reports:administer` or `finance:administer` - [Admin get MCP usage details](https://docs.bonus.ly/reference/admingetmcpusagedetails.md): Get MCP usage details by company, user, date range, class, method, or name. Returns per-method totals plus a per-date breakdown of each `(user_id, occurred_at)` event and the distinct `name` values… ## API Reference: Rewards - Rewards - [Get redemption](https://docs.bonus.ly/reference/getredemption.md): Fetch a single reward redemption by its id, scoped to your company. Returns the redemption's state, catalog/reward details, and claim and certificate URLs — the same shape as the… - [Get my redemptions](https://docs.bonus.ly/reference/getmyredemptions.md): List YOUR own reward redemptions (newest first), scoped to your company. Mirrors the `/api/v1/users/:user_id/redemptions` endpoint for the calling user. Returns each redemption's state,…