Perkville

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",
    "rewards_program_join_dt": "2016-03-02T13:33:11+00:00",
    "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.

Required Filters

GET requests to the connection endpoint that do not specify a CONNECTION_ID are required to append either a business filter, user filter, or both. Using an "IN" style query with the business filter is also not allowed with the connection resource.

Examples of VALID requests:

 /v2/connections/55/
 /v2/connections/?business=6
 /v2/connections/?business=6&user=1125
 /v2/connections/?business=6&user__in=1123,1125
 /v2/connections/?user=1125
 /v2/connections/?user__in=1123,1125
 /v2/connections/?user__emails__email=api@perkville.com

Examples of INVALID requests:

 /v2/connections/
 /v2/connections/?business__in=5,6
 /v2/connections/?business__in=6,7&user=1122
 /v2/connections/?business__in=6,7&user__emails__email=api@perkville.com

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"
rewards_program_join_dt	datetime		The date and time the user joined the business's rewards program. This field can be null if the user has not joined the rewards program.
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. Note that this datetime primarily applies to the "status" attribute and external membership information. For recently modified point balances, please use the Connection Balance resource.
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",
    "rewards_program_join_dt": "2016-03-02T13:33:11+00:00",
    "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	DEPRECATED - Please use External Member - 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	DEPRECATED - Please use External Member - 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	DEPRECATED - Please use External Member - Indicates the user's membership status at the business. Valid values are "ACTIVE" and "INACTIVE" ONLY.
external_membership_type	string	DEPRECATED - Please use External Member - This is an OPTIONAL parameter. The user's membership type at the business
external_home_location_id	string	DEPRECATED - Please use External Member - 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	DEPRECATED - Please use External Member - 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.

Connection Balance

The point balance of a Connection. This endpoint provides the ability to fetch recently updated point balances for a given Business.

While the Connection endpoint includes point balance as a matter of convenience, you cannot filter for Connections who recently had their balances adjusted.

GET

GET /v2/connection-balances/{CONNECTION_BALANCE_ID}/ Example

Example Request

curl https://api.perkville.com/v2/connection-balances/5/ -H "Authorization: Bearer accesstoken123abc"

Example Response

{
    "business": "/v2/businesses/4/",
    "connection": "/v2/connections/3/",
    "last_biz_perk_title": "Check in",
    "last_mod_dt": "2016-03-02T13:33:11+00:00",
    "last_transaction_dt": "2016-03-02T13:33:10+00:00",
    "lifetime_earned_points": 300,
    "lifetime_spent_points": 286,
    "point_balance": 14,
    "resource_uri": "/v2/connection-balances/5/",
    "user": "/v2/users/261998/"
}

Restrictions

Required scopes:

PUBLIC
ADMIN_CUSTOMER_INFO

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.

Required Filters

GET requests to the connection endpoint that do not specify a CONNECTION_BALANCE_ID are required to append at least a connection filter, business filter, or user filter. Using an "IN" style query with the business filter is also not allowed with the connection balance resource.

Examples of VALID requests:

 /v2/connection-balances/55/
 /v2/connection-balances/?business=6
 /v2/connection-balances/?business=6&last_mod_dt__gte=2019-01-01
 /v2/connection-balances/?business=6&user__in=1123,1125
 /v2/connection-balances/?user=1125
 /v2/connection-balances/?user__in=1123,1125
 /v2/connection-balances/?email=api@perkville.com
 /v2/connection-balances/?connection=3

Examples of INVALID requests:

 /v2/connection-balances/
 /v2/connection-balances/?business__in=5,6
 /v2/connection-balances/?last_mod_dt__gte=2019-01-01

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	Connection	✓	The relationship between a User and a Business
last_biz_perk_title	string		The name of the Perk for their latest transaction
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
lifetime_earned_points	int		The total amount of points the customer has earned at the business through Perkville
lifetime_spent_points	int		The total amount of points the customer has spent at the business through Perkville
point_balance	int		The current balance of this customer
resource_uri	string		The url of this Connection Balance record in Perkville's API.
user	User	✓	The user to which this connection belongs. (SUPPORTS RELATIONAL QUERIES)

POST

You can't create new instances of this resource

PATCH

You can't update this resource

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_WARM_REG_REQUEST_NO_POINTS

