--- updatedAt: 2026-08-19T07:18:52.000Z --- Fetch the complete documentation index at: https://developers.perk.com/llms.txt. Use this file to discover all available pages before exploring further. Append .md to any documentation page URL to get its markdown version. # Perk MCP tools reference Reference for every Perk MCP tool across trips, users, expenses, invoices, reporting, policy, events, and cards — with each tool's description, required OAuth scope, and read or write behavior. This reference lists every tool the Perk Model Context Protocol (MCP) server exposes, with its description, required scope, and whether it reads or writes. Use it to see which tool an AI client calls for a given task and which scope that tool needs. You can query trips, users, expenses, invoices, reporting, policy, events, and cards; search and book flights, hotels, trains, and cars; and generate reports, create and manage expenses, create a Perk Event, and get a trip approval link. Reporting data is one day behind because it goes through quality checks and aggregation, and reporting access is limited to users with reporting access — analysts and account admins. Expense queries return live data. ## Tools The tables below list all tools available in this release, grouped by category. Tool names are the identifiers the server exposes. Each scope is a colon-separated string that an access token must carry for the tool to run. #### Trips | Tool | Description | Required scope | | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | | `trips_get_trip` | Returns a full trip breakdown: travelers, bookings (flights, hotels, trains, cars), dates, and cost. | `trip:read` | | `trips_list_trips` | Lists trips, filtered by status (upcoming, current, past), destination, traveler, or date range. Returns up to 30 per call. Travel admins and travel managers can list trips for their travelers; travelers see only their own. | `trip:read` | | `trips_get_trip_itinerary_pdf` | Gets the itinerary confirmation PDF download URL for a trip, covering all its bookings (flights, hotels, cars, trains). The trip must have at least one traveler and one booking. | None — follows your Perk permissions | #### Flights | Tool | Description | Required scope | | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | -------------- | | `flights_search_flight_places` | Searches airports and cities by name or IATA code to resolve origin/destination place objects for a flight search. | `trips:write` | | `flights_start_flight_search` | Starts a flight search (one-way, round-trip, or multi-city). Confirms trip type with the user first; returns a transaction ID and trip ID. | `trips:write` | | `flights_get_flight_leg_options` | Polls for flight offers on the current leg of a search, sortable by price, travel time, or best value. Called once per leg on round-trips. | `trips:write` | | `flights_check_visa_requirements` | Checks visa and entry requirements for a flight itinerary's outbound leg, inferring passport nationality from the origin airport. | `trips:write` | | `flights_build_flight_deeplink` | Generates a Perk checkout deep-link for a confirmed flight offer selection. | `trips:write` | #### Hotels | Tool | Description | Required scope | | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | -------------- | | `hotels_start_hotel_search` | Starts a hotel search for a location, always creating a new trip. | `trips:write` | | `hotels_get_hotels` | Fetches hotels matching a started search, with filters for policy compliance, breakfast, cancellation, and loyalty programs. | `trips:write` | | `hotels_start_hotel_rates` | Starts fetching rooms and rates for one hotel from a search. | `trips:write` | | `hotels_get_hotel_rates` | Fetches the rooms and rates for one hotel once `hotels_start_hotel_rates` has run. | `trips:write` | | `hotels_select_hotel_rate` | Adds a chosen hotel rate to the trip. Does not book or pay — the checkout link still requires user confirmation. | `trips:write` | #### Trains | Tool | Description | Required scope | | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -------------- | | `trains_search_train_places` | Searches train stations and cities by name to resolve origin/destination place objects. | `trips:write` | | `trains_start_train_search` | Starts a train search (one-way or round-trip); round-trip return date/time must be committed at this step. | `trips:write` | | `trains_get_train_search_results` | Polls for outbound train offers for a started search. | `trips:write` | | `trains_start_train_search_inbound` | Starts the inbound (return) leg search after the user picks an outbound offer. | `trips:write` | | `trains_get_train_search_inbound_results` | Polls for inbound (return) train offers. | `trips:write` | | `trains_build_train_deeplink` | Generates a Perk checkout deep-link for a confirmed train offer selection (outbound only, or outbound + inbound for round-trip). | `trips:write` | #### Cars | Tool | Description | Required scope | | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -------------- | | `cars_search_car_places` | Searches airports, cities, and addresses by name to resolve pick-up/drop-off place objects. | `trips:write` | | `cars_list_car_delivery_addresses` | Lists the account's car delivery/collection addresses, for accounts with that feature enabled. | `trips:write` | | `cars_start_car_search` | Starts a car rental search for a pick-up/drop-off location and date range. | `trips:write` | | `cars_get_car_search_results` | Fetches available car rental offers for a started search, with filters for supplier, insurance, car type/size, and payment mode. | `trips:write` | | `cars_build_car_deeplink` | Generates a Perk checkout deep-link for a confirmed car rental offer selection. | `trips:write` | #### Users | Tool | Description | Required scope | | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -------------- | | `identity_get_current_user` | Returns the signed-in user's profile, including user ID and cost object. | `user:read` | | `identity_search_users` | Searches users in the account by name, email, role, cost object, manager, or approval process. Returns up to 1,000. Admin-oriented. | `user:read` | #### Expenses | Tool | Description | Required scope | | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | | `expenses_query_expenses` | Queries the signed-in user's expenses by date, status, merchant, amount, or trip association. Returns live data. | `expenses:read` | | `expenses_create_expense` | Creates an expense from a receipt, mileage, or per diem. | `spend:expenses:write` | | `expenses_update_expense` | Edits an expense's memo, category, cost object, or trip link. | `spend:expenses:write` | | `expenses_submit_expense` | Submits an expense for approval. | `spend:expenses:write` | | `expenses_approve_expense` | Approves or sends back a pending expense. The caller must be a valid approver on that expense. | `spend:expenses:write` | | `expenses_receipt_upload` | Uploads a receipt and matches it to an existing card transaction or expense. | `spend:expenses:write` | | `expenses_get_expense_form_options` | Loads selectable options (categories, cost centers, tags, payment methods, and optionally cards) needed before editing an expense. | None — follows your Perk permissions | | `expenses_receipt_upload_fallback` | Alternate receipt upload that sends the file through the MCP server as base64, for use only when the primary signed-URL upload path fails. | `spend:expenses:write` | | `expenses_send_back_expense` | Sends a pending expense back to its submitter for revision with a required reason, as an alternative to `expenses_approve_expense`'s reject path. | `spend:expenses:write` | #### Invoices | Tool | Description | Required scope | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | | `invoices_list_invoices` | Lists invoices for the company, filtered by profile, status, date range, billing period, or serial number. Returns amounts, due dates, and a PDF download link per invoice. | None — follows your Perk permissions | | `invoices_get_invoice` | Returns a single invoice by its serial number, including billing information, tax summary, amounts, a line-items preview, and a PDF download link. | None — follows your Perk permissions | | `invoices_list_invoice_lines` | Lists invoice lines. Each line is a single booked service (flight, hotel, car) with trip metadata, traveler, cost object, tax, and amount. Filter by profile, serial number, or date range. | None — follows your Perk permissions | | `invoices_list_invoice_profiles` | Lists invoice profiles (payment profiles). Each profile holds billing preferences such as payment method, billing address, and billing period. | None — follows your Perk permissions | #### Reporting | Tool | Description | Required scope | | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | | `reporting_create_travel_report` | Starts an asynchronous travel report using Perk's custom report download. Supports a date range of up to 12 months, a date type (booking date, trip start date, or invoice issue date), and filters such as cost object, payment profile, legal entity, traveler, and payment recipient. Covers around 90 fields (flights, hotels, cars, trains, taxes, invoices, CO2 emissions, policy compliance). Returns a task ID to poll with `reporting_get_travel_report` or `reporting_get_travel_report_data`. | `report:write` | | `reporting_get_travel_report` | Polls the status of a report started by `reporting_create_travel_report`. When the report is ready, returns a CSV or XLSX download link. Generate first, then poll to download. | `report:write` | | `reporting_get_travel_report_data` | Polls a report started by `reporting_create_travel_report` and returns structured JSON rows (paginated via a cursor) instead of a file. Use `reporting_get_travel_report` when you need a CSV or XLSX export. | `report:write` | | `reporting_create_spend_report` | Starts an asynchronous, organization-wide spend report, optionally filtered by legal entity or user set. Returns a task ID to poll with `reporting_get_spend_report`. | `report:write` | | `reporting_get_spend_report` | Polls the status of a spend report started by `reporting_create_spend_report`. When ready, returns a signed download link. | `report:write` | | `reporting_create_team_insights_report` | Starts an asynchronous Team Insights report for the authenticated user's team — available to line managers (direct reports), cost object owners (people who booked against their cost objects), and approvers (trips they or a delegate approved). Covers traveler details, trip/booking info, travel spend, policy violations, and cost allocation, up to a 12-month range with dates filtered by expense date. Only covers travel data, excludes expense data. `until` must be yesterday or earlier. Returns a task ID to poll with `reporting_get_team_insights_report_data`. | `team-insights-report:write` | | `reporting_get_team_insights_report_data` | Polls a report started by `reporting_create_team_insights_report` and returns structured JSON rows (one row per booking), paginated via a cursor. Set `limit` on the first call only (default and max 2,000). | `team-insights-report:write` | #### Policy | Tool | Description | Required scope | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | | `policies_get_travel_policy` | Returns the user's travel policy rules for a vertical (flights, hotels, cars, or trains): budget limits, booking windows, and cabin or star restrictions. Returns null when the user has no travel policy assigned. | `my-travel-policy:read` | #### Events | Tool | Description | Required scope | | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | | `events_list_events` | Lists Perk Events the user can see (organizing, invited, attending, or account-visible). Filter by `date_filter` (upcoming, past, no\_dates) and `status` (all, organizing, attending, invited). Paginated, 5 per page. | None — follows your Perk permissions | | `events_list_event_attendance` | Lists attendees for a specific Perk Event, with RSVP status and person details. The caller must be an event organizer. Takes a required `event_id`, plus `attending` (attending, not\_attending, no\_response, uninvited) and `search` filters. Paginated (default 20, max 100 per page). | None — follows your Perk permissions | | `events_create_event` | Creates a new Perk Event. `name`, `location`, `start_date`, and `end_date` are required. Perk creates the event as private and published by default. | `events:write` | #### Cards & transactions | Tool | Description | Required scope | | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | | `transactions_list_available_cards` | Lists your own company cards plus any lodge cards in your company — the cards you can submit expenses against. No parameters; the user and company resolve from your identity. No pagination. Requires a Spend subscription. | None — follows your Perk permissions | | `transactions_list_pending` | Lists your pending card transactions — unmatched, open transactions on your cards that still need matching to an expense. No parameters; lodge-card transactions are excluded. No pagination. Requires a Spend subscription. | None — follows your Perk permissions | #### Approvals | Tool | Description | Required scope | | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -------------------------- | | `approvals_get_trip_approval_links` | Gets a link the user can open to approve or decline a specific trip — the same as acting from an email, Slack, or Teams message. | `trip-approval-links:read` | ## Reporting data freshness Reporting data in the Perk MCP server is one day behind. It goes through quality checks and aggregation before it becomes available, so a travel report or spend query reflects data up to the previous day. Expense queries are the exception. The `expenses_query_expenses` tool returns live data in real time. ## Reporting access Reporting access in the Perk MCP server is limited to users with reporting access — analysts and account admins. Comma-separated values (CSV) and XLSX report downloads depend on this access. The access token is scoped to your role and your company's active plan through role-based access control (RBAC). A tool call returns only the data your role permits, so a client can only read what you can already access in Perk. When using the Perk MCP to retrieve travel and spend reporting, you may need to add these domains: * storage.googleapis.com * \*.amazonaws.com