> 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/overview/integrations/integrating-perkville/automating-your-program-using-perkvilles-api.md).

# Automating your program using Perkville's API

## **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**

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](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.

## **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
```

***

## **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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

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

The question should be specific, self-contained, and written in natural language.
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.