Perkville

Perkville Version 2 API

Jump right into the API documentation. We're always happy to help out with any questions you might have. Drop us a message at api@perkville.com

Client Registration

Before making requests to the Perkville v2 API, clients must first register with Perkville. Once the registration form has been filled out and submitted, we will email the new client id and secret to the contact email that is provided.

New clients will only be allowed to request the PUBLIC scope (see the scopes section below). A Perkville representative will contact the person included in the client registration form to verify the authenticity of the developer and discuss what permissions your application will need from the Perkville API.

Register

Authentication

When using Perkville V2 API, you must authenticate with a bearer token. A bearer token represents a connection between you—the API client—and the end user. When you make an API request with a bearer token, you're essentially performing an action on behalf of a specific user.

You can generate a bearer token by putting a user through the OAuth 2 authorization code grant flow, which is described in detail below.

OAuth2 Authorization

The official OAuth2 specification includes a several different methods of acquiring an access token, but we only support two: The Authorization Code Grant and the Resource Owner Password Credentials Grant.

Authorization Code Grant

Put simply, this flow works as follows: You redirect a user to Perkville. The user gives us permission to let you see and manipulate their data. We redirect back to your application with a short-lived access token. Finally, you make a separate call to Perkville in which you exchange the short-lived token for a long-term bearer token.

Step 1

Redirect the user to our OAuth2 authorization URL with the querystring parameters listed below. Our OAuth2 authorization URL is the following: 

https://www.perkville.com/api/authorize/
key required description
client_id Yes The client id that was emailed to the developer contact upon client registration
redirect_uri No The redirect uri that you would like Perkville to redirect your user to once they have authorized your application to access their data on Perkville. Important: This MUST match one of the redirect uris that was provided upon client registration. If this querystring parameter is omitted, Perkville will default to the first redirect uri it has stored for the provided client id.
response_type Yes This must be "code" for the authorization code flow.
scope No The scopes that you would like to request access to on behalf of the user, separated by spaces. See below for a detailed explanation of the allowed scopes. If not provided, defaults to all of the scopes that your client application is allowed to request.
state No It is recommended that the client application populate this query parameter with a random hash. When Perkville redirects the user back to the client server, this state will be included in the redirect request query string so that the client servers may verify the authenticity of the request.
For example, the URL that you redirect a user to may look like the following: 
https://www.perkville.com/api/authorize/?scope=PUBLIC+USER_CUSTOMER_INFO+USER_REDEEM&state=dsgjndsguh3408fds&redirect_uri=https%3A%2F%2Fwww.example.org%2Foauth_callback%2F&response_type=code&client_id=123myclientid&response_type=code

Step 2

Once the user has been redirected to the Perkville servers, they will be asked to login. Then, the user will be shown a page which summarizes what actions the API client has access to, and asks the user to agree. Upon agreement, our servers generate an authorization code which we will include in a querystring and attach to the redirect uri that was specified in step 1. The user will then be redirected back to this uri, and the client servers may then grab this authorization code and proceed to step 3.

Following from the example request in step 1, The URL that perkville will redirect the user back to may look like the following: 

https://www.example.org/oauth_callback/?code=ylisfw49snfnsdaa&state=dsgjndsguh3408fds

Step 3

Now that your application has an authorization code, you can use it to request an access token. Access tokens can be requested by POSTing to the access token URL listed below with the following POST body. Important: This step must be initiated within 5 minutes after the redirect to your application in step 2 above. Do NOT JSON-encode the POST body. Encode the request body as application/x-www-form-urlencoded, which looks just like a querystring. See the example below. 

https://www.perkville.com/api/token/
key required description
client_id Yes The client id of the consuming application.
client_secret No* The client secret of the consuming application.
* Include the secret here as a GET parameter, or in a Basic Auth header (described below).
code Yes The authorization code that was given to the application in step 2.
grant_type Yes The type of grant that's being requested. This should be "authorization_code".
redirect_uri Yes This is the redirect_uri that was provided in step 1.
state No If a state was provided in step 1, you must provide the state again in this request.
Client secret: Instead of passing in the client_secret as a GET parameter, the request may include it as a Basic Auth header. The username/password for the basic authentication request must be the client id/secret. Following from the above examples, here is what an example request may look like using curl: 
curl https://www.perkville.com/api/token/ -d "code=ylisfw49snfnsdaa&grant_type=authorization_code&redirect_uri=https%3A%2F%2Fwww.example.org%2Foauth_callback%2F&state=dsgjndsguh3408fds&client_id=123myclientid" -u 123myclientid:myclientpassword

If successful, Perkville will respond with an access_token and the scopes that are applicable to the access token. The returned access token should be used to request v2 resources listed below. See "Accessing Endpoints" for more information on how to access resources.

Resource Owner Password Credentials Grant

This is much simpler than the 3-legged Authorization Code grant flow. In this flow, you will simply ask the Perkville user for their username and password. Then, you make ONE request to Perkville's API with the username and password. We will respond with an access token that does not expire, which you will use to make all subsequent API requests. Store the access token. Do not store the user's username or password.

Use Cases

The only acceptable use case is performing administrative tasks (like awarding points) on behalf of a single administrator's account. Developers will be approved to use this grant type on a case by case basis.

All other use cases are inappropriate. An example of an inappropriate use case would be a website which collects a regular user's username and password and then provides the user a custom interface for redeeming points. In this case, instead of using the password grant type, the 3-legged authorization code type should be used.

If you are unsure of which grant type to use, we're here to help. Email us at api@perkville.com.

Appropriate Usage

DO NOT store the username and password.

Examples of inappropriate usage include: Storing the password in source code. Storing the password in any database of any type, anywhere, at any time, except for the few moments needed to create an access token.

Password Grant Flow

After collecting the username and password, make the following request to our API: Do NOT JSON-encode the POST body. Encode the JSON body as application/x-www-form-urlencoded, which looks just like a querystring. See the example below. 

https://www.perkville.com/api/token/
key required description
grant_type Yes The type of grant that's being requested. This should be "password".
username Yes This should be the user's Perkville username.
password Yes This should be the user's Perkville password.
In addition, the request must define the "Authorization" header for basic authentication. The username/password for the basic authentication request must be the client id/secret. Following from the above examples, here is what an example request may look like using curl: 
curl https://www.perkville.com/api/token -d "grant_type=password&username=hello@perkville.com&password=password&client_id=123myclientid" -u 123myclientid:myclientpassword
If successful, Perkville will respond with an access_token and the scopes that are applicable to the access token. The returned access token should be used to request v2 resources listed below. See "Accessing Endpoints" for more information on how to access resources.

Scopes

The scopes listed below can optionally be requested in the authorization code request. When the access token is given back to the client, a list of scopes applicable to the access token is included in the request.

To understand what these scopes mean, one must understand the two types of users within Perkville: There are regular customers and there are business administrators. Regular customers only use Perkville to checkout their point balance, refer their friends, redeem rewards, etc. Business administrators also use Perkville in an administrative capacity -- they need to give points to their users, redeem points on behalf of their customers, etc. Scopes are partitioned along those lines.

name description
PUBLIC Grants read-only access to public information
USER_CUSTOMER_INFO Grants read-only access to user's contact information, business connections, and vouchers. Grants ability to mark a voucher as "Used".
USER_REDEEM Grants ability to redeem a user's earned points
USER_REFERRAL Grants ability to create a referral to a users connected businesses
ADMIN_CUSTOMER_INFO Grants read-only access to a user's customer's contact information and business connections.
ADMIN_CUSTOMER_REDEEM Grants read access to a user's customer's vouchers. Grants ability to mark customer's vouchers as "Used". Grants ability to redeem points on behalf of customers.
ADMIN_CUSTOMER_GRANT_POINTS Grants ability to grant points to a user's customers and invite new customers to Perkville.
ADMIN_CUSTOMER_REFERRAL Grants ability to create a referral on behalf of two users.
ADMIN_PERK Grants ability to create and edit perks within a business' rewards program.
ADMIN_LOCATION Grants ability to create and edit a business's locations.

You should request only those scopes which are absolutely required for your application. For example, if you are writing a point of sale integration, which is mostly concerned about posting transactions on behalf of business administrators, then you should probably request the following scopes: PUBLIC, ADMIN_CUSTOMER_INFO, ADMIN_CUSTOMER_REDEEM, ADMIN_CUSTOMER_GRANT_POINTS, ADMIN_CUSTOMER_REFERRAL, ADMIN_PERK. If you're writing a mobile app which allows users to redeem points and look up their point balance, then you should probably request these scopes: PUBLIC, USER_CUSTOMER_INFO, USER_REDEEM, USER_REFERRAL.

Accessing Endpoints

Once you have a bearer token, you're ready to access an endpoint. Below, you'll find details on each of the endpoints which are included in our API. Click on the "Example" button to see a sample request/response, along with the format of the returned data.

Authorization Header

When making a request, you must include a bearer token in the Authorization header of the HTTP request. For example: 

Authorization: Bearer OjfXMYim1ttM4v7iA0RLhv6OWyss07

Filtering

Primary Key

Many resources can be filtered. For example, the Connection resource can be filtered by "user". That request would look like this: 

GET https://api.perkville.com/v2/connections/?user=1234
This would query for those Connection objects which belong to the user with the ID 1234.

