LogoLogo
  • Overview
    • About
    • Integrations
      • Perkville API
      • Partners
      • Integrating Perkville
        • API requirements
        • Automating your program using Perkville's API
        • Integrating Your Mobile App with Perkville
          • Page to initiate the PKCE flow.
          • Joining the loyalty program
          • Referral page
            • Referred prospects
          • Point history page
          • Earning rules page
          • Rewards page
            • Redeem confirmation page
          • Vouchers page
            • Mark voucher used confirmation page
          • Challenges page
            • Challenge details page
      • Integration Reference
        • ABC Ignite
          • ABC Ignite Engagement app
            • Home screen
            • Intro page
            • Authorize ABC Fitness page
            • Points page
            • Earning page
            • Rewards page
              • Redeem reward
              • Reward voucher
            • Referral page
        • Mariana Tek
        • Shopify
    • Security
  • Features
    • Loyalty program rules
      • Earning rules
        • Join
        • Birthday
        • Custom
        • Referral
          • Referral offer
          • Completing a referral
          • Referral flow
            • 1. Share referral offer
            • 2.Receive referral offer
            • 3. View offer details
            • 4. Claim offer
            • 5. Receive voucher
            • 6. Earn points for completed referral
        • Twitter (X)
        • Activities
      • Redeeming rules
        • Custom rewards
          • Initial voucher status
        • External rewards
    • Promotions
      • Frequency bonus
        • For customers: How a monthly/weekly bonus works
      • Time bonus
      • Promotion bonus
    • Challenges
      • Creating a challenge
      • Manually adding challenge progress
    • Emails
      • Invitations
      • Point earning notification
      • Weekly summary
      • Redemption
      • Challenge emails
        • Challenge invitation
        • Challenge progress notification
    • Managing customers
      • Referrals
      • Customer profile
        • Managing customer emails
        • Program Status
        • Ad-hoc points, redemptions, and adjustments
        • Transfer account data
        • Voiding transactions
        • Perkville email subscription status
        • Reversing a user's Perkville account closure
      • Bulk point updates
        • Add / Redeem page
        • CSV upload
      • Inviting customers
      • Export customer list
    • Settings
      • Advanced
        • Agreements
        • Allowed registration URLs
        • Business dashboard message section
        • Integration platform
        • Join restriction
        • Membership settings
        • Prohibit staff from earning or redeeming points
        • Referral offer claim options
      • Advertising
      • Business info
      • Branding
        • Branding step 1: logo and colors
        • Branding step 2: web pages and emails
        • Setting up a custom branded domain
        • Setting up custom branded emails
      • Challenges
        • Global Challenge Settings
        • Challenge Settings
        • Challenge Progress Activities
        • Challenge Rewards
        • Challenge Invitations
      • Locations
      • Prohibit Customers
      • Staff members
      • Redeeming options
    • Vouchers
    • Reports
      • Customer list export with points
      • Challenge Overview
      • Points By Location
      • Redemption Details
      • Redemption Overview
      • Referral Details
      • Referral Overview
      • Registration Rate Overview
    • Agency
      • Ad terms
      • Suppressions
      • Advertisers
      • Images
      • Creatives
      • Campaigns
      • Obtaining business approval
  • FAQs
    • End customer FAQs
      • I'm unable to join a business' loyalty program. What should I do?
      • Freeing up your Gmail address if you accidentally created a duplicate account
    • Miscellaneous
      • Protecting against password reuse
      • Is it possible to pre-populate the email address field on the page for joining the reward program?
      • I need to change the support email that displays in the footer. How can I do that?
      • I would like to reactivate my business' Perkville account.
      • How do I control my email notifications?
      • How do I update my billing information (e.g. credit card on file)?
    • Onboarding
      • Can Perkville migrate data from other loyalty / rewards software platforms?
      • Is it possible to invite customers with a link in our own emails rather than through Perkville?
      • The reward images that I added look blurry. How can I fix this?
    • Managing emails and names
      • Can you merge two emails into the same account?
      • I would like to correct an email on an account. How do you do that?
      • Can I change which email my customer receives their notifications?
      • Can I remove an email address from a customer's account?
      • Can you change the name of a customer?
      • My customer has two accounts. What should I do?
      • How Do I Change the Email That I Use to Log in to Perkville?
      • My customer does not want to receive emails every time. What should I do?
      • How do I reset my password?
      • Answering "How can I deactivate my Perkville points account?"
    • Points
      • My customer's points are being expired. Why?
      • My customer is missing points. What should I do?
      • How do we add points to a customer or member account?
      • Can you reactivate points that expired?
    • Redemptions
      • A customer accidentally redeemed a reward. What should I do?
    • Referrals
      • Can you reward a customer for referring their friend?
      • Do referral offers expire and if so, is the referral notified?
      • I don't want customers to automatically get referral points. I want to manually complete referrals.
      • Referral submission error for front desk staff
      • How do I check if a referral has been submitted and its status?
Powered by GitBook
LogoLogo
On this page
  • Overview
  • Authentication
  • Resources
  • Querying
  • Responses
  • Performance
  • Integration Platform: Middle

Was this helpful?

  1. Overview
  2. Integrations
  3. Integrating Perkville

API requirements

Learn how to build an API Perkville can connect to

