# Perkville MCP connector

The Perkville connector brings members, point balances, level progress, challenges, locations, and staff into Claude, ChatGPT, Cursor, and the Elaichi Agent, so each person can look up and update loyalty records inside their own Perkville access.

Source: https://elaichi.ai/connectors/perkville/

## Facts

| | |
| --- | --- |
| Application | Perkville |
| Category | Marketing Automation |
| AI tools | 85 |
| Authentication | Connects over OAuth |
| Needs your own OAuth app | Yes |
| MCP endpoint | https://api.elaichi.ai/mcp |
| Works with | Claude, ChatGPT, Cursor, any MCP client, and the Elaichi Agent |
| Tools advertised by name | No. 85 tools is past the 30-tool threshold, so clients use `search_tools` and `execute_tool` |

## What you can ask once Perkville is connected

- Which Perkville challenges have unmet requirements this month?
- List Perkville businesses with the most challenge connections.
- Summarize staff activity across our Perkville challenges this week.

## Connect Perkville in Elaichi

This happens once for the organization, before any client is involved.

1. Open Connections, choose Add connection, and pick Perkville.
2. Optionally set Share with, then press Connect.
3. Supply your own Perkville app, then approve. Perkville needs an OAuth app you register yourself, so bring its client ID and secret. One person does this once for the organization.

Credentials are vaulted and nobody, including the AI, reads them back. The connection becomes a toolbox immediately, so you can curate which Perkville tools are exposed, rename them, or freeze arguments before anyone points a client at it.

## Connect Perkville to Claude

Endpoint: https://api.elaichi.ai/mcp

1. Open Customize, then Connectors.
2. Press Add.
3. Name it, paste the MCP server URL, then Continue.
4. Sign in and approve.

On Team and Enterprise, an Owner adds it once. Everyone else turns it on for themselves.

## Connect Perkville to ChatGPT

Endpoint: https://api.elaichi.ai/mcp

1. Open Plugins, then press the + button.
2. Name it and paste the endpoint into Server URL.
3. Leave Authentication on OAuth, then tick the risk acknowledgement.
4. Press Create, then sign in and approve.

Works on the web today. The plugin directory lives at chatgpt.com/plugins.

## Connect Perkville to Cursor

Endpoint: https://api.elaichi.ai/mcp

1. Open `~/.cursor/mcp.json`.
2. Add the endpoint under `mcpServers`.
3. Reload Cursor, then sign in and approve.

Set up per machine, so repeat it on each computer you work from.

## Connect Perkville to any MCP client

Endpoint: https://api.elaichi.ai/mcp

1. Add the endpoint as a remote MCP server.
2. Sign in and approve.

The Elaichi Agent already has these tools, with nothing to set up.

## What the consent screen decides

Only Read is granted by default, which is not enough to call a Perkville tool. Over MCP there is no trusted place to confirm a write in the moment, so the consent screen is the standing approval rather than a formality. Grant Read and Run tools. Think hard before granting Delete, which reaches into connected apps and cannot be undone.

## What teams do with Perkville through Elaichi

### Answer a balance question at the counter

Front desk. A member asks how many points they have and how close they are to the next level. Ask for the answer by name and get their balance and level progress from Perkville without leaving the conversation.

### See which challenges are actually landing

Marketing. Pull the list of live challenges, their requirements, and how many members have joined each one, then decide which to promote next month.

### Enroll a new member into rewards

Membership. After someone signs up at a location, create their Perkville connection and set the attributes the team tracks, so they start earning from day one.

### Find members stalled below the next level

Retention. Ask for members whose level progress has not moved, and hand the list to whoever runs win-back outreach.

### Check staff across every location

Operations. List the businesses in your Perkville account and the staff attached to each, and spot where a location is missing someone or lists a person who has moved on.

### Fix a member record after a call

Support. A member says their details are wrong. Look up their connection, update it, and confirm the current agreement version they accepted, all in one exchange.

## Frequently asked questions

### How do I connect Perkville to Claude?

Connect Perkville in Elaichi first, then in Claude go to Customize, then Connectors, then Add, and paste https://api.elaichi.ai/mcp. Perkville connects over OAuth, but it asks you to register an OAuth application inside Perkville yourself, so one person brings a client ID and secret to Elaichi once and nobody else ever handles them. After that, each person signs in to Perkville in their browser when Claude first asks.

### Does Perkville work with ChatGPT and Cursor as well as Claude?

Yes. Once Perkville is connected in Elaichi, the same endpoint, https://api.elaichi.ai/mcp, works in Claude, ChatGPT, Cursor, any other MCP client, and the Elaichi Agent. You connect Perkville once and every client sees it.

### What can an AI agent actually do with my Perkville data?

It can look up members and their point balances, check level progress, list challenges and their requirements, see who has joined a challenge, and pull your locations, staff, and agreement versions from Perkville. It can also enroll a member by creating a connection and update an existing one. Perkville exposes many actions, so short, specific asks such as "show Maria's point balance" work better than long sentences.

### Does connecting Perkville give the AI everything in my account?

No. Every request runs as the person who signed in to Perkville, so the AI sees only the locations, members, and staff that person can already see. Elaichi can narrow that further with restrictions per action, and it can never grant more than Perkville itself allows.

### Can my team share one Perkville connection?

Yes. One person connects Perkville in Elaichi and shares it with a team, and nobody else touches the client ID, secret, or any credential. Each teammate still signs in to Elaichi as themselves, so the audit log names the actual person behind every lookup or update in Perkville.

### Can I stop an agent from deleting or changing things in Perkville?

Yes. In Elaichi you can block specific Perkville actions, such as creating or updating a member connection, while leaving lookups open. A blocked action is never shown to Claude, ChatGPT, or Cursor at all, so no prompt, however worded, can reach it.

### What happens to a Perkville connection when someone leaves?

Offboard them in Elaichi and their access to Perkville through every client ends at once. A shared Perkville connection keeps working for everyone else on the team. If you ever want Perkville gone entirely, disconnecting it once in Elaichi removes it from Claude, ChatGPT, Cursor, and the Elaichi Agent together.

## All 85 Perkville tools

Every tool below is callable through https://api.elaichi.ai/mcp once Perkville is connected, subject to the toolbox it is in and the restrictions on the caller.

- **List all Perkville agreement versions** (List). 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). 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). 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). 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). 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). 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). 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). 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). 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). 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). 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). 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). 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). 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). 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). 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). 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). 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). 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). 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). 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). 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). 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). 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). 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). 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). 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). 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). 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). 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). 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). 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). 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** (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). 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). 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). 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). 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). 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). 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). 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). 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). 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). 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). 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). 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). 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). 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). 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). 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). 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). 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). 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). 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). 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). 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). 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). List all Perkville OAuth scopes granted to the bearer token making the request. Returns: scope.
- **List all Perkville transactions** (List). 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). 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). 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** (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). 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). 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** (Create). 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). 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). 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). 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). 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). 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** (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). 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). 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). 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). 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). 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). 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). 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). 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). 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). 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). 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** (Create). 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** (Action). 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** (List). 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.