Combining Filters

Filters can be combined. For example, if you want to look up those "Connection" resources which belong to the user above, 1234, who also belong to business 889, the query would look like this: 

GET https://api.perkville.com/v2/connections/?user=1234&business=889

"In" filter

Querying for specific sets of values can be done using an __in filter: 

GET https://api.perkville.com/v2/perks?business=889&classification=REDEEM&type__in=STANDARD,TIME_BONUS,FREQUNCY_BONUS
This would query for all active redeem perks at business 889 with the "type" STANDARD, TIME_BONUS, or FREQUENCY_BONUS

Greater Than/Less Than Filter

Querying for a range of values can be done with __gt, __lt, __gte, or __lte filters. 

GET https://api.perkville.com/v2/transactions/?user=me&biz=889&transaction_dt__gte=2016-11-01%2000%3A00Z&transaction_dt__lte=2016-12-01%2000%3A00Z
The above query would include only those transactions that happened after 2016-11-01 00:00 UTC and before 2016-12-01 00:00 UTC. We strongly suggest adding UTC offset or Z when filtering on dates.

Relational Queries

Certain fields support relational queries: 

GET https://api.perkville.com/v2/transactions/?user=me&biz=889&transaction_dt__gte=2016-11-01&perk__classification=REDEEM
The above query would only return transactions that had perks with the classification "REDEEM". Available to fields with the note "SUPPORTS RELATIONAL QUERIES"

The documentation below specifies what filters are allowed on each resource.

Note that filtering only applies to GET requests.

Pagination

Requests on resources that return multiple items will be paginated to 20 items by default. You can set up a custom page size with the ?limit parameter to return more or less items based on your preferences. To page through to a particular set of records, use the ?offset parameter followed by the number of records you want to skip. An example request might look like this: 

GET https://api.perkville.com/v2/businesses/?offset=10

The pagination parameters can be used together to set a custom page size for your request along with the number of records you would like to skip over. See this example query as a reference: 

GET https://api.perkville.com/v2/businesses/?limit=10&offset=10

Please note that offset=0 returns a set of records that start with the very first record. If you request offset=10 a set of records will be returned that start with the eleventh record and continue in sequence until the number specified in the limit is reached.

Handling Errors

Perkville uses conventional HTTP response codes to indicate if something went wrong with your request.

HTTP Status Code Description
200 Success
201 Success, object created
202 Accepted, object updated
400 Bad Request: The request has a problem that can usually be corrected. Could be a syntax error, validation error, or some other correctable issue.
401 Unauthorized: Something is wrong with your credentials. We don't know who you are.
403 Forbidden: We know who you are, but you're not allowed to do that thing.
500 Server Error: Something went wrong on Perkville's server.
501 Method Not Implemented: You've requested a resource using an HTTP verb that we don't support.

Furthermore, when we return a 4XX-type response, we include additional information in the response body, in the following form. 

{
  'error_type': 'error_type_here',
  'errors': {
    'field_name_here': [
      {
        "code": "erorr_code_here",
        "message": "Long-form, English explanation of what went wrong and how to fix it"
      }
    ]
  }
}

error_type is always one of these values--

error_type Description
oauth_error Something went wrong in the OAuth flow, or related to the OAuth credentials themselves.
authorization_error The request failed because you accessed something that you weren't allowed to access.
invalid_request_error 9 times out of 10, this is a correctable validation error of some kind
unknown_error Something that we haven't accounted for occurred

errors contains one or more JSON objects explaining in detail what went wrong.

The object keys in "errors" tell you the name of the field that had the problem. If the problem was with the entire request, then "__all__" is used in the field name.

Here's a complete example of an error response:

{
  "error_type": "invalid_request_error",
  "errors": {
    "user_email": [
      {
        "code": "invalid",
        "message": "Enter a valid email address.",
      }
    ],
    "__all__": [
      {
        "code": "required",
        "message": "user and user_email were not supplied; Supply exactly one of them."
      }
    ]
  }
}

Business

A "Business" is a Perkville client, and represents a single rewards program for a real world business.

Users can have a Connection to a Business, which represents the customer relationship between the User and the Business, and includes point balance.

Businesses have Locations, which are the physical locations of the Business.

Businesses also have Perks, which are the collection of rules defining how many points a User earns for various activities as well as how many points a User can spend in order to earn a particular reward.

GET

GET /v2/businesses/{BUSINESS_ID}/ Example
Example Request
curl https://api.perkville.com/v2/businesses/4/ -H "Authorization: Bearer accesstoken123abc"
Example Response
{
    "brand_color": null
    "business_id": 4,
    "categories": [
        {
            "category": "Restaurant",
            "category_id": 36,
            "resource_uri": "/v2/categories/36/",
            "subcategory": "Quick serve"
        }
    ],
    "fine_print": "Points not valid for cash back (unless required by law). Must use in one visit.
        Does not cover tax or gratuity. Cannot be combined with other offers.",
    "homepage_url": "http://www.example.com/",
    "locations": [
        "/v2/locations/1/",
        "/v2/locations/2/"
    ],
    "name": "Tacos el Carbon",
    "promotions": [
        "/v2/promotions/3/"
    ],
    "perks": [
        "/v2/perks/5/",
        "/v2/perks/8/",
        "/v2/perks/9/"
    ],
    "perkville_url": "http://www.perkville.com/biz/4/",
    "resource_uri": "/v2/businesses/4/"
}
Restrictions

Required scopes:

  • PUBLIC

Fields
Property Name Type Filterable Description
business_id int ✓ The business ID
categories Category[] An array of Category objects, which indicate what kind of business this is.
fine_print string Business level fine print that contains any restrictions on use of this business' rewards program.
homepage_url string The url of this business' home page
locations Location[] An array of Location resources, which are the physical locations of this business.
name string ✓ Name of the business
logo_url string A link to the logo of this business
brand_color string A Business specified hex color for use with branding elements
promotions Promotion[] An array of Promotion resources, which are the collection of promotional perks a business offers.
perks Perk[] (Depricated) This property is no longer in use and will not include all types of perks. The Perk endpoint is the recommended method to lookup perks at a business.
perkville_url string The canonical URL of the business' home page in in Perkville
resource_uri string The url of this Business record in Perkville's API.

POST

You can't create new instances of this resource

PATCH

You can't update this resource

Business Staff

A perkville user that has been assigned a staff role at a business.

The Business Staff resource is filtered based on the user who owns the token making the request. Only business staff members at businesses the user making the request is a staff member at will be returned.

GET

GET /v2/staff/{STAFF_ID}/ Example
Example Request
curl https://api.perkville.com/v2/staff/1/ -H "Authorization: Bearer accesstoken123abc"
Example Response
{
    "staff_id": "1",
    "business": "/v2/businesses/4/",
    "created": "2015-06-25T19:19:25+00:00",
    "bill_payer": true,
    "resource_uri": "/v2/staff/1/",
    "staff_role": "ADMIN",
    "staff_description": "",
    "user": "/v2/users/263726"
}
Restrictions

Required scopes:

  • USER_CUSTOMER_INFO

Fields
Property Name Type Filterable Description
staff_id string The unique ID number given to the staff record.
business Business ✓ The business to which the staff record belongs.
created datetime The date and time the staff member was created.
bill_payer boolean ✓ Is this staff member the billing responsible user at the associated business.
staff_role string ✓ The role in Perkville the staff member has been assigned. Options are 'ADMIN', 'EMPLOYEE', or 'FRONT_DESK'.
staff_description string In Perkville, a business can add a description for a staff member object. This field is the description a business gave to the staff member.
user User ✓ The URI of the User associated with the staff record. (SUPPORTS RELATIONAL QUERIES)

POST

You can't create new instances of this resource

PATCH

You can't update this resource

Connection

The relationship between a User and a Business is a Connection. Together with User, it represents a customer.

The set of customers for a Business are the Users who have a Connection to that Business.

GET

GET /v2/connections/{CONNECTION_ID}/ Example
Example Request
curl https://api.perkville.com/v2/connections/3/ -H "Authorization: Bearer accesstoken123abc"
Example Response
{
    "business": "/v2/businesses/4/",
    "connection_id": 3,
    "external_cancel_dt": null,
    "external_join_dt": "2015-11-22T17:55:24+00:00",
    "external_membership_status": "ACTIVE",
    "external_membership_type": "Basic",
    "home_location": "/v2/locations/8/",
    "last_mod_dt": "2016-03-02T13:33:11+00:00",
    "last_transaction_dt": "2016-04-06T23:22:58+00:00",
    "last_visited_location": "/v2/locations/8/",
    "level": null,
    "lifetime_earned_points": 300,
    "point_balance": 14,
    "resource_uri": "/v2/connections/3/",
    "referral_offer_url": "https://www.perkville.com/biz/4/referral/261998/",
    "status": "ACTIVE",
    "user": "/v2/users/261998/",
    "vouchers": []
}
Restrictions

Required scopes:

  • PUBLIC
  • At least one of these:
    • ADMIN_CUSTOMER_INFO
    • USER_CUSTOMER_INFO

If USER_CUSTOMER_INFO is present, the only accessible records are those Connections which belong to the User associated with the access token.

