--- title: Perkville API Integration on Truto slug: perkville category: Marketing Automation canonical: "https://truto.one/integrations/detail/perkville/" --- # Perkville API Integration on Truto **Category:** Marketing Automation **Status:** Beta ## MCP-ready AI tools Truto exposes 85 tools for Perkville that AI agents can call directly. - **list_all_perkville_agreement_versions** — List Perkville agreement versions for a business or agreement. Returns: agreement_version_id, agreement_id, agreement_internal_name, agreement_type, apply_to_join_flow, business, version, text, is_active, created_dt, last_mod_dt, resource_uri. At least one of the agreement or business filter is required; business__in queries are not supported. - **get_single_perkville_agreement_version_by_id** — Get a single Perkville agreement version by id. Returns: agreement_version_id, agreement_id, agreement_internal_name, agreement_type, apply_to_join_flow, business, version, text, is_active, created_dt, last_mod_dt, resource_uri, address_1, address_2, city, country_code, external_location_id, latitude, location_id, longitude, name, postal_code, state. Required: id. - **list_all_perkville_businesses** — List Perkville businesses, each representing a single rewards program for a real-world business. Returns: business_id, categories, fine_print, homepage_url, locations, name, logo_url, brand_color, brand_secondary_color, promotions, perks, perkville_url, resource_uri, rewards_program_name, app_connection_message, loyalty_launch_dt, prelaunch_info_message, allow_referrals_before_start_dt,… - **get_single_perkville_business_by_id** — Get a single Perkville business by id. Returns the full business object including business_id, name, rewards_program_name, categories, locations, promotions, perks, homepage_url, resource_uri, fine_print, brand_color, brand_secondary_color, logo_url, perkville_url, app_connection_message, loyalty_launch_dt, prelaunch_info_message, allow_referrals_before_start_dt,… - **list_all_perkville_staff** — List business staff members in Perkville. Results are filtered to only return staff at businesses where the token owner is also a staff member. Returns: staff_id, business, created, bill_payer, resource_uri, staff_role, staff_description, user. Filterable by business, bill_payer, staff_role, and user. - **get_single_perkville_staff_by_id** — Get a single business staff member in Perkville by id. Returns: staff_id, business, created, bill_payer, resource_uri, staff_role, staff_description, user, address_1, address_2, city, country_code, external_location_id, latitude, location_id, longitude, name, postal_code, state. Required: id. - **list_all_perkville_challenges** — List Perkville challenges, filterable by challenge_id, business, name, or slug. Returns: challenge_id, business, name, slug, description, fine_print, join_message, ineligible_message, success_message, incomplete_message, locations, home_locations, start_date, end_date, use_membership_start_date, membership_join_start_date, membership_join_end_date, require_active_membership, resource_uri,… - **get_single_perkville_challenge_by_id** — Get a single Perkville challenge by id. Returns: challenge_id, business, name, slug, description, fine_print, join_message, ineligible_message, success_message, incomplete_message, locations, home_locations, start_date, end_date, use_membership_start_date, membership_join_start_date, membership_join_end_date, require_active_membership, resource_uri, valid_customer_attributes, address_1,… - **list_all_perkville_challenge_connections** — List challenge connections in Perkville. A challenge connection represents the relationship between a user and a challenge (rewards program) at a business. At least one of the business, user, email, connection or challenge filters is required. Returns: business, challenge, completed, completed_dt, connection, created_dt, end_date, join_dt, join_status, last_mod_dt, start_date, resource_uri and location details. - **get_single_perkville_challenge_connection_by_id** — Get a specific challenge connection in Perkville by id. A challenge connection represents the relationship between a user and a challenge (rewards program) at a business. Returns: business, challenge, completed, completed_dt, connection, created_dt, end_date, join_dt, join_status, last_mod_dt, resource_uri, start_date, address_1, address_2, city, country_code, external_location_id, latitude,… - **list_all_perkville_challenge_connection_requirement_summaries** — List Challenge Connection Requirement Summaries in Perkville, tracking each Challenge Connection's progress toward a Challenge Perk Requirement. Returns: challenge, challenge_connection, challenge_perk_requirement, earned_quantity, completed_requirement, completed_dt, created_dt, last_mod_dt, resource_uri. - **get_challenge_connection_requirement_summary_by_id** — Get a Perkville challenge connection requirement summary by id. The summary represents the relationship between a Challenge Connection and a Challenge Perk Requirement. Returns: challenge, challenge_connection, challenge_perk_requirement, completed_dt, completed_requirement, created_dt, earned_quantity, last_mod_dt, resource_uri, address_1, address_2, business, city, country_code,… - **list_all_perkville_challenge_requirements** — List Challenge Perk Requirements in Perkville, which define how many times a user must earn a Perk to complete a requirement for a single Challenge. Returns: challenge_perk_requirement_id, challenge, business, title, description, required_quantity, progress_perk, display_order, detail_link, resource_uri. - **get_single_perkville_challenge_requirement_by_id** — Get a challenge perk requirement by id in Perkville. A challenge perk requirement is a rule defining how many times a user must earn a perk before completing a requirement for a single challenge. Returns the requirement object including challenge_perk_requirement_id, title, description, required_quantity, progress_perk, challenge, business, and resource_uri. Required: id. - **list_all_perkville_connections** — List connections in Perkville. A connection joins a user to a business's rewards program and tracks their point balance, lifetime earned points, membership status and vouchers. At least one of the business or user filters is required; also supports filtering by email, external membership status and last-modified date range, with limit/offset pagination. Returns Connection objects. - **get_single_perkville_connection_by_id** — Get a single Perkville connection by id. A connection joins a user to a business's rewards program. Returns: connection_id, business, user, status, point_balance, lifetime_earned_points, external_member_id, external_membership_status, external_membership_type, external_join_dt, external_cancel_dt, rewards_program_join_dt, home_location, last_visited_location, last_transaction_dt, last_mod_dt, level, referral_offer_url, vouchers, resource_uri. - **create_a_perkville_connection** — Create a connection in Perkville to join a user to a business's loyalty program. Returns the created connection including business, user, status, point_balance, lifetime_earned_points, and resource_uri. Required: business and exactly one of user or user_email. - **update_a_perkville_connection_by_id** — Update a Perkville connection by id. With user-level access only the status field can be changed (to ACTIVE or INACTIVE). With admin access the external membership fields (external_join_dt, external_cancel_dt, external_membership_status, external_membership_type, external_home_location_id, home_location) can also be updated. Returns the updated Connection object. - **list_all_perkville_connection_attributes** — List connection attributes in Perkville, which record custom attribute values assigned to a business's customer connections. Returns: added_dt, connection, custom_attribute_value, resource_uri. At least one filter (connection or custom_attribute_value) is required when no id is specified. - **get_single_perkville_connection_attribute_by_id** — Get a single connection attribute by id in Perkville. Returns: added_dt, connection, custom_attribute_value, resource_uri, address_1, address_2, business, city, country_code, external_location_id, latitude, location_id, longitude, name, postal_code, state. Required: id. - **list_all_perkville_connection_balances** — List connection balances in Perkville for recently updated point balances of connections at a business. Returns: business, connection, last_biz_perk_title, last_mod_dt, last_transaction_dt, lifetime_earned_points, lifetime_spent_points, point_balance, resource_uri, user. At least one of business, user, email, or connection filter is required for list requests without a connection_balance_id;… - **get_single_perkville_connection_balance_by_id** — Get a single Perkville connection balance by id. Returns the point balance of a connection, including lifetime earned and spent points, business and connection references, last transaction date, and user. Returns: business, connection, last_biz_perk_title, last_mod_dt, last_transaction_dt, lifetime_earned_points, lifetime_spent_points, point_balance, resource_uri, user, address_1, address_2,… - **list_all_perkville_connection_level_progress** — List Perkville connection level progress records for a business, ordered by most recent last_mod_dt descending. Returns each connection's current level progress snapshot including business, connection, user, current_level_info, next_level_info, and requalification_info. Required: business. - **list_all_perkville_custom_attributes** — List custom attributes created by businesses in Perkville. Returns: business, display_name, display_action, description, resource_uri, slug. - **get_single_perkville_custom_attribute_by_id** — Get a single custom attribute in Perkville by id. Returns: business, description, display_action, display_name, resource_uri, slug, address_1, address_2, city, country_code, external_location_id, latitude, location_id, longitude, name, postal_code, state. Required: id. - **list_all_perkville_custom_attribute_values** — List custom attribute values in Perkville. Without a filter, returns values for all custom attributes at all businesses authorized for the bearer token user; use the custom_attribute filter to narrow results to a specific attribute. Returns: custom_attribute, display_name, order, resource_uri. - **get_single_perkville_custom_attribute_value_by_id** — Get a single custom attribute value by id in Perkville. Returns: custom_attribute, display_name, order, resource_uri, address_1, address_2, business, city, country_code, external_location_id, latitude, location_id, longitude, name, postal_code, state. Required: id. - **list_all_perkville_email_tracking** — List emails sent from Perkville businesses associated with the API token. Returns: business_id, location_id, resource_uri, sent_dt, type, user_email, user_id. Supports filtering on business_id, sent_dt, type, user_email, and user_id. - **get_single_perkville_email_tracking_by_id** — Get a single email tracking record by id. Returns: business_id, location_id, resource_uri, sent_dt, type, user_email, user_id, address_1, address_2, business, city, country_code, external_location_id, latitude, longitude, name, postal_code, state. Required: id. - **list_all_perkville_external_locations** — List External Locations in Perkville that associate a Perkville Location with an ID in another system. The combination of external_system_id and external_location_id is unique system-wide. Returns: id, external_system_id, external_location_id, location. - **get_single_perkville_external_location_by_id** — Get a single External Location in Perkville by id. Returns: id, external_system_id, external_location_id, location, address_1, address_2, business, city, country_code, latitude, location_id, longitude, name, postal_code, resource_uri, state. Required: id. - **list_all_perkville_external_members** — List external members at a business in Perkville. Returns: business, connection, user, resource_uri, external_system_id, external_member_id, external_membership_type, external_membership_status, home_location, external_cancel_dt, external_join_dt, user_id, resource_id, connection_id, home_location_id. Required: at least one of business or user. The external_member_id filter also requires… - **get_single_perkville_external_member_by_id** — Get a Perkville external member by id. Returns the full membership record including business, connection, user, external_member_id, external_system_id, external_membership_status, external_membership_type, external_join_dt, external_cancel_dt, home_location, resource_uri, created_dt, and last_mod_dt. Required: id. - **perkville_external_members_bulk_create** — Batch create or update external members in Perkville, upserting by external_member_id and external_system_id. Returns: business, external_members, address_1, address_2, city, country_code, external_location_id, latitude, location_id, longitude, name, postal_code, resource_uri, state. Required: business, external_members. Max 50 members per request. - **list_all_perkville_frequency_bonus_perks** — List Frequency Bonus Perks in Perkville. A frequency bonus perk is awarded when users earn qualifying perks a certain number of times within a defined period. Returns: frequency_bonus_perk_id, business, frequency, required_to_earn, qualifying_perks, reward, resource_uri, address_1, address_2, city, country_code, external_location_id, latitude, location_id, longitude, name, postal_code, state. - **get_single_perkville_frequency_bonus_perk_by_id** — Get a Perkville frequency bonus perk by id. A frequency bonus perk is awarded when a user earns a qualifying perk a certain number of times within a given period. Returns: frequency_bonus_perk_id, business, frequency, required_to_earn, qualifying_perks, reward, resource_uri, address_1, address_2, city, country_code, external_location_id, latitude, location_id, longitude, name, postal_code, state.… - **list_all_perkville_frequency_bonus_progress** — List Perkville frequency bonus progress records showing each user's progress towards frequency bonus perks. Returns: frequency_bonus_progress_id, business, user, frequency_bonus_perk, progress_count, has_earned_bonus, resource_uri. Records appear only when a user has earned at least once in the current time period; users with no activity in the period return no records. Filterable by… - **get_single_perkville_frequency_bonus_progress_by_id** — Get a single Perkville frequency bonus progress record by id. Returns: frequency_bonus_progress_id, business, user, frequency_bonus_perk, progress_count, has_earned_bonus, resource_uri, address_1, address_2, city, country_code, external_location_id, latitude, location_id, longitude, name, postal_code, state. Required: id. - **list_all_perkville_levels** — List loyalty program levels for a business in Perkville. Returns: level_id, business, name, point_floor, badge_url, resource_uri. Required: business. - **get_single_perkville_level_by_id** — Get a single Perkville level by id. Returns: level_id, business, name, point_floor, badge_url, resource_uri, address_1, address_2, city, country_code, external_location_id, latitude, location_id, longitude, postal_code, state. Required: id. - **list_all_perkville_locations** — List physical business locations in Perkville. Returns: location_id, name, business, address_1, address_2, city, state, postal_code, country_code, latitude, longitude, external_location_id, resource_uri. - **get_single_perkville_location_by_id** — Get a single Perkville location by id. Returns: location_id, name, address_1, address_2, city, state, postal_code, country_code, latitude, longitude, business, external_location_id, resource_uri. Required: id. - **list_all_perkville_perks** — List perks (reward rules) for a business in Perkville. Perks are organized into earning or redemption classifications. Returns: perk_id, business, category, classification, title, description, points, type, fine_print, redemption_instructions, expiration_days, eligible_at_all_locations, eligible_locations, external_coupon_code, initial_voucher_status, instant_rewards,… - **get_single_perkville_perk_by_id** — Get a single Perk in Perkville by id. A Perk is a rewards rule for a business — either an earning rule or a redemption rule. Returns: perk_id, business, category, classification, title, description, points, type, fine_print, redemption_instructions, expiration_days, eligible_at_all_locations, eligible_locations, external_coupon_code, initial_voucher_status, instant_rewards,… - **create_a_perkville_perk** — Create a perk (reward rule) for a business in Perkville. Perks are classified as EARN (points awarded to a customer for an action) or REDEEM (points spent by a customer for a reward), and can carry fine print, redemption instructions, voucher expiration and location eligibility. Returns the created Perk object. Required: business, classification, title, points. - **update_a_perkville_perk_by_id** — Update an existing Perkville perk by id. Returns the updated perk object including perk_id, title, points, type, classification, description, eligible_locations, fine_print, and resource_uri. Required: id. - **list_all_perkville_perk_categories** — List Perkville perk categories for a business. A perk category groups perks for display purposes. Returns: category_id, category_name, business, type, display_order, perks, resource_uri, created_dt, last_mod_dt. Required: business. - **get_single_perkville_perk_category_by_id** — Get a single Perkville perk category by id. Returns: category_id, category_name, business, type, display_order, perks, resource_uri, created_dt, last_mod_dt, address_1, address_2, city, country_code, external_location_id, latitude, location_id, longitude, name, postal_code, state. Required: id. - **list_all_perkville_promotions** — List promotions (special perks such as Referral Promotions) for a Perkville business. Returns: business, detail, eligible_at_all_locations, eligible_locations, fine_print, perk, picture_uri, picture_url, title, type. Required: business. - **get_single_perkville_promotion_by_id** — Get a single Perkville promotion by id. A Promotion is a special perk created by a business, currently including Referral Promotions. Returns: business, detail, eligible_at_all_locations, eligible_locations, fine_print, perk, picture_uri, picture_url, title, type, address_1, address_2, city, country_code, external_location_id, latitude, location_id, longitude, name, postal_code, resource_uri,… - **list_all_perkville_recurring_bonus_perks** — List Recurring Bonus Perks in Perkville. A Recurring Bonus Perk is awarded when a user earns a qualifying perk a certain number of times, after which progress carries forward for the next earn. Returns: recurring_bonus_perk_id, business, qualifying_perk, points, instant_rewards, required_to_earn, start_date, resource_uri and location details. - **get_single_perkville_recurring_bonus_perk_by_id** — Get a single Recurring Bonus Perk in Perkville by id. A Recurring Bonus Perk is awarded when a user earns a qualifying perk a certain number of times, after which progress carries forward for the next earn. Returns: recurring_bonus_perk_id, business, qualifying_perk, points, instant_rewards, required_to_earn, start_date, resource_uri, address_1, address_2, city, country_code,… - **list_all_perkville_recurring_bonus_progress** — List recurring bonus progress records in Perkville showing each user's progress towards a recurring bonus perk. Returns: recurring_bonus_progress_id, business, user, recurring_bonus_perk, progress_count, times_earned, cycle_start_date, resource_uri. Records are excluded for staff members not authorized for all locations at a business. - **get_single_perkville_recurring_bonus_progress_by_id** — Get a single recurring bonus progress record by id in Perkville. Returns: recurring_bonus_progress_id, business, user, recurring_bonus_perk, progress_count, times_earned, cycle_start_date, resource_uri, address_1, address_2, city, country_code, external_location_id, latitude, location_id, longitude, name, postal_code, state. Required: id. - **list_all_perkville_referrals** — List Perkville referrals between users at a business. Returns the referral record including business, referral_status, referral_source, referrer_conn_status, referral_from_user, referral_to_user, created_dt, completed_dt, voucher, voucher_id, and resource_uri. Filterable by business, referral_status, created_dt, completed_dt, location, referral_from_user, referral_to_user. - **get_single_perkville_referral_by_id** — Get a single Perkville referral by id. Returns: business, completed_dt, created_dt, distribution_type, location, referral_content, referral_date, referral_from_user, referral_source, referral_status, referral_to_email, referral_to_user, referree_external_id, referree_external_id_type, referrer_conn_status, resource_uri, voucher, voucher_id, address_1, address_2, city, country_code,… - **create_a_perkville_referral** — Create a Perkville referral between two users at a specified business. Returns the created referral including business, referral_from_user, referral_to_email, referral_status, referral_source, created_dt, distribution_type, resource_uri. Required: business, referral_from_user, referral_to_email. - **list_all_perkville_scopes** — List all Perkville OAuth scopes granted to the bearer token making the request. Returns: scope. - **list_all_perkville_transactions** — List Perkville transactions, optionally filtered by user, business, date range, or perk classification. Returns: transaction_id, classification, title, trans_source_id, perk_id, business_id, business, transaction_status, trans_status, points, transaction_dt, last_mod_dt, user_id, transaction_reference, location_id, locations_id, quantity. - **get_single_perkville_transaction_by_id** — Get a single Perkville transaction by id. Returns: transaction_id, classification, title, trans_source_id, perk_id, business_id, business, transaction_status, trans_status, points, transaction_dt, last_mod_dt, user_id, transaction_reference, location_id, locations_id, quantity, address_1, address_2, city, country_code, external_location_id, latitude, longitude, name, postal_code, resource_uri,… - **create_a_perkville_transaction** — Create or award points transactions in Perkville. Returns the created transaction including transaction_id, classification, title, points, transaction_dt, last_mod_dt, user_id, business_id, perk_id, and quantity. Required: business and exactly one of user or user_email. - **perkville_transactions_bulk_create** — Batch create up to 200 transactions for a given Perkville business in a single request. Returns a list of result objects in the same order as the input — successful entries include the created transaction's business, transaction_dt, transaction_id, transaction_reference, and transaction_status; failed entries include an errors object. Required: business, transactions. Limit of 200 transactions… - **list_all_perkville_void_transactions** — List voided transaction records in Perkville. A void creates a new transaction with the negative amount of the original and marks the original as VOID. Returns: transaction_id, business, transaction_status, transaction_reference, trans_source_id, transaction_dt, last_mod_dt. - **get_single_perkville_void_transaction_by_id** — Get a specific void transaction in Perkville by id. Returns: business, last_mod_dt, trans_source_id, transaction_dt, transaction_id, transaction_reference, transaction_status, address_1, address_2, city, country_code, external_location_id, latitude, location_id, longitude, name, postal_code, resource_uri, state. Required: id. - **create_a_perkville_void_transaction** — Void a Perkville transaction by creating a new transaction with the negative amount of the original and marking the original as VOID. Returns: business, last_mod_dt, trans_source_id, transaction_dt, transaction_id, transaction_reference, transaction_status, address_1, address_2, city, country_code, external_location_id, latitude, location_id, longitude, name, postal_code, resource_uri, state.… - **list_all_perkville_users** — List Perkville users, filterable by email, user_id, last_mod_dt, or Identify User Flow code. Returns: user_id, first_name, last_name, phone_number, birthday, emails, connections, last_mod_dt, resource_uri. - **get_single_perkville_user_by_id** — Get a single Perkville user by id. Returns: user_id, first_name, last_name, phone_number, birthday, emails, connections, resource_uri, last_mod_dt, address_1, address_2, business, city, country_code, external_location_id, latitude, location_id, longitude, name, postal_code, state. Required: id. - **list_all_perkville_user_business_agreements** — List user business agreements in Perkville. A business filter is required for list requests. Returns: id, agreement_id, agreement_version, business, user, email, first_name, last_name, agreement_dt, resource_uri. Required: business. The business__in filter style is not supported. - **get_single_perkville_user_business_agreement_by_id** — Get a single user business agreement by id in Perkville. Returns: id, agreement_id, agreement_version, business, user, email, first_name, last_name, agreement_dt, resource_uri, address_1, address_2, city, country_code, external_location_id, latitude, location_id, longitude, name, postal_code, state. Required: id. - **create_a_perkville_user_business_agreement** — Create a user business agreement acceptance in Perkville, recording that a user has agreed to a business's agreement terms. Returns: agreement_dt, agreement_id, agreement_version, business, email, first_name, last_name, resource_uri, user, address_1, address_2, city, country_code, external_location_id, latitude, location_id, longitude, name, postal_code, state. Required: business, agreement_id,… - **perkville_user_business_agreements_bulk_create** — Bulk create user business agreement records for a Perkville business to record acceptance of join-flow agreement terms for one or more users. Returns: business, user_business_agreements, address_1, address_2, city, country_code, external_location_id, latitude, location_id, longitude, name, postal_code, resource_uri, state. Required: business, user_business_agreements. Limit of 50 records per… - **get_single_perkville_voucher_by_id** — Get a single voucher in Perkville by id. A voucher represents a redeemed reward coupon created when a customer redeems points. Returns: voucher_id, business, created_datetime, details, expiration_date, external_coupon_code, location, network_reward_url, perk, perk_description, perk_fine_print, point_cost, promotion_fine_print, status, title, user, address_1, address_2, city, country_code,… - **update_a_perkville_voucher_by_id** — Update a Perkville voucher by changing its status (mark as USED) and/or expiration date. Returns the patched voucher object including voucher_id, status, title, business, user, perk, point_cost, expiration_date, and details. Required: id. - **list_all_perkville_vouchers** — List Perkville vouchers, filtered by business and optionally by user. Returns: voucher_id, status, business, user, perk, location, transaction, created_datetime, expiration_date, point_cost, resource_uri, external_coupon_code, marketplace_business, network_reward_url. The business parameter is required unless filtering by voucher_id. - **list_all_perkville_challenges_view** — List challenges from a user's perspective in Perkville, including completion rewards, requirement progress, and user-specific eligibility and join status. Returns: challenge_id, name, user_display_status, join_status, requirements, completion_rewards, restriction_reasons. Required: business. Challenges are returned in the order Perkville displays them to users. - **list_all_perkville_earning_view** — List a Perkville business' earning rules from a user's perspective, including active bonuses and user-specific progress and eligibility details. Returns: business, completes_referral, date_range_bonuses, description, display_name, display_order, frequency_bonuses, recurring_bonuses, instant_rewards, loc_id, perk_id, points, referral_eligibility_days, referral_eligibility_explanation,… - **list_all_perkville_levels_view** — List user-facing levels for a Perkville business in display order, including unlock requirements and user-specific status such as current level and progress. Returns: business, level_id, name, point_floor, require_active_membership, unlocked_dt, is_current_level, badge_url, unlockable_perks, unlockable_privileges, points_accumulated_toward_level, points_until_this_level, level_validity_interval,… - **list_all_perkville_redeeming_view** — List a Perkville business's redeemable rewards from the perspective of a user. Results are location-specific by default; set all_locs=true to return perks across all locations. Returns: business, can_redeem, description, display_order, external_reward_url, fine_print, from_date, loc_id, must_redeem_at_home_location, perk_id, picture_card, points, redemption_instructions, redemption_limit_count,… - **list_all_perkville_agreements_view** — List user-facing agreement terms by business in Perkville, including active agreement text, version, and whether the user has agreed. Returns: business, agreement_id, agreement_type, apply_to_join_flow, agreement_version_id, version, text, is_active, has_agreed, agreed_dt. Required: business. - **get_single_perkville_user_voucher_by_id** — Get a specific user voucher in Perkville by id, returning user-facing details beyond the base Voucher endpoint including title, perk description, fine print, perk use type, and status. Returns: voucher_id, title, status, perk, perk_description, perk_fine_print, point_cost, created_datetime. Required: id. - **list_all_perkville_top_earners** — List top earners at a Perkville business by points earned in descending order. Returns: first_name, last_name, user_id, last_earned_location_id, home_location_id, points_earned, connection_id, primary_email_address, primary_user_address. Required: business. - **list_all_perkville_transaction_report** — List transactions at a Perkville business by business primary key without requiring a specific user. Returns: transaction_id, business_id, user_id, points, classification, title, trans_status, transaction_dt, last_mod_dt, perk_id, locations_id, quantity, trans_source_id. Required: business_id. For best performance, filter by (business_id, from_datetime, to_datetime) or (business_id,… - **create_a_perkville_identify** — Generate a single-use, short-lived Identify Token in Perkville to initiate the identify user flow. Returns: identify_token, expire_datetime, staff_id, business, created, bill_payer, resource_uri, staff_role, staff_description, user. The token is valid for 30 minutes from creation and becomes invalid after first use. - **perkville_oauth_token** — Exchange an authorization code or user password for a Perkville OAuth2 access token. Returns: access_token, scopes, staff_id, business, created, bill_payer, resource_uri, staff_role, staff_description, user. Required: grant_type, plus either (code and redirect_uri) for the authorization_code grant or (username and password) for the password grant; client_id is always required. The authorization… - **list_all_perkville_me** — Get the current authenticated Perkville user. Returns: user_id, first_name, last_name, last_mod_dt, phone_number, birthday, emails, connections, resource_uri, address_1, address_2, business, city, country_code, external_location_id, latitude, location_id, longitude, name, postal_code, state. ## How it works 1. **Link your customer's Perkville account.** Use Truto's frontend SDK; we handle every OAuth and API key flow so you don't need to create the OAuth app. 2. **Authentication is automatic.** Truto refreshes tokens, stores credentials securely, and injects them into every API request. 3. **Call Truto's API to reach Perkville.** The Proxy API is a 1-to-1 mapping of the Perkville API. 4. **Get a unified response format.** Every response uses a single shape, with cursor-based pagination and data in the `result` field. ## Use cases - **Embed loyalty into fitness and wellness booking software** — Studio scheduling and membership platforms can offer their gym, yoga, and spa customers a fully managed points, tiers, and referral engine without building one in-house. Class check-ins and package purchases automatically translate into loyalty rewards inside your product. - **Add loyalty-aware checkout to a POS or payments product** — Retail and service POS platforms can surface available vouchers at the register and mark them redeemed the moment a discount is applied. This lets your merchants run sophisticated loyalty programs directly from the checkout flow you already own. - **Power referral-driven growth inside a vertical CRM** — CRMs for gyms, salons, and wellness brands can pull referral activity into their pipeline and automate follow-up on referred prospects. Your users get closed-loop attribution from referral send through paying member without leaving your CRM. - **Ship a native member rewards experience in white-label mobile apps** — App builders can render a member's tier badge, point balance, active challenges, and earning opportunities inside their own branded app. This turns a plain member portal into a gamified retention surface backed by Perkville data. - **Sync membership rosters between your platform and Perkville** — Any SaaS that owns the customer record — CRMs, membership managers, gym management systems — can keep Perkville's member directory continuously aligned with theirs. Members, locations, and identifiers stay consistent so loyalty actions always attribute correctly. ## What you can build - **Bulk member roster sync** — Upsert up to 50 external members per call from your CRM into Perkville, mapping your internal customer IDs to Perkville accounts for reliable attribution. - **Real-time point awarding from transactions and check-ins** — Push single or bulk transactions (up to 200 at a time) when customers buy, visit, or complete an action, using trans_source_id for idempotent, retry-safe writes. - **Refund-aware point reversals** — Automatically create void transactions when your platform processes a refund or cancels a booking, so point balances stay in sync with real revenue. - **In-app tier and challenge widgets** — Use the levels, challenges, and earning views to render a member's current tier, progress bar, badge URL, and active gamification challenges natively in your UI. - **Voucher redemption at checkout** — List a customer's available vouchers at the register, apply the chosen discount in your cart, and update the voucher status to redeemed to close the loop. - **Referral capture and lead routing** — Pull new referrals from Perkville into your CRM or marketing automation to enroll referred prospects in nurture campaigns and track conversion back to the referring member. ## FAQs ### How does authentication with Perkville work through Truto? Perkville uses OAuth-based authentication, and Truto handles the full token exchange and refresh lifecycle for you via the perkville_oauth_token flow. Your end users connect their Perkville account once through Truto's connection UI or API, and you receive a stable connection to make calls against. ### Can I write data back to Perkville, or is it read-only? It's fully two-way. You can create transactions, void transactions, perks, referrals, connections, user business agreements, and identify calls, and you can update connections, perks, and vouchers. This covers point awarding, refunds, voucher redemption, and member onboarding workflows. ### How do I handle high-volume writes like nightly transaction syncs? Perkville supports bulk endpoints for the highest-volume resources — up to 200 records per call for transactions and up to 50 per call for external members and user business agreements. Use trans_source_id on transactions to make bulk writes idempotent and safe to retry. ### How do I make sure loyalty actions attribute to the correct customer in my system? Use the external members resource to map your internal customer identifiers to Perkville accounts. Once members are upserted with your external_system_id, subsequent transactions, referrals, and lookups can be reliably tied back to the right record on both sides. ### Can I build a member-facing UI without stitching together multiple raw endpoints? Yes. Perkville exposes purpose-built view endpoints — earning view, levels view, challenges view, redeeming view, agreements view — that return pre-shaped data optimized for rendering member dashboards, tier progress, and gamification widgets directly in your app. ### Does Truto support custom fields defined in a merchant's Perkville account? Yes. You can list and fetch custom attributes and custom attribute values, as well as connection attributes, so any merchant-specific fields configured in Perkville are accessible through the same connection without special handling. ## Related reading - [Connect Perkville to Claude: Manage Rewards and Referral Programs](https://truto.one/blog/connect-perkville-to-claude-manage-rewards-and-referral-programs/) — Learn how to build a secure, managed MCP server for Perkville to connect your rewards, points, and referral programs directly to Claude. - [Connect Perkville to ChatGPT: Sync Loyalty Rules and User Points](https://truto.one/blog/connect-perkville-to-chatgpt-sync-loyalty-rules-and-user-points/) — Learn how to connect Perkville to chatgpt using Truto. Step-by-step guide to tool calling, API quirks, and autonomous workflows. - [Connect Perkville to AI Agents: Orchestrate Tiers & Transactions](https://truto.one/blog/connect-perkville-to-ai-agents-orchestrate-tiers-and-transactions/) — Learn how to connect Perkville to AI agents using Truto's /tools endpoint. Build autonomous workflows for loyalty tiers, point transactions, and referrals.