PreviousIntegrating PerkvilleNextAutomating your program using Perkville's API

Last updated 8 months ago

Was this helpful?

Overview

Thank you for your interest in integrating your POS/Membership system with Perkville! This document outlines the general API requirements and data we typically ingest from membership, scheduling, and point-of-sale systems when Perkville is integrating with your API.

If you’re looking to integrate your system with Perkville, we also offer an API that you can use. You can find the documentation for Perkville's API at .

By following these guidelines, you’ll enable Perkville to detect new users in your system and track their activities, allowing for custom behaviors to be triggered based on these events.

For any questions, feel free to reach out to us at ops@perkville.com. We’re here to help!

Authentication

Your API should have an authentication scheme that allows us to store a key to authenticate requests on behalf of a specific business. We recommend using OAuth 2's "Authorization Code" grant type. You can refer to for more details.

If OAuth 2 is too complex, consider starting with a simple shared secret. A business can log into their account, find a secret key, and paste it into our application. We’ll use this key for every query.

Additionally, we require a separate key that uniquely identifies Perkville. If you create a custom authentication solution, ensure this key is included to distinguish our system from others that might integrate with your API.

Resources

A "resource" is a record that businesses care about, such as a "user" or "check-in." Your API should allow us to poll for newly added records and perform actions based on the data received.

User

  • Fields: User ID (Primary Key), Email, First Name, Last Name, Phone Number, Record Last Modified Datetime, (Boolean) Is Child User?, (User ID) Parent ID, and any other personal information.

  • Query by: Batch primary key, Last modified datetime range.

Location (Facility)

  • Fields: Location ID (Primary Key), Location Name, Street Address, City, State, Zip Code, Timezone, Record Last Modified Datetime, and any other useful information.

  • Query by: Complete transfer.

Membership

  • Fields: Membership ID (Primary Key), User ID (Foreign Key to User), Membership Type, Membership Status, Member Join Date, Cancellation Date, Home Location (Foreign Key to Location), Record Last Modified Datetime, and any other useful information.

  • Query by: Batch primary key, Last modified datetime range.

Gym Check-in

  • Fields: Check-in ID (Primary Key), Check-in Datetime, Location ID (Foreign Key to Location), Member ID (Foreign Key to Membership), User ID (Foreign Key to User), Record Last Modified Datetime, and any other useful information.

  • Query by: Last modified datetime range.

Referral

  • Fields: Referral ID (Primary Key), Referrer User ID (Foreign Key to User), Referee User ID (Foreign Key to User), Referral Datetime, Record Last Modified Datetime, and any other useful information.

  • Query by: Last modified datetime range.

Sales

  • Fields: Sale ID (Primary Key), LineItem ID, LineItem Category ID, LineItem Category Name, LineItem Subcategory ID, LineItem Subcategory Name, LineItem Payment Type, Pre-Tax Price, User ID (Foreign Key to User), Member ID (Foreign Key to Membership), Location ID (Foreign Key to Location), Sale Datetime, Record Last Modified Datetime, and any other useful information.

  • Query by: Last modified datetime range.

Sales Category

  • Fields: Category ID, Category Name, Location ID, and any other useful information.

  • Query by: Complete transfer.

Sales Subcategory

  • Fields: Subcategory ID, Subcategory Name, Location ID, and any other useful information.

  • Query by: Complete transfer.

Class

  • Fields: Class ID (Primary Key), Class Name, and any other useful information.

  • Query by: Complete transfer.

Class Attendance

  • Fields: Class Attendance ID (Primary Key), Class ID, User ID (Foreign Key to User), Membership ID (Foreign Key to Membership), Location ID (Foreign Key to Location), Class Name, Class Datetime, Check-in Datetime, Attended/Checked-in Confirmation (if applicable), and any other useful information.

  • Query by: Last modified datetime range.

Appointment

  • Fields: Appointment ID (Primary Key), Appointment Datetime, Check-in Datetime, User ID (Foreign Key to User), Membership ID (Foreign Key to Membership), Attended/Checked-in Confirmation (if applicable), and any other useful information.

  • Query by: Last modified datetime range.

Appointment Category

  • Fields: Appointment ID, Appointment Name, Location ID (Filterable), and any other useful information.

  • Query by: Complete transfer.

Querying

Every API endpoint should require authentication and accept the two keys referenced above. Each endpoint should also support paging, ideally allowing up to 10,000 records per page. We support three types of queries:

  1. Complete transfer: Retrieve all records of a specific type.

  2. Batch primary key lookup: We provide a list of primary keys, and you return all matching records.

  3. Last modified datetime range lookup: We provide a datetime range, and you return all records created or modified within that period.

Querying Guidelines for Different Resources

  • User events (e.g., Check-Ins, Sales): Last modified datetime range query.

  • Other resources (e.g., User, Membership, Location): Support all three query types where applicable.

Responses

  • Responses should be UTF-8 encoded.

  • All datetimes should be in ISO 8601 format with a UTC offset.

Performance

Data related to user interactions (e.g., check-ins or purchases) should be available for consumption immediately upon occurrence.

Integration Platform: Middle

We use our integration platform, , to connect Perkville to various APIs. For more detailed guidelines on building an API for Middle, refer to .

https://www.perkville.com/developers/docs/v2/
this guide
Middle
this guide