If ADMIN_CUSTOMER_INFO is present, the only accessible records are those Connections which belong to the Business which the User associated with the access token is an ADMIN staff member. For example, if the User associated with the access token is an ADMIN staff member at Business 1, this will return all Connection who belong to Business 1.

Fields
Property Name Type Filterable Description
business Business ✓ The business to which this connection is for; i.e., the given user is a customer at this business
connection_id int The primary key of this Connection
external_cancel_dt datetime The date and time a user's membership status converted from "ACTIVE" to "INACTIVE"
external_join_dt datetime The date and time a user's membership became "ACTIVE"
external_membership_status string ✓ Indicates the user's membership status at the business. Values include "ACTIVE", "INACTIVE", or null.
external_membership_type string The user's membership type at the business
home_location Location ✓ The user's home location at the business
last_mod_dt datetime ✓ The date and time that this record was last modified in UTC
last_transaction_dt datetime The date and time of the customer's last transaction in UTC
last_visited_location Location The last location where this customer visited.
level Level The current level of the user. Can be null if the business is not using that feature or if the user has not earned enough points to be in any level.
lifetime_earned_points int The total amount of points the customer has earned at the business through Perkville
point_balance int The current balance of this customer
resource_uri string The url of this Connection record in Perkville's API.
referral_offer_url string The unique referral offer url to the business referred by this customer.
status string ✓ Indicates if the user has accepted the rewards program for this business. Values include "ACTIVE", "INACTIVE", "PENDING", and "IMPORTED".
user User ✓ The user to which this connection belongs. (SUPPORTS RELATIONAL QUERIES)
vouchers Voucher[] The list of vouchers for this business connection

POST

You can't create new instances of this resource

PATCH

PATCH /v2/connections/{CONNECTION_ID}/ Example
Example Request
curl --request PATCH https://api.perkville.com/v2/connections/3/ -H "Authorization: Bearer accesstoken123abc" -H "Content-Type: application/json" -d '{ "status": "ACTIVE" }'
Example Response
{
    "business": "/v2/businesses/4/",
    "connection_id": 3,
    "external_cancel_dt": null,
    "external_join_dt": "2015-11-22T17:55:24+00:00",
    "external_membership_status": "ACTIVE",
    "external_membership_type": "Basic",
    "home_location": "/v2/locations/6/",
    "last_mod_dt": "2017-03-22T23:32:33+00:00",
    "last_transaction_dt": "2016-04-06T23:22:58+00:00",
    "last_visited_location": "/v2/locations/8/",
    "level": null,
    "lifetime_earned_points": 300,
    "point_balance": 14,
    "resource_uri": "/v2/connections/3/",
    "referral_offer_url": "https://www.perkville.com/biz/4/referral/261998/",
    "status": "ACTIVE",
    "user": "/v2/users/261998/",
    "vouchers": []
}
Restrictions

Required scopes:

  • PUBLIC
  • At least one of these:
    • ADMIN_CUSTOMER_INFO
    • USER_CUSTOMER_INFO

If USER_CUSTOMER_INFO is present, you may only PATCH the status field for Connections belonging to the User associated with the access token.

If ADMIN_CUSTOMER_INFO is present, you may only PATCH external_cancel_dt, external_join_dt, external_home_location_id, external_membership_status, external_membership_type, and home_location for Connections belonging to the Business at which the User associated with the access token is an ADMIN staff member.

Parameters
Include only valid JSON in your HTTP body.
Property Name Type Description
external_cancel_dt datetime This field is strongly suggested if setting the user's external_membership_status to INACTIVE. The date and time a user's membership status converted from "ACTIVE" to "INACTIVE". This will be converted to UTC, so we strongly suggest adding UTC offset or Z to the datetime.
external_join_dt datetime This field is strongly suggested if setting the user's external_membership_status to ACTIVE. The date and time a user's membership became "ACTIVE". This will be converted to UTC, so we strongly suggest adding UTC offset or Z to the datetime.
external_membership_status string Indicates the user's membership status at the business. Valid values are "ACTIVE" and "INACTIVE" ONLY.
external_membership_type string This is an OPTIONAL parameter. The user's membership type at the business
external_home_location_id string This is an OPTIONAL parameter. The external_location_id of the user's home Location. Include this or the home_location, but not both.
home_location Location This is an OPTIONAL parameter. The uri of the user's home Location. Include this or the external_home_location_id, but not both.
status string Indicates if the user has accepted the rewards program for this business. Valid values are "ACTIVE" and "INACTIVE" ONLY.
Returns

202 Accepted with a JSON object of the patched Connection.

Email Tracking

Returns a list of emails sent from Perkville businesses associated with the API token used.

This endpoint can be filtered on most fields. The `type` field can be filtered on using the following values:

Emails sent to business customers
  • USER_WARM_REG_REQUEST
    • Sent to a business customer prompting them to join a rewards program after receiving points for the first time.
  • USER_EARN_ALERT
    • Sent to a business customer who is actively connected to a business' rewards program after earning new points.
  • USER_REDEEM_ALERT
    • Sent to a business customer after they redeem for a perk.
  • BONUS_REFERRAL_INFORM
    • Email that is sent when a business customer refers a friend and the business has not set up a referral offer.
  • REFERRAL_OFFER
    • Email that is sent when a business customer refers a friend and the business has an active referral offer.
  • WEEKLY_CUSTOMER_REPORT
    • Sent to a business customer summarizing their transaction activity over the past week.
  • CLAIMED_OFFER
    • Sent to a customer after they claim an offer from a business.
  • VOUCHER_EXPIRES
    • Sent to a business customer alerting them that they have unused vouchers that will expire soon.
  • CUSTOMER_INVITE
    • Sent to users that have been invited to join a business' loyalty program by a staff member.
  • USER_COLD_REG_REQUEST
    • Email contaning a registration link that is sent to users who join Perkville by signing up on our website.
Emails sent to business staff
  • BUSINESS_DAILY_STATS
    • Sent to business staff summarizing the activity at their business over the past day.
  • WEEKLY_BUSINESS_REPORT
    • Email sent to business admins summarizing their business' activity over the past week.
  • MONTHLY_BUSINESS_REPORT
    • Email sent to business admins summarizing their business' activity over the past month.
  • BUSINESS_ADD_EMPLOYEE_INFORM
    • Sent to a user when they are added as a staff member at a business.
  • BUSINESS_LIVE_ALERT
    • Sent to business admins when their business first goes live on Perkville.
  • OBLIGATION
    • Sent to business admins and employees when a customer claims an offer or redeems a perk.
  • NOTIFY_LIMIT_EXCEEDED
    • Sent to a business admin when a batch process fails because it attempted to upload too many records.
  • BATCH_UPLOAD_REPORT
    • Sent to a business admin after a batch process has successfully been completed.
  • COMPLETED_REFERRAL_ADMIN_INFORM
    • Sent to a business admin after a new customer has been successfully referred to their business.
  • BIZ_COUPON_REMINDER
    • For businesses that have uploaded custom coupon codes, this email is sent to staff when a location is running low.
  • MARKETPLACE_ONLY_CONFIRM_EMAIL
    • Sent to an admin of Perkville Marketplace businesses prompting them to confirm their email.
  • MARKETPLACE_ONLY_GET_STARTED
    • Sent to business that join Perkville as a marketplace only business giving them tips on how to get started.
  • INVITE_BATCH_UPLOAD_REPORT
    • Sent to a business admin after they have successfully uploaded a list of user's to be invited to their rewards program.
  • BUSINESS_OVERAGE_WARN
    • Sent to a business admin alerting them that they have exceeded the maximum number of transactions that their plan allows
Emails that may be sent to either staff or customers
  • USER_CONFIRM_EMAIL_REQUEST
    • Sent to users registering via our website or changing their primary email address.
  • USER_MERGE_REQUEST
    • A confirmation email sent as part of the user account merge process.
  • USER_MERGE_OK
    • Sent to a user after they have successfully merged two accounts.
Legacy - These emails are no longer used
  • USER_EARN_WAITING_ALERT
  • BUSINESS_WELCOME
  • GET_STARTED_REPORT
  • REFERRAL_PROMPT
  • API_REGISTRATION_BONUS

GET

GET /v2/email-tracking/{EMAIL_TRACKING_ID}/ Example
Example Request
curl https://api.perkville.com/v2/email-tracking/59/ -H "Authorization: Bearer accesstoken123abc"
Example Response
{
    "business_id": 1832,
    "resource_uri": "/v2/email-tracking/59/",
    "sent_dt": "2016-11-20T17:53:25+00:00",
    "type": "USER_EARN_ALERT",
    "user_email": "edward_test@perkville.com",
    "user_id": 263727
}
Restrictions

Required scopes:

  • ADMIN_CUSTOMER_INFO

Fields
Property Name Type Filterable Description
business_id integer ✓ The primary key of the business associated with this email.
location_id integer The primary key of the location associated with this email. This field can be null if an email is not associated with any location in particular.
resource_uri string The url of this record in Perkville's API.
send_dt datetime ✓ The date and time this email was sent.
type string ✓ The type of email that was sent.
user_email string ✓ The address the email was sent to.
user_id integer ✓ The primary key of the user the email was sent to.

POST

You can't create new instances of this resource

PATCH