Sent to a business customer prompting them to join a rewards program if a business does not allow users to earn points until they join Perkville.

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.
sent_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

External Member

Fetch, update, or create external membership details for a user at a business.

Required Filters

GET requests to the external member endpoint that do not specify a EXTERNAL_MEMBER_IDENTIFIER_ID are required to append either a business filter, user filter, or both. Using an "IN" style query with the business filter is also not allowed on this resource. With the above conditions met, you may also filter on external_system_id, and, more specifically, external_member_id.

Examples of VALID requests:

    /v2/external-members/55/
    /v2/external-members/?business=6
    /v2/external-members/?business=6&user=1125
    /v2/external-members/?business=6&user__in=1123,1125
    /v2/external-members/?user=1125
    /v2/external-members/?user__in=1123,1125
    /v2/external-members/?user__emails__email=api@perkville.com
    /v2/external-members/?business=6&external_system_id=EXAMPLE_SOFTWARE
    /v2/external-members/?business=6&external_system_id=EXAMPLE_SOFTWARE&external_member_id=1111111

Examples of INVALID requests:

    /v2/external-members/
    /v2/external-members/?business__in=5,6
    /v2/external-members/?business__in=6,7&user=1122
    /v2/external-members/?business__in=6,7&user__emails__email=api@perkville.com
    /v2/external-members/?external_member_id=1111111
    /v2/external-members/?&external_system_id=EXAMPLE_SOFTWARE&external_member_id=1111111

GET

GET /v2/external-members/{EXTERNAL_MEMBER_IDENTIFIER_ID}/ Example

Example Request

curl https://api.perkville.com/v2/external-members/3/ -H "Authorization: Bearer accesstoken123abc"

Example Response

{
  "business": "/v2/businesses/2/",
  "connection": "/v2/connections/1/",
  "created_dt": "2019-04-01T23:16:47.266014+00:00",
  "external_cancel_dt": null,
  "external_join_dt": "2018-05-02T12:35:00+00:00",
  "external_member_id": "1111111",
  "external_membership_status": null,
  "external_membership_type": null,
  "external_system_id": "EXAMPLE_SOFTWARE",
  "home_location": "/v2/locations/2/",
  "id": "3",
  "last_mod_dt": "2019-04-01T23:16:47.266667+00:00",
  "resource_uri": "/v2/external-members/3/",
  "user": "/v2/users/2/"
}

Restrictions

Required scopes:

ADMIN_CUSTOMER_INFO

Fields

Property Name	Type	Filterable	Description
business	Business	✓	The business to which this external member belongs.
connection	Connection		The relationship between a User and a Business
user	User	✓	The user to which this external member belongs. (SUPPORTS RELATIONAL QUERIES)
resource_uri	string		The url of this record in Perkville's API.
external_system_id	string	✓	A unique identifier representing the external system from which this member came.
external_member_id	string	✓	The external identifier for this membership record. When filtering on this attribute, external_system_id is REQUIRED
external_membership_type	string		The external member's membership type
external_membership_status	string		The external member's membership status. Values include "ACTIVE", "INACTIVE", or null.
home_location	Location		The external member's home location
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"

POST

POST /v2/external-members/ Example

Example Request

curl https://api.perkville.com/v2/external-members/ -H "Authorization: Bearer accesstoken123abc" -d '{"business": "/v2/businesses/1/", "home_location": "/v2/locations/2/", "external_member_id": "1111111", "external_system_id": "EXAMPLE_SOFTWARE", "user_email": "john.doe@example.org", "external_join_dt": "2018-05-02 12:35:00"}'

Example Response

{
  "business": "/v2/businesses/2/",
  "connection": "/v2/connections/1/",
  "created_dt": "2019-04-01T23:16:47.266014+00:00",
  "external_cancel_dt": null,
  "external_join_dt": "2018-05-02T12:35:00+00:00",
  "external_member_id": "1111111",
  "external_membership_status": null,
  "external_membership_type": null,
  "external_system_id": "EXAMPLE_SOFTWARE",
  "home_location": "/v2/locations/2/",
  "id": "3",
  "last_mod_dt": "2019-04-01T23:16:47.266667+00:00",
  "resource_uri": "/v2/external-members/3/",
  "user": "/v2/users/2/"
}

Restrictions

Required scopes:

ADMIN_CUSTOMER_INFO

Parameters

Include only valid JSON in your HTTP body.

