> 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/integrating-your-app-with-perkville/referral-page.md).

# Referral page

Creating a referral page for your mobile app involves using several Perkville API endpoints. Below are the components you'll need to consider when building your referral page.

<figure><img src="https://2181708597-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSiE75SeColbiBVbet0NZ%2Fuploads%2FaYrrIPKk3hvi9ZFIfrul%2FPerkville_referral_page.png?alt=media&#x26;token=bde21c74-2132-4f59-acd1-ffdcc47dd5b0" alt="" width="369"><figcaption></figcaption></figure>

#### Retrieve Referral Offer Details

The details of the referral offer are accessible via the [**Promotion** endpoint](https://www.perkville.com/developers/docs/v2/#v2_resource_21_anchor). This endpoint will provide you with the information about the offers available for sharing, which can be displayed on your referral page.

Promotions are location specific. Filter this endpoint using the customer’s currently selected location with the `location` parameter. For guidance on mapping app locations to Perkville locations and fallback behavior, see the [**Location**](https://docs.perkville.com/integrations/integrating-perkville/integrating-your-app-with-perkville.md#location) section in [Integrating Your App with Perkville](https://docs.perkville.com/integrations/integrating-perkville/integrating-your-app-with-perkville.md).

#### Get the Referral Offer URL

The [**Connection**](https://docs.perkville.com/integrations/integrating-perkville/integrating-your-app-with-perkville.md#connection) provides the `referral_offer_url` that members will share.

#### Submit Referrals on Behalf of Members

If you want to submit referrals on behalf of members, you can do so using the [**Referrals** endpoint](https://www.perkville.com/developers/docs/v2/#v2_resource_22_anchor). At the bottom of the referral page, you can include a form that captures necessary information for submitting a referral.

**Supplying the referral date**

The `referral_date` field is optional when creating a referral. Use it when the referral actually occurred earlier than the API submission time and that original date needs to be preserved.

* Submit the value in **UTC** using `YYYY-MM-DD HH:MM:SS` format. Fractional seconds are also accepted.
* Do not include a timezone offset in the submitted value.
* Dates more than **24 hours in the future** are rejected.
* The date must be on or after the business launch date unless the business allows referrals before launch.
* Referral expiration is calculated from `referral_date`. If the supplied date means the referral has already expired, the referral is created with an expired status.
* If `referral_date` is omitted, Perkville uses the current time.

{% hint style="info" %}
Use `referral_date` for the time the referral occurred, not the time your integration happened to send it to Perkville.
{% endhint %}

See [Referral limits and follow-up](https://docs.perkville.com/features/referrals/configuring-your-referral-program/referral-limits-and-follow-up.md) for the rolling referral-submission limit and guidance on CRM-based prospect follow-up.

#### Error Handling

When creating a referral, handle the following errors and show a customer-safe message. These are the specific validation errors raised by the referral endpoint.

* `pv_api_bad_loc_id`\
  When: The provided location is missing, inactive, or not valid for the business.\
  Customer-safe: “That location isn’t available. Please select a different location.”
* `pv_referral_referer_not_connected`\
  When: The referrer does not have a Connection to the business.\
  Customer-safe: “You need to join the loyalty program before referring someone.”
* `pv_referral_self_referral`\
  When: The referrer and referee are the same person.\
  Customer-safe: “You can’t refer yourself.”
* `pv_referral_max_limit`\
  When: The referrer has reached the rolling 24-hour referral-submission limit.\
  Customer-safe: “You’ve reached the referral limit. Please try again later.”
* `pv_referral_referee_not_eligible`\
  When: The referee already has a Connection to the business.\
  Customer-safe: “That person isn’t eligible for referral.”
* `required` / `invalid` (field-level)\
  When: Required fields are missing or malformed.\
  Customer-safe: “We couldn’t complete your request. Please check your details and try again.”


---

# 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/integrating-your-app-with-perkville/referral-page.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.