You can't update this resource

Frequency Bonus Perk

A Frequency Bonus Perk is awarded when users earn a qualifying perk (defined by `qualifying_perks`) a certain number of times (defined by `required_to_earn`) within a particular period (defined by `frequency`).

GET

GET /v2/frequency-bonus-perk/{FREQUENCY_BONUS_PERK_ID}/ Example
Example Request
curl https://api.perkville.com/v2/frequency-bonus-perk/8/ -H "Authorization: Bearer accesstoken123abc"
Example Response
{
  "business": "/v2/businesses/25/",
  "frequency": "WEEKLY",
  "frequency_bonus_perk_id": 8,
  "qualifying_perks": [
    "/v2/perks/480/"
  ],
  "required_to_earn": 3,
  "resource_uri": "/v2/frequency-bonus-perk/8/",
  "reward": "/v2/perks/742/"
}
Restrictions

Required scopes:

  • PUBLIC

Fields
Property Name Type Filterable Description
frequency_bonus_perk_id integer ✓ The ID of this record
business Business ✓ The business that this bonus belongs to.
qualifying_perks Perk[] ✓ The list of perks which count towards this frequency bonus
reward Perk ✓ The reward given to the user after earning the requisite number of qualifying perks
required_to_earn integer ✓ The number of times that a user must earn one of the qualifying perks before receiving the reward
frequency string Options are WEEKLY, MONTHLY, or FROM_DATE, indicates the time window during which users can accumulate the requisite number of earning events

POST

You can't create new instances of this resource

PATCH

You can't update this resource

Frequency Bonus Progress

Returns a list of users and their progress towards each frequency bonus perk. Important notes:

  • Records will be present ONLY when a user has earned at least ONCE in the current time period. e.g., if a business has just one frequency bonus perk set up, for "3 Check-Ins per week", and user 1451243 has NOT earned any Check-Ins this week, then the query "GET /v2/frequency-bonus-progress/?user=1451243" would return NO records
  • When making a request with the ADMIN_CUSTOMER_INFO scope, ensure that your user is a staff member with access to ALL locations at the business. We deliberate exclude records for staff members who are NOT authorized for all locations at a business.

GET

GET /v2/frequency-bonus-progress/{FREQUENCY_BONUS_PROGRESS_ID}/ Example
Example Request
curl https://api.perkville.com/v2/frequency-bonus-progress/19/ -H "Authorization: Bearer accesstoken123abc"
Example Response
{
  "business": "/v2/businesses/25/",
  "frequency_bonus_perk": "/v2/frequency-bonus-perk/8/",
  "frequency_bonus_progress_id": 19,
  "has_earned_bonus": false,
  "progress_count": 1,
  "resource_uri": "/v2/frequency-bonus-progress/19/",
  "user": "/v2/users/263726/"
}
Restrictions

Required scopes:

  • PUBLIC
  • At least one of these:
    • ADMIN_CUSTOMER_INFO
    • USER_CUSTOMER_INFO

Fields
Property Name Type Filterable Description
frequency_bonus_progress_id integer ✓ The ID of this record
business Business ✓ The business that this promotion belongs to.
user User ✓ The user which has had some progress towards this frequency bonus perk. (SUPPORTS RELATIONAL QUERIES)
frequency_bonus_perk FrequencyBonusPerk ✓ The perk which the user is progressing towards completing
progress_count integer The number of times the user has earned the requisite perks
has_earned_bonus boolean Indicates if the user has earned this bonus

POST

You can't create new instances of this resource

PATCH

You can't update this resource

Level

Businesses can incorporate the idea of levels into their loyalty program. Once the Levels features has been activated, Perks can be restricted so that only users who have obtained a specified level can redeem them. Users can reach different levels by earning the amount of points set as the level's point_floor.

GET

GET /v2/levels/{level_id}/ Example
Example Request
curl https://api.perkville.com/v2/levels/2/ -H "Authorization: Bearer accesstoken123abc"
Example Response
{
    "badge_url": "https://example.perkville.com/images/1832/levels/2/badge/20170331164340.png",
    "business": "/v2/businesses/1832/",
    "level_id": 2,
    "name": "Silver",
    "point_floor": 750,
    "resource_uri": "/v2/levels/2/"
}
Restrictions

Required scopes:

  • PUBLIC

Fields
Property Name Type Filterable Description
level_id integer ✓ The Level ID
business Business ✓ The Business associated with this level
name string The name of the level
point_floor integer The amount of points a customer must earn to reach this level
badge_url string URL of the badge image associated with this level

POST

You can't create new instances of this resource

PATCH

You can't update this resource

Location

A Location is a physical place at which a Business resides.

GET

GET /v2/locations/{LOCATION_ID}/ Example
Example Request
curl https://api.perkville.com/v2/locations/1/ -H "Authorization: Bearer accesstoken123abc"
Example Response
{
    "address_1": "123 Main St.",
    "address_2": "",
    "business": "/v2/businesses/4/",
    "city": "San Francisco",
    "country_code": "us",
    "external_location_id": "AD123F",
    "latitude": "37.7833",
    "location_id": 1,
    "longitude": "122.4167",
    "name": "SF Shoppe",
    "postal_code": "94102",
    "resource_uri": "/v2/locations/1/",
    "state": "CA"
}
Restrictions

Required scopes:

  • PUBLIC

Fields
Property Name Type Filterable Description
address_1 string First line of this Location's physical address
address_2 string Second line of this Location's physical address
business Business ✓ The Business to which this Location belongs
city string The city where this Location resides
country_code string ✓ The country code (e.g., "us" for the USA)
external_location_id string ✓ The external location ID, often used to associate a location with an ID in another system.
latitude string The exact latitude of this location's physical address.
location_id int ✓ The Perkville ID of this location
longitude string The exact longitude of this location's physical address
name string The title of this location
postal_code string ✓ The ZIP/postal code of this location
state string The state code of this location (e.g., CA for California; Often this field used for provinces and similiar political entities.)

POST

POST /v2/locations/ Example
Example Request
curl https://api.perkville.com/v2/locations/ -H "Authorization: Bearer accesstoken123abc" -H "Content-Type: application/json" -d '{ "address_1": "123 Main St.", "address_2": "", "business": "/v2/businesses/4/", "city": "Perkville", "country_code": "us", "external_location_id": "AD123F", "name": "POST Location", "postal_code": "94102", "state": "CA"}'
Example Response
201 Created
{
    "address_1": "123 Main St.",
    "address_2": "",
    "business": "/v2/businesses/4/",
    "city": "Perkville",
    "country_code": "us",
    "external_location_id": "AD123F",
    "latitude": "37.7833",
    "location_id": 1,
    "longitude": "122.4167",
    "name": "POST Location",
    "postal_code": "94102",
    "resource_uri": "/v2/locations/1/",
    "state": "CA"
}
Restrictions

Required scopes:

  • ADMIN_LOCATION

Parameters
Include only valid JSON in your HTTP body.
Property Name Type Description
address_1 string First line of this Location's physical address
address_2 string Second line of this Location's physical address
business Business The Business to which this Location belongs
city string The city where this Location resides
country_code string The country code (e.g., "us" for the USA)
external_location_id string An unique external location ID, often used to associate a location with an ID in another system.
name string The title of this location
postal_code string The ZIP/postal code of this location
state string The state code of this location (e.g., CA for California; Often this field used for provinces and similiar political entities.)
Returns

A 201 Created response with the newly created Location, as JSON

PATCH

PATCH /v2/locations/{LOCATION_ID}/ Example
Example Request
curl --request PATCH https://api.perkville.com/v2/locations/1/ -H "Authorization: Bearer accesstoken123abc" -H "Content-Type: application/json" -d '{ "name": "A new location name"}'
Example Response
202 Accepted
{
    "address_1": "123 Main St.",
    "address_2": "",
    "business": "/v2/businesses/4/",
    "city": "Perkville",
    "country_code": "us",
    "external_location_id": "AD123F",
    "latitude": "37.7833",
    "location_id": 1,
    "longitude": "122.4167",
    "name": "A new location name",
    "postal_code": "94102",
    "resource_uri": "/v2/locations/1/",
    "state": "CA"
}
Restrictions

Required scopes:

  • ADMIN_LOCATION

Parameters
Include only valid JSON in your HTTP body.
Property Name Type Description
address_1 string First line of this Location's physical address
address_2 string Second line of this Location's physical address
business Business The Business to which this Location belongs
city string The city where this Location resides
country_code string The country code (e.g., "us" for the USA)
external_location_id string An unique external location ID, often used to associate a location with an ID in another system.
name string The title of this location
postal_code string The ZIP/postal code of this location
state string The state code of this location (e.g., CA for California; Often this field used for provinces and similiar political entities.)
Returns

202 Accepted response with the updated Location, as JSON

Marketplace Reward

A Marketplace Reward is a type of Perk that businesses can create to be offered for use at other Perkville businesses.

Through the Perkville Marketplace, when a business creates a loyalty program they can choose to accept these offers as part of their own program, assigning them a logical point value based on the estimated monetary value of the marketplace offer.

Objects returned from this resource endpoint represent a Perk being offered on the marketplace and a business that has accepted it into their own loyalty program.

GET