Property Name	Type	Description
business	Business	The business to which this external member belongs.
user_email	string	The email of the user to which this external member belongs.
external_member_id	string	The external identifier for this membership record
external_system_id	string	A unique identifier representing the external system from which this member came.
external_membership_type	string	OPTIONAL. The external member's membership type
external_membership_status	string	OPTIONAL. The external member's membership status. Values include "ACTIVE", "INACTIVE", or null.
home_location	Location	OPTIONAL. The URI of the external member's home location. Include this OR the "home_location" parameter, but not both.
external_home_location_id	string	OPTIONAL. The external_location_id of the Location you'd like to use for this external member's home location. Include this OR the "home_location" parameter, but not both.
external_cancel_dt	datetime	OPTIONAL. The date and time a user's membership status converted from "ACTIVE" to "INACTIVE"
external_join_dt	datetime	OPTIONAL. The date and time a user's membership became "ACTIVE"

Returns

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

PATCH

PATCH /v2/external-members/{EXTERNAL_MEMBER_IDENTIFIER_ID}/ Example

Example Request

curl https://api.perkville.com/v2/external-members/3/ -H "Authorization: Bearer accesstoken123abc" -d '{"home_location": "/v2/locations/1/", "external_membership_type": "NEW_TYPE",
    "external_membership_status": "ACTIVE"}'

Example Response

{
  "business": "/v2/businesses/2/",
  "connection": "/v2/connections/1/",
  "created_dt": "2019-04-01T23:16:47.266014+00:00",
  "external_cancel_dt": null,
  "external_join_dt": "2018-05-02T12:35:00+00:00",
  "external_member_id": "1111111",
  "external_membership_status": "ACTIVE",
  "external_membership_type": "NEW_TYPE",
  "external_system_id": "EXAMPLE_SOFTWARE",
  "home_location": "/v2/locations/1/",
  "id": "3",
  "last_mod_dt": "2019-04-01T23:21:47.266667+00:00",
  "resource_uri": "/v2/external-members/3/",
  "user": "/v2/users/2/"
}

Restrictions

Required scopes:

ADMIN_CUSTOMER_INFO

Parameters

Include only valid JSON in your HTTP body.

Property Name	Type	Description
external_membership_type	string	The external member's membership type
external_membership_status	string	The external member's membership status. Values include "ACTIVE", "INACTIVE", or null.
home_location	Location	The external member's home location
external_home_location_id	string	The external_location_id of the Location you'd like to use for this external member's home location. Include this OR the "home_location" parameter, but not both.
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"

Returns

A 201 response with a JSON object of the updated External Member if successful.

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_to_first_name	string	The first name of the person being referred. This is an optional parameter.
referral_to_last_name	string	The last name of the person being referred. This is an optional parameter.
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."

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

When creating a Transaction, the following fields must always be present:

Business URI
Location URI or External location ID
Perk URI
Quantity
Trans source ID (Not technically required, but strongly recommended)

We STRONGLY recommend using a trans_source_id. This will ensure that the same event will never be awarded twice, like if you post older events to backfill data. It also greatly helps in debugging, as we can point to the exact event ID from your application that created this Transaction.

For identifying whom should receive this Transaction, there are a few options:

User URI
User email
External member ID and External system ID

If the User exists, we'll simply add that Transaction for that User. If the User doesn't exist, we'll create a new user from the provided email, award the Transaction, and then send the user an invitational email.

Alternatively, if the external member ID and external system IDs are present, we'll look up the User, and add that Transaction for that User. If no User has the provided external member info, we'll create a User from the provided email, award the Transaction, and then send the user an invitational email. If no email was provided in the latter case, the Transaction will fail.

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.
external_member_id	string	This is an OPTIONAL parameter. This can serve as a separate identifier for a User. If included, this external_member_id will be used to identify the User. If the external_member_id does not already exist, then it will become associated with user/user_email passed into the request.
external_system_id	string	This is an OPTIONAL parameter, however must be included when using the external_member_id parameter. This is used to identify the external membership system. So if the membership system is something like "Example Software", you could use "EXAMPLE_SOFTWARE" as the ID
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

Getting Started with Batch Endpoints

The following endpoints allow a staff member to post data in bulk to our API. While these endpoints are a part of APIv2, some of their basic functionality differs from the resources endpoints.

