Perkville Version 2 API
Jump right into the API documentation. We're always happy to help out with any questions you might have. Drop us a message at api@perkville.com
Client Registration
Before making requests to the Perkville v2 API, clients must first register with Perkville. Once the registration form has been filled out and submitted, we will email the new client id and secret to the contact email that is provided.
New clients will only be allowed to request the PUBLIC scope (see the scopes section below). A Perkville representative will contact the person included in the client registration form to verify the authenticity of the developer and discuss what permissions your application will need from the Perkville API.
RegisterAuthentication
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.
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=1234This 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_BONUSThis 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%3A00ZThe 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=REDEEMThe 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
PATCH
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
PATCH
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.
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 |
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
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
Property Name | Type | Description |
external_cancel_dt | datetime | This field is strongly suggested if setting the user's external_membership_status to INACTIVE. The date and time a user's membership status converted from "ACTIVE" to "INACTIVE". This will be converted to UTC, so we strongly suggest adding UTC offset or Z to the datetime. |
external_join_dt | datetime | This field is strongly suggested if setting the user's external_membership_status to ACTIVE. The date and time a user's membership became "ACTIVE". This will be converted to UTC, so we strongly suggest adding UTC offset or Z to the datetime. |
external_membership_status | string | Indicates the user's membership status at the business. Valid values are "ACTIVE" and "INACTIVE" ONLY. |
external_membership_type | string | This is an OPTIONAL parameter. The user's membership type at the business |
external_home_location_id | string | This is an OPTIONAL parameter. The external_location_id of the user's home Location. Include this or the home_location, but not both. |
home_location | Location | This is an OPTIONAL parameter. The uri of the user's home Location. Include this or the external_home_location_id, but not both. |
status | string | Indicates if the user has accepted the rewards program for this business. Valid values are "ACTIVE" and "INACTIVE" ONLY. |
Returns
202 Accepted with a JSON object of the patched Connection.
Email Tracking
Returns a list of emails sent from Perkville businesses associated with the API token used.
This endpoint can be filtered on most fields. The `type` field can be filtered on using the following values:>
Emails sent to business customers
- USER_WARM_REG_REQUEST
- Sent to a business customer prompting them to join a rewards program after receiving points for the first time.
- USER_EARN_ALERT
- Sent to a business customer who is actively connected to a business' rewards program after earning new points.
- USER_REDEEM_ALERT
- Sent to a business customer after they redeem for a perk.
- BONUS_REFERRAL_INFORM
- Email that is sent when a business customer refers a friend and the business has not set up a referral offer.
- REFERRAL_OFFER
- Email that is sent when a business customer refers a friend and the business has an active referral offer.
- WEEKLY_CUSTOMER_REPORT
- Sent to a business customer summarizing their transaction activity over the past week.
- CLAIMED_OFFER
- Sent to a customer after they claim an offer from a business.
- VOUCHER_EXPIRES
- Sent to a business customer alerting them that they have unused vouchers that will expire soon.
- CUSTOMER_INVITE
- Sent to users that have been invited to join a business' loyalty program by a staff member.
- USER_COLD_REG_REQUEST
- Email contaning a registration link that is sent to users who join Perkville by signing up on our website.
Emails sent to business staff
- BUSINESS_DAILY_STATS
- Sent to business staff summarizing the activity at their business over the past day.
- WEEKLY_BUSINESS_REPORT
- Email sent to business admins summarizing their business' activity over the past week.
- MONTHLY_BUSINESS_REPORT
- Email sent to business admins summarizing their business' activity over the past month.
- BUSINESS_ADD_EMPLOYEE_INFORM
- Sent to a user when they are added as a staff member at a business.
- BUSINESS_LIVE_ALERT
- Sent to business admins when their business first goes live on Perkville.
- OBLIGATION
- Sent to business admins and employees when a customer claims an offer or redeems a perk.
- NOTIFY_LIMIT_EXCEEDED
- Sent to a business admin when a batch process fails because it attempted to upload too many records.
- BATCH_UPLOAD_REPORT
- Sent to a business admin after a batch process has successfully been completed.
- COMPLETED_REFERRAL_ADMIN_INFORM
- Sent to a business admin after a new customer has been successfully referred to their business.
- BIZ_COUPON_REMINDER
- For businesses that have uploaded custom coupon codes, this email is sent to staff when a location is running low.
- MARKETPLACE_ONLY_CONFIRM_EMAIL
- Sent to an admin of Perkville Marketplace businesses prompting them to confirm their email.
- MARKETPLACE_ONLY_GET_STARTED
- Sent to business that join Perkville as a marketplace only business giving them tips on how to get started.
- INVITE_BATCH_UPLOAD_REPORT
- Sent to a business admin after they have successfully uploaded a list of user's to be invited to their rewards program.
- BUSINESS_OVERAGE_WARN
- Sent to a business admin alerting them that they have exceeded the maximum number of transactions that their plan allows
Emails that may be sent to either staff or customers
- USER_CONFIRM_EMAIL_REQUEST
- Sent to users registering via our website or changing their primary email address.
- USER_MERGE_REQUEST
- A confirmation email sent as part of the user account merge process.
- USER_MERGE_OK
- Sent to a user after they have successfully merged two accounts.
Legacy - These emails are no longer used
- USER_EARN_WAITING_ALERT
- BUSINESS_WELCOME
- GET_STARTED_REPORT
- REFERRAL_PROMPT
- API_REGISTRATION_BONUS
GET
GET /v2/email-tracking/{EMAIL_TRACKING_ID}/
Example
Example Request
curl https://api.perkville.com/v2/email-tracking/59/ -H "Authorization: Bearer accesstoken123abc"
Example Response
{ "business_id": 1832, "resource_uri": "/v2/email-tracking/59/", "sent_dt": "2016-11-20T17:53:25+00:00", "type": "USER_EARN_ALERT", "user_email": "edward_test@perkville.com", "user_id": 263727 }
Restrictions
Required scopes:
- ADMIN_CUSTOMER_INFO
Fields
Property Name | Type | Filterable | Description |
business_id | integer | ✓ | The primary key of the business associated with this email. |
location_id | integer | The primary key of the location associated with this email. This field can be null if an email is not associated with any location in particular. | |
resource_uri | string | The url of this record in Perkville's API. | |
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
PATCH
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
PATCH
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
PATCH
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
PATCH
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
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
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
PATCH
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
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
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
PATCH
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
Property Name | Type | Description |
business | Business | The uri of the Business of this referral. |
location | Location | The uri of the Location of this referral. This is an OPTIONAL parameter. |
referral_from_user | User | The uri of the User who is sending the referral. If USER_REFERRAL scope is present, this field will always be equal to the user making the referral request. |
referral_to_email | string | The email address of the person being referred to the specified business. |
referral_content | string | A personalized note to be sent along with the referral. This is an OPTIONAL parameter. |
send_referral_email | boolean | Determines whether to send a referral email to the user being referred. An input of true will send an email and an input of false will not send an email. This is an OPTIONAL parameter and if excluded will automatically default to true. |
submit_as_referrer | boolean | Only applicable to ADMIN_CUSTOMER_REFERRAL scopes. When set to true, if the referral_to_email has an existing connection with the business, the referral will be rejected. When set to false, the referral will be created regardless of the referral_to_email's connection with the business. This is an OPTIONAL parameter, and if excluded will automatically default to false. |
Returns
A 201 response with a JSON object of the created Referral if successful.
PATCH
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
PATCH
Transaction
A Transaction is a single event where a user earns or spends points. An example of a Transaction would be "Bob checked in at Yoga Studio Extreme on March 5th 2015 and earned 15 points."
You can create a transaction in one of two ways: First, if you know the the user ID, you can pass in just the user URI along with the Business, Location and Perk URIs, plus the quantity.
However, if you don't know the user ID, you can pass the user's email address, first name and last name, along with the Business, Location, and Perk URIs, plus the quantity. If that user exists, we'll simply add that Transaction for that user. If the user doesn't exist, we'll create a new user, award the Transaction, and then send the user an invitational email.
In addition, you can retrieve a specific transaction or a list of transactions.
NOTE: If you are requesting a list of transactions using the ADMIN_CUSTOMER_INFO scope, we require you to append a user filter, e.g. ?user={{USER_ID}}
or a filter related to the user model, e.g. ?user__emails__email="{{USER_EMAIL}}"
. For more information on related fields, please see the documentation for the user resource. If you are using the USER_CUSTOMER_INFO scope a user filter is not required since those requests will already be filtered by records belonging to the user making the request.
GET
GET /v2/transactions/{TRANSACTION_ID}/
Example
Example Request
curl https://api.perkville.com/v2/transactions/232442/ -H "Authorization: Bearer accesstoken123abc"" -H "Content-Type: application/json"
Example Response
{ 'business': '/v2/businesses/25/', 'location': '/v2/locations/2/', 'perk': '/v2/perks/397/', 'title': 'Free Hoodie', 'points': 300, 'quantity': 1, 'resource_uri': '/v2/transactions/232442/', 'trans_source_id': '', 'transaction_dt': '2015-01-30T23:54:04.147208+00:00', 'transaction_id': 3144, 'user': '/v2/users/263727/', 'voucher': '/v2/vouchers/552044/' }
Restrictions
Required scopes:
- PUBLIC
- At least one of these:
- ADMIN_CUSTOMER_INFO
- USER_CUSTOMER_INFO
If ADMIN_CUSTOMER_INFO is present, you can retrieve transaction records from businesses and locations that the user making the request is an administrator of.
If USER_CUSTOMER_INFO is present, you can retrieve transaction records for the user making the request.
Fields
Property Name | Type | Filterable | Description |
business | Business | ✓ | The uri of the Business of this transaction |
location | Location | ✓ | The uri of the Location of this transaction. Include this OR the "external_location_id" parameter, but not both. |
perk | Perk | The uri of the Perk of this transaction. (SUPPORTS RELATIONAL QUERIES) | |
title | string | The user-readable description of what this transaction was actually for. e.g., "Checkin" or "Free Hoodie" | |
classification | string | The classification of the perk tied to this transaction. Either "EARN" or "REDEEM", indicating if this rule is for receiving points or for spending. | |
points | int | The points that were either spent (REDEEM type perk) or earned (EARN type perk) with this transaction. | |
quantity | int | The quantity of the transaction -- usually this is used with the EARN transaction event for a dollar spent rule. | |
trans_source_id | string | This field may be present if the transaction was created via an API. It is used to ensure that the transaction is unique at this business. | |
transaction_dt | datetime | ✓ | The date and time the transaction was created. |
transaction_id | int | The ID number for the transaction. | |
transaction_status | string | ✓ | The current status of the Transaction. The options are ACTIVE, VOID, VOID_REF. When a transaction is voided two the things happen. The transaction gets updated with a status of VOID, and a new transaction, for the negative amount of the original transaction, is created with the status VOID_REF. The transaction_reference field described below will also be used in order for the original transaction to reference the transaction that voided it and vice versa. |
transaction_reference | Transaction | Certain types of transactions may be created in reference to another transaction. In those cases this field is used. | |
user | User | ✓ | The uri of the User associated with the transaction. (SUPPORTS RELATIONAL QUERIES) |
voucher | Voucher | The uri of the Voucher used in the transaction. |
POST
POST /v2/transactions/
Example
Example Request
curl https://api.perkville.com/v2/transactions/ -H "Authorization: Bearer ryYMKAkopdwNb82FJTmxJ31L7T6K8z" -H "Content-Type: application/json" -d '{ "business": "/v2/businesses/1/", "location": "/v2/locations/2/", "perk": "/v2/perks/397/", "quantity": "1", "user_email": "edward_test@perkville.com", "first_name": "Edward", "last_name": "McFudge" }'
Example Response
{ 'business': '/v2/businesses/25/', 'location': '/v2/locations/2/', 'perk': '/v2/perks/397/', 'points': 300, 'quantity': 1, 'resource_uri': '/v2/transactions/232442/', 'trans_source_id': '', 'transaction_dt': '2015-01-30T23:54:04.147208+00:00', 'transaction_id': 3144, 'user': '/v2/users/263727/', 'voucher': '/v2/vouchers/552044/' }
Restrictions
Required scopes:
- PUBLIC
- At least one of these:
- ADMIN_CUSTOMER_GRANT_POINTS
- ADMIN_CUSTOMER_REDEEM
- USER_REDEEM
- At least one of these:
- ADMIN_CUSTOMER_INFO
- USER_CUSTOMER_INFO
If ADMIN_CUSTOMER_GRANT_POINTS is present, you may create EARN transactions for any customers who belong to the Business for which this user is a staff member.
If USER_REDEEM is present, you may create a REDEEM transaction for only the user associated with the bearer token. This will create an UNUSED Voucher, unless voucher_start_as_used is set to True.
If ADMIN_CUSTOMER_REDEEM is present, you may create REDEEM transactions for any customers who belong to the Business for which this user is a staff member. This will create a USED voucher, unless voucher_start_as_unused is set to True.
Parameters
Property Name | Type | Description |
business | Business | The uri of the Business of this transaction |
location | Location | The uri of the Location of this transaction. Include this OR the "external_location_id" parameter, but not both. PLEASE NOTE When creating redeem transactions for marketplace rewards, a location uri of a location at the marketplace business MUST be used. When creating redeem transactions for perks using the must_redeem_at_home_location option, the user's home location MUST be used. A user's home location can be found using the Connection resource. |
external_location_id | string | The external_location_id of the Location you'd like to use for this transaction. Include this OR the "location" parameter, but not both. |
perk | Perk | The uri of the Perk of this transaction |
quantity | int | The quantity of the transaction -- usually this is used with the EARN transaction event for a dollar spent rule. Not typically used with a REDEEM type perk. |
trans_source_id | string | This is an OPTIONAL parameter. This field is guaranteed to be unique for a business. API clients may use this field to ensure that the posted transaction is unique. For example, imagine an API client is awarding points for a customer's purchase. It may be a good idea to pass in the ID of the purchase into this field, avoiding the case where a customer may be awarded points twice for a purchase. |
transaction_dt | datetime | This is an OPTIONAL parameter. It defaults to the current datetime. If passed in, we'll set the transaction_dt of the transaction to this value. This can be useful if posting transactions that occurred sometime in the past. This value may not be in the future, or more than 1 year in the past. This value must be in UTC! The following formats are valid -- '%Y-%m-%d %H:%M:%S', '%Y-%m-%d %H:%M', '%Y-%m-%d' |
user_email | string | This is an OPTIONAL parameter. Include this or "user" but not both. If this user_email record exists in our database, we'll apply the transaction to that user. Otherwise, we'll create a new user with the passed user_email, first_name, and last_name. |
user | user | The uri of the User of this transaction. This is an OPTIONAL parameter. Include this or "user_email" but not both. |
first_name | string | Only include if you're using user_email instead of user. If this user_email record exists in our database, we'll apply the transaction to that user. Otherwise, we'll create a new user with the passed user_email, first_name, and last_name. |
last_name | string | Only include if you're using user_email instead of user. If this user_email record exists in our database, we'll apply the transaction to that user. Otherwise, we'll create a new user with the passed user_email, first_name, and last_name. |
send_email | boolean | Indicates if we should send an email to the user upon earning or redeeming. Defaults to true if nothing is passed in. Perks that the business has configured to not trigger an email will never do so regardless of the value of this parameter. |
voucher_start_as_used | boolean | Only applicable to USER_REDEEM scopes. If this is true AND the perk is redeem-type perk, the user's voucher will be created in a USED status. This defaults to false, as normally users will need to redeem the voucher themselves. |
voucher_start_as_unused | boolean | Only applicable to ADMIN_CUSTOMER_REDEEM scopes. If this is true AND the perk is redeem-type perk, the user's voucher will be created in a UNUSED status. This defaults to false, as normally perks redeemed by admins on a user's behalf are marked as USED. |
Returns
A 201 response with a JSON object of the created Transaction if successful. Note that the "voucher" property will only appear if the transaction actually has a voucher.
PATCH
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
PATCH
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
PATCH
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
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 |