GET /v2/marketplace-rewards/{MARKETPLACE_REWARD_ID}/ Example
Example Request
curl https://api.perkville.com/v2/marketplace-rewards/5/ -H "Authorization: Bearer accesstoken123abc"
Example Response
{
    "business": "/v2/businesses/1832/",
    "marketplace_reward_id": 5,
    "perk": "/v2/perks/33168/",
    "points": 100,
    "resource_uri": "/v2/marketplace-rewards/5/"
}
Restrictions

Required scopes:

  • Public

Fields
Property Name Type Filterable Description
marketplace_reward_id int ✓ The Perkville ID of this Marketplace Reward
business Business ✓ The business that has accepted the marketplace reward into their loyalty program.
perk Perk The Perk record offered to the Marketplace
points int The point value assinged to the reward by the business accepting it from the marketplace

POST

You can't create new instances of this resource

PATCH

You can't update this resource

Perk

A Perk is a rewards rule for a Business, and are organized into two classifications: redemption or earning.

An earning Perk is a rule for how many points a customer earns for doing a particular thing, such as attending a one-on-one workout session, or spending $1.

A redeeming Perk is a rule for how many points a customer must spend to earn a reward. For example, spend 100 points and get a free $10 off coupon.

GET

GET /v2/perks/{PERK_ID}/ Example
Example Request
curl https://api.perkville.com/v2/perks/5/ -H "Authorization: Bearer accesstoken123abc"
Example Response
{
    "admin_flagged_as_invisible_to_customers": false,
    "business": "/v2/businesses/4/",
    "classification": "REDEEM",
    "description": "We love our customers! Bring in this voucher for $10 off any purchase!",
    "end_date": null,
    "eligible_at_all_locations": true,
    "external_coupon_code": null,
    "external_reward_url": null,
    "fine_print": null,
    "must_redeem_at_home_location": false,
    "perk_id": 5,
    "picture_card": null,
    "points": 100,
    "redemption_limit_count": null,
    "redemption_limit_interval": null,
    "redemption_limit_interval_count": null,
    "resource_uri": "/v2/perks/5/",
    "required_level": null,
    "start_date": null,
    "title": "$10 Off Any Purchase",
    "type": "STANDARD"
}
Restrictions

Required scopes:

  • PUBLIC

Fields
Property Name Type Filterable Description
business Business ✓ The business ID
perk_id int The perk ID
status string Either 'ACTIVE' or 'INACTIVE'. If INACTIVE, the perk will no longer be eligible for earning or redeeming.
classification string ✓ Either "EARN" or "REDEEM", indicating if this rule is for receiving points or for spending them.
description string The long form user-facing description of this rule. Usually this is used to give detailed information about the Perk.
eligible_at_all_locations boolean Indicates if this rule applies to all locations. Note that right now, only REDEEM perks or EARN perks with a type of TIME_BONUS, FREQUENCY_BONUS, or DATE_RANGE_BONUS can specify eligible locations.
eligible_locations Location[] These are the locations at which this Perk is eligible. Note that if eligible_at_all_locations is True, then eligible_locations won't be included.
admin_flagged_as_invisible_to_customers boolean ✓ Indicates if this perk is shown on the public facing rewards program. Transactions can still be created for these perks. Defaults to false.
points int The number of points that this rule is worth
title string The short title of this Perk
type string This is a special field which indicates how the Perk is used. Options include 'STANDARD', 'POINT_ADJUSTMENT', 'BIRTHDAY', 'CHECKIN', 'COUPON', 'REFERRAL', 'REGISTRATION', 'TWITTER_POST', 'VISITOR', 'TIME_BONUS', 'FREQUENCY_BONUS', 'MARKETPLACE_OFFER', 'DATE_RANGE_BONUS', 'EXTERNAL_REWARD'.
external_coupon_code string The business' internal identifier for this perk. Businesses typically use it instead of the voucher code when representing perkville vouchers in third party systems.
completes_referral boolean When this field is true, when a customer earns this perk, if that customer has an open referral where he or she is the one who was referred, that referral should be completed. This field may only be True for standard EARN type perks.
must_redeem_at_home_location boolean For businesses that sync membership information, this is an option that can be configured when creating a perk that requires users to redeem at their home location.
redemption_limit_interval string One of the following - 'NO_REDEMPTION_LIMIT', 'DAY', 'MONTH', 'YEAR', 'ALL_TIME'. Together with redemption_limit_interval_count and redemption_limit_count, this indicates how many times this perk can be redeemed within the interval.
redemption_limit_count int Populated if redemption_limit_interval is anything other than 'NO_REDEMPTION_LIMIT', and indicates how many times the perk can be redeemed in the given span of time. If the rule is that this can be redeemed "2 times in 10 Days", 2 is the redemption_limit_count.
redemption_limit_interval_count int Populated if redemption_limit_interval is 'DAY', 'MONTH' or 'YEAR', and indicates the span of time with which the redemption limit applies. If the rule is that this can be redeemed "2 times in 10 Days", 10 is the redemption_limit_interval_count.
required_level Level Indicates the minimum level, based on point_floor, that a user must unlock before they can redeem this perk. Use the Connection endpoint to determine a user's level at a business.
start_date date Populated if the perk's available start date has been set.
end_date date Populated if the perk's available end date has been set.
picture_card string If this perk has a photo, the URL of the photo is available in this attribute.
fine_print string Any specific rules that applies to the perk
external_reward_url string A URL to a third party reward provider

POST

POST /v2/perks/ Example
Example Request
curl https://api.perkville.com/v2/perks/ -H "Authorization: Bearer ryYMKAkopdwNb82FJTmxJ31L7T6K8z" -H "Content-Type: application/json" -d '{ "business": "/v2/businesses/4/", "classification": "REDEEM", "description": "Get 20% off any item in our gift shop!", "eligible_locations": [ "/v2/locations/35/" ], "points": 100, "title": "20% Off Coupon" }'
Example Response
201 Created
{
    "admin_flagged_as_invisible_to_customers": false,
    "business": "/v2/businesses/4/",
    "classification": "REDEEM",
    "description": "Get 20% off any item in our gift shop!",
    "eligible_at_all_locations": false,
    "eligible_locations": [
        "/v2/locations/35/"
    ],
    "external_coupon_code": null,
    "fine_print": "Only valid for non-discounted items",
    "perk_id": 6,
    "points": 100,
    "resource_uri": "/v2/perks/6/",
    "title": "20% Off Coupon",
    "type": "STANDARD",
    "picture_card": null
}
Restrictions

Required scopes:

  • ADMIN_PERK

Parameters
Include only valid JSON in your HTTP body.
Property Name Type Description
business Business The business ID the perk belongs to.
status string Either 'ACTIVE' or 'INACTIVE'. If INACTIVE, the perk will no longer be eligible for earning or redeeming.
classification string The type of perk to be created. This can either be 'EARN' or 'REDEEM'. An 'EARN' perk is an earning rule that you can set up to give points to a business' customers. A 'REDEEM' perk is a redemption rule that describes what a customer can get and how many points they need to spend to get it.
description string A detailed description of the Perk being offered.
eligible_at_all_locations boolean If True, this perk is available at all of the business locations. Else, it's only available at the locations specified in the eligible_locations field.
eligible_locations Location[] If eligible_at_all_locations is False, this field describes which locations the perk is associated with.
external_coupon_code string The business' internal identifier for this perk. Businesses typically use it instead of the voucher code when representing perkville vouchers in third party systems.
points int The point amount that can be earned for achieving this perk, or subtracted from the user's account for redeeming this perk.
title string The name of the perk being offered.
completes_referral boolean When this field is true, when a customer earns this perk, if that customer has an open referral where he or she is the one who was referred, that referral should be completed. This field may only be True for standard EARN type perks. This optional field defaults to True for EARN type perks, and is always False for REDEEM type perks.
fine_print string Any specific rules that applies to the perk
admin_flagged_as_invisible_to_customers boolean This is an OPTIONAL parameter. Indicates if this perk is shown on the public facing rewards program. Transactions can still be created for these perks. Defaults to false.
Returns

201 Created response, with the newly-created Perk in the response body, as JSON

PATCH

PATCH /v2/perks/{PERK_ID}/ Example
Example Request
curl --request PATCH https://api.perkville.com/v2/perks/5/ -H "Authorization: Bearer ryYMKAkopdwNb82FJTmxJ31L7T6K8z" -H "Content-Type: application/json" -d '{ "title": "$20 Off Any Purchase", "points": 150 }'
Example Response
{
    "admin_flagged_as_invisible_to_customers": false,
    "business": "/v2/businesses/4/",
    "classification": "REDEEM",
    "description": "We love our customers! Bring in this voucher for $10 off any purchase!",
    "eligible_at_all_locations": true,
    "external_coupon_code": null,
    "perk_id": 5,
    "points": 100,
    "resource_uri": "/v2/perks/5/",
    "title": "$10 Off Any Purchase",
    "type": "STANDARD",
    "picture_card": null
}
Restrictions

Required scopes:

  • ADMIN_PERK

