> For the complete documentation index, see [llms.txt](https://docs.perkville.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.perkville.com/integrations/integrating-perkville/automating-your-program-using-perkvilles-api.md).

# 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](https://www.perkville.com/developers/registration/). 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](https://www.perkville.com/developers/docs/v2/#v2_client_registration_anchor) for more information.

## **2. Authentication**

Perkville supports the **Resource Owner Grant flow** described in the [API authentication reference](https://www.perkville.com/developers/docs/v2/#v2_authentication_anchor). Before implementing, verify the currently supported grant flow and required scopes for your integration against that reference or with the Perkville API team.

#### **How It Works**

* Send a **POST request** with a **username and password**
* Perkville can return a **long-lived API token**. Treat long-lived tokens as sensitive credentials and do not rely on them expiring automatically.

#### **Keeping API credentials secure**

* Keep client secrets, staff passwords, API keys, and access tokens in secure server-side configuration or a secrets manager. Never put privileged credentials in a public repository, logs, URLs, or a distributed mobile application.
* Use HTTPS for all authenticated requests and limit access to credentials to only the systems and staff that need them.
* Use credentials and permissions appropriate to the integration. Confirm the supported authentication method and scopes in the [official API reference](https://www.perkville.com/developers/docs/v2/#v2_authentication_anchor).
* Use separate test-business credentials and identifiers when testing. Before production launch, verify that requests use the intended business, user, and location rather than test identifiers.
* If a token or secret may have been exposed, contact **<api@perkville.com>** to coordinate revocation or replacement as applicable. Do not assume a long-lived token will expire on its own.

#### **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](https://www.perkville.com/developers/docs/v2/#v2_authentication_anchor) for more information.

## **3. Awarding Points via the Transaction API**

Use Perkville’s [**Transaction API**](https://www.perkville.com/developers/docs/v2/#v2_resource_24_anchor) 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.
* **`voucher_start_as_unused`** → Respects the initial voucher status set for the perk (e.g. UNUSED, PENDING, etc).
  * Only applicable for REDEEM type perks and `ADMIN_CUSTOMER_REDEEM` scopes.

## **4. Managing Membership Data**

To track and update membership data, use the [**External Member API**](https://www.perkville.com/developers/docs/v2/#v2_resource_14_anchor).

#### **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**](https://www.perkville.com/developers/docs/v2/#v2_resource_7_anchor).

#### **Example Query**

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

```
/v2/connections/?business=9823&user__emails__email=example_email@perkville.com
```

***

## Testing an integration without affecting live customers

Before sending test transactions or membership updates, coordinate with [Perkville Support](https://docs.perkville.com/overview/support.md) about using a separate test business and the isolation it provides. Do not assume that a test business is automatically provisioned or that it behaves as a fully isolated sandbox.

1. **Confirm the target business.** Record the Perkville business ID and any external location IDs for the test environment. Double-check that test calls cannot target the production business.
2. **Use test identities and credentials.** Use designated test staff credentials and test member records. Do not use live member email addresses or tokens from production.
3. **Review outbound notifications.** Ask Support which customer emails or other notifications may be triggered during testing and how to avoid sending them to real customers.
4. **Test the complete flow.** Send a distinct test transaction or membership update, verify it on the test customer profile, then check for duplicates and the intended point award or membership state.
5. **Review go-live mappings.** Confirm business and location IDs, credentials, unique transaction identifiers, and any workflow configuration before switching the integration to production.

If you use Middle, coordinate any environment-specific workflow and mapping setup with your integration owner. The Perkville and Middle test configurations may need to be coordinated separately.

## **Need Help?**

For any questions or further assistance, contact **<api@perkville.com>**.

Happy integrating! 🚀


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.perkville.com/integrations/integrating-perkville/automating-your-program-using-perkvilles-api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
