Automating your program using Perkville's API

This guide provides key steps and best practices for integrating with Perkville’s API to award points, track membership data, and retrieve user information.

1. Register Your API Client

Before interacting with Perkville’s API, you must register your API client. This registration process will provide you with:

• A client ID and client secret

• Access to generate an API key

Once registered, Perkville will assign the necessary admin-focused scopes to your client.

Please refer to Perkville's API documentation for more information.

2. Authentication

To authenticate, use the Resource Owner Grant flow, which is the simplest method.

How It Works

• Send a POST request with a username and password

• Perkville will return a long-lived API token (does not expire)

Testing Consideration

• Create a token on behalf of a business staff member at your test business.

• This ensures access to test business data and the ability to create transactions.

Please refer to Perkville's API documentation for more information.

3. Awarding Points via the Transaction API

Use Perkville’s Transaction API to grant points for user activity.

Key Parameters

• limit_to_once_per_calendar_day → Ensures a perk is awarded only once per day.

• trans_source_id → Prevents duplicate point awards by assigning a unique ID to each transaction.

  • The trans_source_id must be unique across the entire Perkville business.

  • Construct an ID that uniquely identifies a user, sale, or check-in.

4. Managing Membership Data

To track and update membership data, use the External Member API.

Best Practices

• Provide as many membership details as possible.

• Keep records up to date to ensure users can participate in relevant programs.

• Use POST or PATCH requests to update membership data.

  • POST requests can both create and update records.

5. Retrieving User Information

If you need to surface user data within your system, use the Connection API.

Example Query

To retrieve a user’s point balance and other details by email:

/v2/connections/?business=9823&user__emails__email=[e-mail]

---

Need Help?

For any questions or further assistance, contact [e-mail].

Happy integrating! 🚀