Parameters
Include only valid JSON in your HTTP body.
Property Name Type Description
status string Either 'ACTIVE' or 'INACTIVE'. If INACTIVE, the perk will no longer be eligible for earning or redeeming.
title string The name of the perk being offered.
description string A detailed description of the Perk being offered.
points int The point amount that can be earned for achieving this perk, or subtracted from the user's account for redeeming this perk.
eligible_at_all_locations boolean If True, this perk is available at all of the business locations. Else, it's only available at the locations specified in the eligible_locations field.
eligible_locations Location[] array If eligible_at_all_locations is False, this field describes which locations the perk is associated with.
external_coupon_code string The business' internal identifier for this perk. Businesses typically use it instead of the voucher code when representing perkville vouchers in third party systems.
completes_referral boolean When this field is true, when a customer earns this perk, if that customer has an open referral where he or she is the one who was referred, that referral should be completed. This field may only be True for standard EARN type perks.
fine_print string Any specific rules that applies to the perk
admin_flagged_as_invisible_to_customers boolean This is an OPTIONAL parameter. Indicates if this perk is shown on the public facing rewards program. Transactions can still be created for these perks. Defaults to false.
Returns

202 Accepted with a JSON object of the patched Perk

Promotion

A Promotion is a special perk created by a business. Currently, this includes just a Referral Promotion.

GET

GET /v2/promotions/{PROMOTION_ID}/ Example
Example Request
curl https://api.perkville.com/v2/promotions/8/ -H "Authorization: Bearer accesstoken123abc"
Example Response
{
    "business": "/v2/businesses/93/",
    "detail": "Enjoy a free cup of coffee on us!",
    "fine_print": "Only valid for first time customers.",
    "picture_uri": "https://www.perkville.com/images/deals/1234/123_500x500.jpg",
    "perk": "/v2/perks/1234",
    "title": "Free 12oz coffee",
    "type": "REFERRAL"
}
Restrictions

Required scopes:

  • PUBLIC

Fields
Property Name Type Filterable Description
business Business ✓ The business ID the promotion belongs to.
detail string The description of the promotion
fine_print string The detailed information and restriction of the promotion
perk Perk The Perk resource of this promotion
picture_uri string The url of the picture associated with the promotion
title string The name of the promotion
type string ✓ The field that indicates the type of promotion. Options include 'REFERRAL'

POST

You can't create new instances of this resource

PATCH

You can't update this resource

Referral

Get or create a referral between two users at a specified business.

GET

GET /v2/referrals/{REFERRAL_ID}/ Example
Example Request
curl https://api.perkville.com/v2/referrals/5/ -H "Authorization: Bearer ryYMKAkopdwNb82FJTmxJ31L7T6K8z"
Example Response
{
  "business": "/v2/businesses/5/",
  "completed_dt": "2016-03-31T20:46:14+00:00",
  "created_dt": "2016-03-31T20:16:40+00:00",
  "location": "/v2/locations/3/",
  "referral_content": "",
  "referral_date": "2016-03-31T20:16:40+00:00",
  "referral_from_user": "/v2/users/2/",
  "referral_source": "DIRECT_LINK",
  "referral_status": "COMPLETED",
  "referral_to_user": "/v2/users/5/",
  "referrer_conn_status": "ACTIVE",
  "resource_uri": "/v2/referrals/1/",
  "voucher_id": "/v2/vouchers/6/"
}
Restrictions

Required scopes:

  • PUBLIC
  • At least one of these:
    • ADMIN_CUSTOMER_REFERRAL
    • USER_REFERRAL

If ADMIN_CUSTOMER_REFERRAL is present, referrals will be returned at businesses and locations that user is authorized to accesss.

If USER_REFERRAL is present, referrals will be returned at businesses and locations that involve that user as the referrer or referee.

Fields
Property Name Type Filterable Description
business Business ✓ The uri of the Business of this referral.
completed_dt datetime ✓ The day and time the referral was marked as complete. This field is left blank if the referral status is not 'COMPLETED'.
created_dt datetime ✓ The day and time the referral was created in Perkville.
location Location ✓ The uri of the Location of this referral.
referral_content string The message that was sent by the referrer to the referree.
referral_date datetime The day and time the referral was sent by the referrer to the referree.
referral_from_user User ✓ The uri of the User who is the referrer. (SUPPORTS RELATIONAL QUERIES)
referral_source string The part of Perkville's system where the referral came from. Options are 'WARM_REG' (Warm registration), 'LOGGED_IN' (Customer logged in), 'POS_SYNC' (Point-of-sale system sync), 'STAFF_SUBMIT' (Business staff submitted), 'API_SUBMITTED' (Submitted through API), 'FORWARDED' (Forwarded by original referred user'), 'TWITTER' (Distributed through Twitter), 'FACEBOOK' (Distributed through Facebook), 'DIRECT_LINK' (Linked directly using the "copy and paste" interface), 'MAILTO_EMAIL' (Mailed to using the mailto share button), 'PERKVILLE_EMAIL' (Sent through the "enter emails" interface), or blank if the referral source is unknown.
referral_status string ✓ Current status of the referral. Options are 'SENT' (the referral has been sent by the referrer, but not completed by the referree), 'COMPLETED' (the referree has earned points at the business and successfully completed the referral), and 'VOID' (the referral has been voided).
referrer_conn_status string The business connection status of the referrer at the time the referral was sent. Options are 'ACTIVE', 'INACTIVE', 'PENDING', 'IMPORTED', 'NOCONN', or blank if the business connection status is unknown.
referral_to_user User ✓ The uri of the User who is the referree. (SUPPORTS RELATIONAL QUERIES)
resource_uri string The uri of this Referral record in Perkville's API.
voucher Voucher The uri of the Voucher that was created from this referral. Please note this field will be null unless the referral offer has already been claimed by the referree.

POST

POST /v2/referrals/ Example
Example Request
curl https://api.perkville.com/v2/referrals/ -H "Authorization: Bearer ryYMKAkopdwNb82FJTmxJ31L7T6K8z" -d '{"business": "/v2/businesses/1/", "location": "/v2/locations/2/", "referral_from_user": "/v2/users/261998/", "referral_to_email": "edward_test@perkville.com"}'
Example Response
{
  "business": "/v2/businesses/1/",
  "completed_dt": null,
  "created_dt": "2015-05-12-T18:39:07+00:00",
  "distribution_type": "EMAIL",
  "location": "/v2/locations/2/",
  "referral_content": "",
  "referral_from_user": "/v2/users/261998/",
  "referral_source": "API_SUBMITTED",
  "referral_status": "SENT",
  "referral_to_email": "edward_test@perkville.com",
  "referree_external_id": "",
  "referree_external_id_type: "",
  "referrer_conn_status": "ACTIVE",
  "resource_uri": "/v2/referrals/1/",
  "voucher": null
}
Restrictions

Required scopes:

  • PUBLIC
  • At least one of these:
    • ADMIN_CUSTOMER_INFO
    • USER_CUSTOMER_INFO
  • At least one of these:
    • ADMIN_CUSTOMER_REFERRAL
    • USER_REFERRAL

If ADMIN_CUSTOMER_REFERRAL is present, you may create referrals on behalf of customers who belong to the Business for which this user is a staff member. If both the referral_from_user and the referral_to_email are already connected to the specified business and submit_as_referrer is set to false (default), the referral will be created with a referral_status of COMPLETED. If the referral_to_email is not connected to the specified business the referral will be created with a status of SENT.

If USER_REFERRAL is present, you may create referrals only for the user associated with the bearer token. This will create a referral from the user to the email address specified, and will have a referral_status of SENT. If the referral_to_email is already a customer of the specified business the referral will be rejected.

Parameters
Include only valid JSON in your HTTP body.
Property Name Type Description
business Business The uri of the Business of this referral.
location Location The uri of the Location of this referral. This is an OPTIONAL parameter.
referral_from_user User The uri of the User who is sending the referral. If USER_REFERRAL scope is present, this field will always be equal to the user making the referral request.
referral_to_email string The email address of the person being referred to the specified business.
referral_content string A personalized note to be sent along with the referral. This is an OPTIONAL parameter.
send_referral_email boolean Determines whether to send a referral email to the user being referred. An input of true will send an email and an input of false will not send an email. This is an OPTIONAL parameter and if excluded will automatically default to true.
submit_as_referrer boolean Only applicable to ADMIN_CUSTOMER_REFERRAL scopes. When set to true, if the referral_to_email has an existing connection with the business, the referral will be rejected. When set to false, the referral will be created regardless of the referral_to_email's connection with the business. This is an OPTIONAL parameter, and if excluded will automatically default to false.
Returns

A 201 response with a JSON object of the created Referral if successful.

PATCH

You can't update this resource

Scope

Scopes are different levels of authorization that control what a bearer token can and can't access. Calling this endpoint will return a list of all scopes for the bearer token making the request.

GET

GET /v2/scopes/ Example
Example Request
curl https://api.perkville.com/v2/scopes/ -H "Authorization: Bearer accesstoken123abc"
Example Response
{
    "scope": "PUBLIC"
},
{
    "scope": "USER_CUSTOMER_INFO"
},
{
    "scope": "USER_REDEEM"
},
{
    "scope": "ADMIN_CUSTOMER_INFO"
},
{
    "scope": "ADMIN_CUSTOMER_REDEEM"
},
{
    "scope": "ADMIN_CUSTOMER_GRANT_POINTS"
},
{
    "scope": "ADMIN_PERK"
}
Restrictions