Resource URIs

Resource URIs are not supported. Only primary keys are used.

Transaction Batch

This accepts a list of transaction data for a given Business.

GET

You can't read from this resource.

POST

POST /v2/batch/transactions/ Example

Example Request

curl https://api.perkville.com/v2/batch/transactions/ -H "Authorization: Bearer accesstoken123abc" -H "Content-Type: application/json" -d '{ "business": "1", "transactions": [{"location": "2", "perk": "397", "quantity": "1", "user_email": "edward_test@perkville.com", "first_name": "Edward", "last_name": "McFudge"}, {"location": "1", "perk": "397", "quantity": "1", "user_email": "rex_test@perkville.com", "first_name": "Rex", "last_name": "McJudge"}] }'

Example Response

{
    'business': '1',
    'transactions': [
        {
            'classification': 'REDEEM',
            'transaction_dt': '2015-01-30T23:54:04.147208+00:00',
            'perk': '397',
            'business': '1',
            'transaction_status': 'ACTIVE',
            'voucher': '552044',
            'transaction_reference': null,
            'location': '2',
            'user': '263727',
            'title': 'Free Hoodie',
            'trans_source_id': null,
            'points': 300,
            'transaction_id': 3144,
            'quantity': 1
        },
        {
            'errors': {
                'message': 'The user doesn't have enough points to complete this transaction.',
                'code': 'pv_txn_insufficient_points'
            }
        }
    ]
}

Restrictions

Required scopes:

PUBLIC
Both of these:
- ADMIN_CUSTOMER_GRANT_POINTS
- ADMIN_CUSTOMER_REDEEM

When creating batch Transactions, the following fields will apply to the entire batch:

Business (required)
Send email
Voucher start as unused

For each transaction in the 'transactions' list the following fields must always be present:

Business URI
Location URI or External location ID
Perk URI
Quantity
Trans source ID (Not technically required, but strongly recommended)

Parameters

Include only valid JSON in your HTTP body.

Property Name	Type	Description
business	int	The ID of the Business of this transaction
send_email	boolean	This is an OPTIONAL parameter. 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_unused	boolean	This is an OPTIONAL parameter. 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.
transactions	list	A list of JSON objects containing transaction information. See Transaction Parameters below for more detail.

Transaction Parameters

Include only valid JSON in your HTTP body.

Property Name	Type	Description
location	int	The ID 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 ID 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	int	The ID 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 ID 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.
external_member_id	string	This is an OPTIONAL parameter. This can serve as a separate identifier for a User. If included, this external_member_id will be used to identify the User. If the external_member_id does not already exist, then it will become associated with user/user_email passed into the request.
external_system_id	string	This is an OPTIONAL parameter, however must be included when using the external_member_id parameter. This is used to identify the external membership system. So if the membership system is something like "Example Software", you could use "EXAMPLE_SOFTWARE" as the ID

Returns

A 200 response with a list of JSON objects representing each transaction's result. Results will be returned in the order they were given. If successful, the JSON object will include the created transaction details. If unsuccessful, it will include an "errors" JSON object with detail about what went wrong. Please toggle the posted Example for a clear view of the behavior.

Perkville Version 2 API

Client Registration

Authentication

OAuth2 Authorization

Authorization Code Grant

Step 1

Step 2

Step 3

Resource Owner Password Credentials Grant

Use Cases

Appropriate Usage

Password Grant Flow

Scopes

Accessing Endpoints

Authorization Header

Filtering

Primary Key

Combining Filters

"In" filter

Greater Than/Less Than Filter

Relational Queries

Pagination

Handling Errors

Business

GET

Example Request

Example Response

Restrictions

Fields

POST

PATCH

Business Staff

GET

Example Request

Example Response

Restrictions

Fields

POST

PATCH

Connection

GET

Example Request

Example Response

Restrictions

Required Filters

Fields

POST

PATCH

Example Request

Example Response

Restrictions

Parameters

Returns

Connection Balance

GET

Example Request

Example Response

Restrictions

Required Filters

Fields

POST

PATCH

Email Tracking

Emails sent to business customers

Emails sent to business staff

Emails that may be sent to either staff or customers

Legacy - These emails are no longer used

GET

Example Request

Example Response

Restrictions

Fields

POST

PATCH

External Member

Required Filters

GET

Example Request

Example Response

Restrictions