None

Fields
Property Name Type Filterable Description
scope string The name of the scope.

POST

You can't create new instances of this resource

PATCH

You can't update this resource

Transaction

A Transaction is a single event where a user earns or spends points. An example of a Transaction would be "Bob checked in at Yoga Studio Extreme on March 5th 2015 and earned 15 points."

You can create a transaction in one of two ways: First, if you know the the user ID, you can pass in just the user URI along with the Business, Location and Perk URIs, plus the quantity.

However, if you don't know the user ID, you can pass the user's email address, first name and last name, along with the Business, Location, and Perk URIs, plus the quantity. If that user exists, we'll simply add that Transaction for that user. If the user doesn't exist, we'll create a new user, award the Transaction, and then send the user an invitational email.

In addition, you can retrieve a specific transaction or a list of transactions.

NOTE: If you are requesting a list of transactions using the ADMIN_CUSTOMER_INFO scope, we require you to append a user filter, e.g. ?user={{USER_ID}} or a filter related to the user model, e.g. ?user__emails__email="{{USER_EMAIL}}". For more information on related fields, please see the documentation for the user resource. If you are using the USER_CUSTOMER_INFO scope a user filter is not required since those requests will already be filtered by records belonging to the user making the request.

GET

GET /v2/transactions/{TRANSACTION_ID}/ Example
Example Request
curl https://api.perkville.com/v2/transactions/232442/ -H "Authorization: Bearer accesstoken123abc"" -H "Content-Type: application/json"
Example Response
{
    'business': '/v2/businesses/25/',
    'location': '/v2/locations/2/',
    'perk': '/v2/perks/397/',
    'title': 'Free Hoodie',
    'points': 300,
    'quantity': 1,
    'resource_uri': '/v2/transactions/232442/',
    'trans_source_id': '',
    'transaction_dt': '2015-01-30T23:54:04.147208+00:00',
    'transaction_id': 3144,
    'user': '/v2/users/263727/',
    'voucher': '/v2/vouchers/552044/'
}
Restrictions

Required scopes:

  • PUBLIC
  • At least one of these:
    • ADMIN_CUSTOMER_INFO
    • USER_CUSTOMER_INFO

If ADMIN_CUSTOMER_INFO is present, you can retrieve transaction records from businesses and locations that the user making the request is an administrator of.

If USER_CUSTOMER_INFO is present, you can retrieve transaction records for the user making the request.

Fields
Property Name Type Filterable Description
business Business ✓ The uri of the Business of this transaction
location Location ✓ The uri of the Location of this transaction. Include this OR the "external_location_id" parameter, but not both.
perk Perk The uri of the Perk of this transaction. (SUPPORTS RELATIONAL QUERIES)
title string The user-readable description of what this transaction was actually for. e.g., "Checkin" or "Free Hoodie"
classification string The classification of the perk tied to this transaction. Either "EARN" or "REDEEM", indicating if this rule is for receiving points or for spending.
points int The points that were either spent (REDEEM type perk) or earned (EARN type perk) with this transaction.
quantity int The quantity of the transaction -- usually this is used with the EARN transaction event for a dollar spent rule.
trans_source_id string This field may be present if the transaction was created via an API. It is used to ensure that the transaction is unique at this business.
transaction_dt datetime ✓ The date and time the transaction was created.
transaction_id int The ID number for the transaction.
transaction_status string ✓ The current status of the Transaction. The options are ACTIVE, VOID, VOID_REF. When a transaction is voided two the things happen. The transaction gets updated with a status of VOID, and a new transaction, for the negative amount of the original transaction, is created with the status VOID_REF. The transaction_reference field described below will also be used in order for the original transaction to reference the transaction that voided it and vice versa.
transaction_reference Transaction Certain types of transactions may be created in reference to another transaction. In those cases this field is used.
user User ✓ The uri of the User associated with the transaction. (SUPPORTS RELATIONAL QUERIES)
voucher Voucher The uri of the Voucher used in the transaction.

POST

POST /v2/transactions/ Example
Example Request
curl https://api.perkville.com/v2/transactions/ -H "Authorization: Bearer ryYMKAkopdwNb82FJTmxJ31L7T6K8z" -H "Content-Type: application/json" -d '{ "business": "/v2/businesses/1/", "location": "/v2/locations/2/", "perk": "/v2/perks/397/", "quantity": "1", "user_email": "edward_test@perkville.com", "first_name": "Edward", "last_name": "McFudge" }'
Example Response
{
    'business': '/v2/businesses/25/',
    'location': '/v2/locations/2/',
    'perk': '/v2/perks/397/',
    'points': 300,
    'quantity': 1,
    'resource_uri': '/v2/transactions/232442/',
    'trans_source_id': '',
    'transaction_dt': '2015-01-30T23:54:04.147208+00:00',
    'transaction_id': 3144,
    'user': '/v2/users/263727/',
    'voucher': '/v2/vouchers/552044/'
}
Restrictions

Required scopes:

  • PUBLIC
  • At least one of these:
    • ADMIN_CUSTOMER_GRANT_POINTS
    • ADMIN_CUSTOMER_REDEEM
    • USER_REDEEM
  • At least one of these:
    • ADMIN_CUSTOMER_INFO
    • USER_CUSTOMER_INFO

If ADMIN_CUSTOMER_GRANT_POINTS is present, you may create EARN transactions for any customers who belong to the Business for which this user is a staff member.

If USER_REDEEM is present, you may create a REDEEM transaction for only the user associated with the bearer token. This will create an UNUSED Voucher, unless voucher_start_as_used is set to True.

If ADMIN_CUSTOMER_REDEEM is present, you may create REDEEM transactions for any customers who belong to the Business for which this user is a staff member. This will create a USED voucher, unless voucher_start_as_unused is set to True.

Parameters
Include only valid JSON in your HTTP body.
Property Name Type Description
business Business The uri of the Business of this transaction
location Location The uri of the Location of this transaction. Include this OR the "external_location_id" parameter, but not both. PLEASE NOTE When creating redeem transactions for marketplace rewards, a location uri of a location at the marketplace business MUST be used. When creating redeem transactions for perks using the must_redeem_at_home_location option, the user's home location MUST be used. A user's home location can be found using the Connection resource.
external_location_id string The external_location_id of the Location you'd like to use for this transaction. Include this OR the "location" parameter, but not both.
perk Perk The uri of the Perk of this transaction
quantity int The quantity of the transaction -- usually this is used with the EARN transaction event for a dollar spent rule. Not typically used with a REDEEM type perk.
trans_source_id string This is an OPTIONAL parameter. This field is guaranteed to be unique for a business. API clients may use this field to ensure that the posted transaction is unique. For example, imagine an API client is awarding points for a customer's purchase. It may be a good idea to pass in the ID of the purchase into this field, avoiding the case where a customer may be awarded points twice for a purchase.
transaction_dt datetime This is an OPTIONAL parameter. It defaults to the current datetime. If passed in, we'll set the transaction_dt of the transaction to this value. This can be useful if posting transactions that occurred sometime in the past. This value may not be in the future, or more than 1 year in the past. This value must be in UTC! The following formats are valid -- '%Y-%m-%d %H:%M:%S', '%Y-%m-%d %H:%M', '%Y-%m-%d'
user_email string This is an OPTIONAL parameter. Include this or "user" but not both. If this user_email record exists in our database, we'll apply the transaction to that user. Otherwise, we'll create a new user with the passed user_email, first_name, and last_name.
user user The uri of the User of this transaction. This is an OPTIONAL parameter. Include this or "user_email" but not both.
first_name string Only include if you're using user_email instead of user. If this user_email record exists in our database, we'll apply the transaction to that user. Otherwise, we'll create a new user with the passed user_email, first_name, and last_name.
last_name string Only include if you're using user_email instead of user. If this user_email record exists in our database, we'll apply the transaction to that user. Otherwise, we'll create a new user with the passed user_email, first_name, and last_name.
send_email boolean Indicates if we should send an email to the user upon earning or redeeming. Defaults to true if nothing is passed in. Perks that the business has configured to not trigger an email will never do so regardless of the value of this parameter.
voucher_start_as_used boolean Only applicable to USER_REDEEM scopes. If this is true AND the perk is redeem-type perk, the user's voucher will be created in a USED status. This defaults to false, as normally users will need to redeem the voucher themselves.
voucher_start_as_unused boolean Only applicable to ADMIN_CUSTOMER_REDEEM scopes. If this is true AND the perk is redeem-type perk, the user's voucher will be created in a UNUSED status. This defaults to false, as normally perks redeemed by admins on a user's behalf are marked as USED.
Returns

A 201 response with a JSON object of the created Transaction if successful. Note that the "voucher" property will only appear if the transaction actually has a voucher.

PATCH

You can't update this resource

User

A User is a single person using the Perkville platform. Usually, Users have one or more Connections, which represent their customer relationship to a Business. This object includes contact information, such as email address.

Note: Instead of a user ID in the uri, you can call GET /v2/users/me/. This will return the User which belongs to the Bearer Token.

GET

GET /v2/users/{USER_ID}/ Example
Example Request
curl https://api.perkville.com/v2/users/me -H "Authorization: Bearer accesstoken123abc"
Example Response
{
    "birthday": "1909-04-23",
    "connections": [
        "/v2/connections/3/"
    ],
    "emails": [
        {
            "email": "john.doe@example.org",
            "primary": true
        }
    ],
    "first_name": "John",
    "last_mod_dt": "2016-06-02T14:30:45+00:00",
    "last_name": "Doe",
    "phone_number": "555-867-5309",
    "resource_uri": "/v2/users/261998/",
    "user_id": 261998
}
Restrictions

Required scopes:

  • PUBLIC
  • At least one of these:
    • ADMIN_CUSTOMER_INFO
    • USER_CUSTOMER_INFO

If USER_CUSTOMER_INFO is present, the only accessible record is the User associated with the access token.

If ADMIN_CUSTOMER_INFO is present, the only accessible records are those Users who are customers of the Business which the user associated with the access token is a staff member. For example, if the User associated with the access token is a staff member at Business 1, this will return all users who are customers of Business 1.

Fields
Property Name Type Filterable Description
user_id int ✓ The ID of this User
first_name string The user's first name
last_mod_dt datetime ✓ The date and time that this record was last modified in UTC
last_name string The user's last name
phone_number string The user's phone number
birthday date The user's birthday as "YYYY-MM-DD"
emails Object[] ✓ These are all the emails which are registered to this user account. (SUPPORTS RELATIONAL QUERIES) Note that emails in Perkville are unique. No two users share the same email address. Objects in this array have two keys, "email" and "primary". To filter users by email, use the quesystring parameter "emails__email". E.g., "https://api.perkville.com/v2/users/?emails__email=foo@foo.com".
connections Connection[] These objects represent a user's relationship to a business.

POST

You can't create new instances of this resource

PATCH

You can't update this resource

Voucher

A Voucher represents a redeemed reward. It's like a coupon -- The user exchanges a voucher for a physical reward.

A Voucher is created when a customer redeems a reward.

Vouchers can be "Marked as Used", indicating that the Voucher has been used and can't be redeemed again.

Vouchers can be created via the API, but not through this resource! Instead, use the Transaction resource, and post a REDEEM type Transaction.

If a business have disallowed canceled members from earning or redeeming points, vouchers for canceled members will not show up in the API.

GET

GET /v2/vouchers/{VOUCHER_ID}/ Example
Example Request
curl https://api.perkville.com/v2/vouchers/39437/ -H "Authorization: Bearer accesstoken123abc"
Example Response
{
    "business": "/v2/businesses/1/",
    "marketplace_business": null,
    "created_datetime": "2014-10-28T16:04:06+00:00",
    "expiration_date": "2014-12-26",
    "external_coupon_code": null,
    "location": "/v2/locations/10/",
    "network_reward_url": null,
    "perk": "/v2/perks/96/",
    "transaction": "/v2/transactions/5503404/",
    "point_cost": 24,
    "quantity": 1,
    "resource_uri": "/v2/vouchers/39437/",
    "status": "UNUSED",
    "user": "/v2/users/262251/",
    "voucher_id": 39437
}
Restrictions

Required scopes:

  • PUBLIC
  • At least one of these:
    • ADMIN_CUSTOMER_REDEEM
    • USER_CUSTOMER_INFO

If USER_CUSTOMER_INFO is present, the only accessible records are those which belong to the User associated with the access token.

If ADMIN_CUSTOMER_REDEEM is present, the only accessible records are those which belong to the Business which the User associated with the access token is a staff member. For example, if the User associated with the access token is a staff member at Business 1, accessible vouchers include those associated at Business 1.

Fields
Property Name Type Filterable Description
business Business ✓ The Business where the voucher was created. In most cases, this will also indicate where the voucher can be redeemed.
marketplace_business Business If the voucher is for a marketplace reward, this property will indicate the business where the voucher can be redeemed.
created_datetime datetime The datetime of when the voucher was created in UTC
expiration_date datetime The datetime when the voucher expires, in UTC
location Location ✓ The voucher can be redeemed at this Location
network_reward_url string A Reward URL displayed on a voucher instance
perk Perk ✓ The voucher was created by spending the point at this Perk
transaction Transaction The transaction associated with creating this voucher. In order to display the details of the perk AT THE TIME it was redeemed, you need to look at the transaction record. Any of a perks details may have been edited since the voucher was created.
point_cost int The voucher cost this many points to redeem
status string Indicates whether this voucher has been used or not. Values include 'USED', 'UNUSED', 'EXPIRED', 'EMAILED_REWARD', 'PROCESSING', 'CREDITED', 'VOIDED'
voucher_id int ✓ The voucher ID of this voucher. Often referred to as the "Voucher Code" on the Perkville website.
user User ✓ The user who owns the voucher. (SUPPORTS RELATIONAL QUERIES)
external_coupon_code string The business' internal identifier for this perk. Businesses typically use it instead of the voucher code when representing perkville vouchers in third party systems. If the external_coupon_code is present, display it instead of the voucher code.

POST

You can't create new instances of this resource

PATCH

This endpoint allows you to mark a voucher as USED. This is only value allowed to be updated for a voucher!
PATCH /v2/vouchers/{VOUCHER_ID}/ Example
Example Request
curl --request PATCH https://api.perkville.com/v2/vouchers/39437/ -H "Authorization: Bearer ryYMKAkopdwNb82FJTmxJ31L7T6K8z" -H "Content-Type: application/json" -d '{ "status": "USED" }'
Example Response
202 Accepted
{
    "business": "/v2/businesses/1/",
    "created_datetime": "2014-10-28T16:04:06+00:00",
    "expiration_date": "2014-12-26",
    "external_coupon_code": null,
    "location": "/v2/locations/10/",
    "perk": "/v2/perks/96/",
    "transaction": "/v2/transactions/5503404/",
    "point_cost": 24,
    "quantity": 1,
    "resource_uri": "/v2/vouchers/39437/",
    "status": "USED",
    "user": "/v2/users/262251/",
    "voucher_id": 39437
}
Restrictions

Required scopes:

  • PUBLIC
  • At least one of these:
    • ADMIN_CUSTOMER_REDEEM
    • USER_CUSTOMER_INFO

If USER_CUSTOMER_INFO is present, the only accessible records are those which belong to the User associated with the access token.

If ADMIN_CUSTOMER_REDEEM is present, the only accessible records are those which belong to the Business which the User associated with the access token is a staff member. For example, if the User associated with the access token is a staff member at Business 1, accessible vouchers include those associated at Business 1.

Parameters
Include only valid JSON in your HTTP body.
Property Name Type Description
status string Indicates whether this voucher has been used or not. The only valid value here is 'USED'.
Returns

202 Accepted with a JSON object of the patched Voucher.

Getting Started with API Reports

The following reporting endpoints allow a staff member to run reports on business data using our API. While these endpoints are a part of APIv2, some of their basic functionality differs from the resources endpoints.

Querystring Parameters

Unlike resource endpoints, the querystring parameters of a GET request are not used to filter a resulting list of objects. They are instead used to set the parameters of a report we will be running on a staff member's behalf.

The Querystring Parameters table of each endpoint documents the parameters that can be set for a report.

Business Primary Key

A business querystring parameter is always required.

GET https://api.perkville.com/v2/top-earners/?business=1234
Greater Than/Less Than Filter

Greater Than/Less Than Filters are not supported in the reporting API. If a report accepts from_date and to_date parameters, you should set those values when needed. 

GET https://api.perkville.com/v2/top-earners/?business=1234&from_date=2017-08-01&to_date=2017-08-31
"In" filter

The "In" filter can be used to specify multiple values for parameters whose type has [] appended. 

GET https://api.perkville.com/v2/top-earners/?business=1234&locations__in=5,6

Top Earners

This endpoint returns a list of customers by points earned in descending order.

GET

GET /v2/top-earners/?business={business_id} Example
Example Request
curl https://api.perkville.com/v2/top-earners/?business=4 -H "Authorization: Bearer accesstoken123abc"
Example Response
{
    "first_name": "John",
    "last_name": "Doe",
    "user_id": 544623,
    "last_earned_location_id": 2684,
    "home_location_id": 2684,
    "points_earned": 100,
    "connection_id": 767193,
    "primary_user_address": "john.doe@example.org"
}
Restrictions

Required scopes:

  • ADMIN_CUSTOMER_INFO

Pagination:

  • A limit of 100 records is the most allowed for a single query.

Querystring Parameters
Name Type Required Description
business_id integer ✓ The primary key of the business to run a report for.
locations integer[] One or more location primary keys. User point totals will only include points earned at specified locations.
from_date date Beginning of report date range using format YYYY-MM-DD.
to_date date End of report date range using format YYYY-MM-DD.
hide_pending boolean Setting this parameter will exclude PENDING users.
hide_cancelled boolean Setting this parameter will exclude users without an ACTIVE connection to the business.
Fields
Property Name Type Filterable Description
first_name string The user's first name.
last_name string The user's last name.
user_id integer The primary key of the User.
last_earned_location_id integer The primary key of the location where the user last earned points.
home_location_id integer The primary key of the user's home location.
points_earned integer The total number of points earned by the user during the report's date range.
connection_id integer The primary key of the connection resource referencing the user and business.
primary_email_address string The user's primary email address