Perkville Version 1 API

Jump right into the API documentation. We're always happy to help out with any questions you might have [email protected]

Authentication

Authentication for the v1 Perkville API is handled by passing in a registered Perkville email/password along with every API request via Basic Authentication. Every incoming request MUST use the HTTPS protocol.


Response Format

Perkville offers API responses in the JSON, XML, and HTML format. To specify which one you would like to receive, append .{FORMAT} to the end of the request URL. For example: https://api.perkville.com/v1/root.xml


Expanding Objects

Certain objects returned by the API can be expanded upon to provide more in-depth information about the object of interest. If this is the case for a particular resource endpoint, the "expand" query parameter will be documented in the "Query Parameters" section of the endpoint documentation below. If the "expand" query parameter is given, the additional information will show up in a "expanded" object within the returned response.


Errors

Perkville utilizes standard HTTP status codes to indicate the status of a request. Responses in the 200 range indicate a success. Errors in the 400 range indicate an error with the provided data, such as an invalid URL (404) or authorization failure (401). Errors in the 500 range indicate that something went wrong on our side.

When a request fails due to an error in the 400 range, a response in the following form is given.

{
  "status": "failure",
  "error_codes": [
    {
      "message": "Perk 34 does not exist",
      "code": "E003"
    }
  ],
  "errors": [
    "Perk 34 does not exist"
  ]
}
      

Below is a table indicating each of our error codes and their corresponding messages:

Error codeError message
E000Location {0} does not exist
E001Location {0} is not active
E002Location {0} does not belong to business {1}
E003Perk {0} does not exist
E004Perk {0} is not active
E005Perk {0} does not belong to Business {1}
E006Voucher {0} does not exist
E007Voucher {0} does not belong to Business {1}
E008Business {0} does not exist
E009Business {0} is not active
E010invalid email address {0}
E011User {0} does not exist
E012Unrecognized POS system for this API call.
E013Authorized user is not a staff of business
E014Authorized user is not a staff of business
E015No connection made with user
E016This business has exceeded its transaction limit.
E017This type of perk cannot be called using the API. This perk is only triggered by events directly on www.perkville.com.
E018Insufficient permissions
E019The user does not have a connection
E020The user does not have enough points ({bal}pts) to redeem the perk ({pts}pts x {qua}).
E021Insufficient permissions
E022email {0} had an error processing: {1}
E022email {0} had an error processing: The provided unique_id has already been used.
E023Not authorized to create empty customers
E024That email address is already in {0} reward program. Please check your points at www.perkville.com.
E025You are not a staff member of that business.
E026They cannot recommend them self.
E027They already recommended that person.
E028Only the recommender can write this information.
E029That person cannot recommend more than 500 people in one day.
E030You cannot recommend yourself.
E031Sorry, they are already a customer of the business.
E032You exeeded 1000 text limit. Please write something shorter.
E033You cannot recommended more than 500 people in one day.
E034This perk's points cannot be updated. This can only be managed directly on www.perkville.com.
E035Not authorized to view social postings
E036Date format is YYYY-MM-DD
E037Date format is YYYY-MM-DD
E038Authorized user has no ties to specified user
E039Authorized users can only look at connections for itself
E040Authorized users can only look at connections for itself
E041Authorized user is not a staff of business
E042Insufficient permissions
E043This perk's status cannot be updated. This can only be managed directly on www.perkville.com.
E044This perk's title cannot be updated. This can only be managed directly on www.perkville.com.
E045This perk's type cannot be updated. This can only be managed directly on www.perkville.com.
E046That email is deactivated on Perkville. They will need to contact [email protected] to register.
E047That email has notifications turned off. They will need to register at www.perkville.com.
E048Cannot create vouchers for this business
E049Perk {0} cannot be used with location {1}
E050Perk {0} cannot have locations, it is a business-level perk
E051Perk {0} must be a business-level perk because it is not a redeeming perk
E052Perk {0} is location-specific perk with no locations. Location-specific perks require at least one location.
E053We encountered an error while processing your request. Please try again later.
E054Only Standard EARN perks can have their `completes_referral` flag modified.
E055Only EARN perks can have `completes_referral` == True
E056You're not allowed to edit marketplace perks.
E057Customers can only be invited to businesses that have a registration bonus set up
E058Business {0} is not active, and its customers and transactions have been merged into Business {1}

Get Business Customers

GET /v1/business/{BUSINESS_ID}/connection/{USER_ID} Example
Example Request
curl https://api.perkville.com/v1/business/4065/connection/502.json?expand=1 -u [email protected]
Example Response
{
  "status": "success",
  "links": [
    "/v1/business/4065/location/6112",
    "/v1/user/502"
  ],
  "entity": {
    "status": "ACTIVE",
    "first_name": "Marty",
    "last_name": "Regan",
    "user_id": 502,
    "last_location": 6112,
    "balance": 4530,
    "email": "[email protected]"
  }
}
Returns customer connections to the relevant business

URL Parameters

name type required description
BUSINESS_ID integer True The perkville unique identifier of the business
USER_ID integer OR email False The perkville unique identifier of the user

Query Parameters

name type required description
expand boolean False If the expand argument is provided, the last location the user earned points at will be returned along with the normal details.

Returns

If USER_ID is left blank, this method will return a list of all of the customer connections at the relevant business. If USER_ID is provided, only the relevant customer connection will be returned.

Restrictions

The authenticated user must either be a staff member of the relevant business, or must be the user that is being requested. The user's first and last name will only be returned if the associated connection is in an "ACTIVE" state.


Create a New Transaction

POST /v1/business/{BUSINESS_ID}/connection Example
Example Request
curl https://api.perkville.com/v1/business/4065/connection.json -d "email=stephen%40example.com&location_id=6112&perk_id=64554&quantity=1" -u [email protected]
Example Response
{
  "status": "success",
  "error_codes": [],
  "balance": 20,
  "errors": [],
  "links": [
    "/v1/business/4065/connection/3743181"
  ]
}
Creates a transaction, allows a business to reward customers or redeem points. If the customer associated with the transaction does not exist in Perkville, create the customer, and send them a "warm registration" email prompting them to join the business' rewards program.

URL Parameters

name type required description
BUSINESS_ID integer True The perkville unique identifier of the business

Query Parameters

name type required description
user_id OR email integer OR string True The email OR user_id must be provided in order to identify the user the transaction belongs to
location_id OR external_location_id integer OR string True Perkville must somehow identify which location the transaction is taking place at. The location_id represents a Perkville generated Location ID. external_location_id represents an externally generated ID that has been associated with the location.
perk_id integer True The perkville ID of the perk to award the user
quantity integer True The quantity of the perk that is being granted (usually 1, unless the perk is a "for each dollar spent" type)
unique_id string False A unique identifier for the transaction being generated
transaction_dt datetime (2014-01-02 11:24:34) False The datetime that the transaction took place. Omit for current time.
first_name string False First name of the user the transaction belongs to
last_name string False Last name of the user the transaction belongs to
create_voucher boolean False If true and the transaction is generated from a Redeeming perk, creates a voucher for the transaction.

Returns

An object representing information about the applied transaction

Restrictions

The authenticated user must be a staff member of the applicable business


Get a Customer's Vouchers

GET /v1/business/{BUSINESS_ID}/connection/{USER_ID}/voucher/{VOUCHER_CODE} Example
Example Request
curl "https://api.perkville.com/v1/business/4065/connection/[email protected]/voucher.json?expand=TRUE" -u [email protected]
Example Response
{
  "status": "success",
  "expanded": {
    "6521825849": {
      "external_location_id": "",
      "location_name": "Perks Cove",
      "perk_id": 50863,
      "network_reward_url": null,
      "perk_fine_print": "Not redeemable on Saturdays",
      "voucher_status": "UNUSED",
      "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.",
      "points_deducted": 500,
      "external_coupon_code": "",
      "expire_date": "2014-12-13",
      "voucher_code": "6521825849",
      "location_id": 6112,
      "perk_title": "Free Class!"
    }
  },
  "links": [
    "/v1/business/4065/connection/3743181/voucher/6521825849"
  ]
}
Get redeemed vouchers applicable to a specific business and customer.

URL Parameters

name type required description
BUSINESS_ID integer True The ID of the business that the vouchers are applicable to
USER_ID integer OR email True The ID of the customer that the vouchers are applicable to
VOUCHER_CODE integer False If specified, only a single voucher will be returned. Else, all applicable vouchers will be returned.

Query Parameters

name type required description
expand If provided, each returned voucher object will include an "expanded" attribute which will contain additional information about the associated voucher.

Returns

A list of vouchers associated with the requested business and customer.

Restrictions

The authenticated user must either be the same user as the requested customer, or must be a staff member of the requested business.


Create a Customer

POST /v1/business/{BUSINESS_ID}/customer Example
Example Request
curl https://api.perkville.com/v1/business/4065/customer.json -d "email=stephen%40example.com&external_location_id=CaliforniaSales1" -u [email protected]
Example Response
{
  "status": "success",
  "links": [
    "/v1/business/4065/connection/3743181"
  ]
}
Adds a customer to a business and sends the customer an email requesting that they complete registration.

URL Parameters

name type required description
BUSINESS_ID integer True The perkville unique identifier of the business

Query Parameters

name type required description
email integer True The customer's email address
location_id integer False The perkville id of the business location the customer visits most frequently.
external_location_id string False The business' internal id of the business location the customer visits most frequently.
first_name string False The customer's first name
last_name string False The customer's last name

Returns

A link to the created customer object

Restrictions

The authenticated user must be an ADMIN of the applicable business


Get Business Locations

GET /v1/business/{BUSINESS_ID}/location/{LOCATION_ID} Example
Example Request
curl https://api.perkville.com/v1/business/4065/location/6112.json -u [email protected]
Example Response
{
  "status": "success",
  "entity": {
    "loc_postal_code": "94111",
    "ext_loc_id": null,
    "loc_phone": "(415)555-5555",
    "loc_state": "CA",
    "loc_address_2": "",
    "loc_name": "Perks Cove",
    "loc_city": "San Francisco",
    "loc_country": "us",
    "loc_id": 6112,
    "loc_address_1": "1 Embarcadero Ctr"
  }
}
Returns a list of locations for the requested business

URL Parameters

name type required description
BUSINESS_ID integer True The perkville unique identifier of the business
LOCATION_ID integer False The perkville unique identifier of the location.

Returns

If LOCATION_ID is left blank, this method will return links (not objects) to all of the active locations for the requested business. If LOCATION_ID is provided, the relevant location object will be returned.

Restrictions

The authenticated user MUST be a staff member of the requested business.


Create a Business Location

POST /v1/business/{BUSINESS_ID}/location Example
Example Request
curl https://api.perkville.com/v1/business/4065/location.json -d "loc_name=Headquarters&loc_address_1=555+Embarcadero+Ave." -u [email protected]
Example Response
{
  "status": "success",
  "links": [
    "/v1/business/4065/location/9372"
  ]
}
Creates a location

URL Parameters

name type required description
BUSINESS_ID integer True The perkville unique identifier of the business

Query Parameters

name type required description
loc_name string True Name of the primary location
loc_address_1 string False Street address of the primary location
loc_address_2 string False Street address (line 2) of the primary location
loc_city string False City of the primary location
loc_state string False State of the primary location
loc_postal_code string False Postal code of the primary location
loc_country string False Country of the primary location
loc_phone string False Phone number of the primary location
ext_loc_id string False External location id of the primary location

Returns

A link to the created location

Restrictions

Only Admins of the relevant business have access to this method


Get Business Perks

GET /v1/business/{BUSINESS_ID}/perk/{PERK_ID} Example
Example Request
curl "https://api.perkville.com/v1/business/4065/perk.json?perk_type=REDEEM&perk_status=ACTIVE&expand=TRUE" -u [email protected]
Example Response
{
  "status": "success",
  "expanded": {
    "perks": {
      "60568": {
        "perk_status": "ACTIVE",
        "perk_id": 60568,
        "locations": [
          [
            9372,
            "Headquarters",
            null
          ]
        ],
        "business_level_perk": false,
        "fine_print": "Only valid for non-discounted memberships",
        "can_connect": true,
        "points": 150,
        "perk_title": "$10 off membership",
        "external_coupon_code": "",
        "perk_type": "REDEEM",
        "perk_desc": "Next Month's",
        "completes_referral": false
      },
      "64424": {
        "perk_status": "ACTIVE",
        "perk_id": 64424,
        "locations": [],
        "business_level_perk": true,
        "fine_print": null,
        "can_connect": true,
        "points": 100,
        "perk_title": "Hug",
        "external_coupon_code": "",
        "perk_type": "REDEEM",
        "perk_desc": "",
        "completes_referral": false
      }
    }
  },
  "links": [
    "/v1/business/4065/perk/60568",
    "/v1/business/4065/perk/64424"
  ],
  "GET": {
    "perk_status": "enum(ACTIVE, INACTIVE) - limit results by the status of the perk",
    "perk_type": "enum(EARN, REDEEM) - limit results by the type of perk",
    "expand": "bool - get more information"
  }
}
Lists the active perks of a business. If the authenticated user is an admin of the business, returns inactive perks as well.

URL Parameters

name type required description
BUSINESS_ID integer True The perkville unique identifier of the business
PERK_ID integer False If provided, returns only the applicable perk. Else, returns all perks.

Query Parameters

name type required description
expand boolean False If set to TRUE, an "expanded" object will be returned with additional information about the perk links.
perk_type string False Can be either "EARN" or "REDEEM". The result set will be filtered by the provided value.
perk_status string False Can be either "ACTIVE" or "INACTIVE". The result set will be filtered by the provided value.

Returns

If PERK_ID is provided, a perk object is returned. Else, a list of perk links is returned which can be expanded with the expand query argument.

Restrictions

The authenticated user must be a staff member of the applicable business. Also, INACTIVE type perks are only returned for ADMIN employees.


Create an Earning or Redeeming Perk

POST /v1/business/{BUSINESS_ID}/perk Example
Example Request
curl https://api.perkville.com/v1/business/4065/perk.json -d "perk_type=EARN&perk_title=Take+a+spin+class&points=20" -u [email protected]
Example Response
{
  "status": "success",
  "links": [
    "/v1/business/4065/perk/64554"
  ]
}
Creates a perk for a business.

URL Parameters

name type required description
BUSINESS_ID integer True The perkville unique identifier of the business

Query Parameters

name type required description
perk_type string True The type of perk to be created. Can be either 'EARN' or 'REDEEM'
perk_title string True The name of the perk
perk_desc string False A more detailed description of the perk.
points integer True The number of points that can be earned for achieving this perk or taken away for redeeming.
external_coupon_code string False The business' internal identifier for this perk
business_level_perk boolean False If True, this perk is available at all of the business locations. Else, it's only available at specified locations.
locations integer array False If business_level_perk is False, this field describes which locations the perk is associated with
completes_referral boolean False 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 an EARN perk -- redeeming perks can never qualify as a referral-completing event. This defaults to True for EARN perks, and is always false for REDEEM perks.
fine_print string False Any specific rules that applies to the perk

Returns

A link to the created perk object

Restrictions

The authenticated user must be an ADMIN of the applicable business.


Update an Existing Perk

PUT /v1/business/{BUSINESS_ID}/perk/{PERK_ID} Example
Example Request
curl https://api.perkville.com/v1/business/4065/perk/64554.json -X PUT -d "perk_desc=You+will+have+the+time+of+your+life" -u [email protected]
Example Response
{
  "status": "success",
  "entity": {
    "perk_status": "ACTIVE",
    "perk_id": 64554,
    "locations": [],
    "business_level_perk": true,
    "points": 20,
    "perk_title": "Take a spin class",
    "external_coupon_code": "",
    "perk_type": "EARN",
    "perk_desc": "You will have the time of your life"
  }
}
Update an existing perk.

URL Parameters

name type required description
BUSINESS_ID integer True The perkville unique identifier of the business

Query Parameters

name type required description
perk_type string False The type of perk to be created. Can be either 'EARN' or 'REDEEM'
perk_title string False The name of the perk
perk_desc string False A more detailed description of the perk.
perk_status string False Can be set to either 'ACTIVE' or 'INACTIVE'. If INACTIVE, the perk will no longer be eligible for earning or redeeming.
points integer False The number of points that can be earned for achieving this perk or taken away for redeeming.
external_coupon_code string False The business' internal identifier for this perk
business_level_perk boolean False If True, this perk is available at all of the business locations. Else, it's only available at specified locations.
locations integer array False If business_level_perk is False, this field describes which locations the perk is associated with
completes_referral boolean False 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 should only be passed for an EARN perk -- redeeming perks can never qualify as a referral-completing event.
fine_print string False Any specific rules that applies to the perk

Returns

The updated perk object

Restrictions

The authenticated user must be an ADMIN of the applicable business.


Create a Recommendation

POST /v1/business/{BUSINESS_ID}/referral Example
Example Request
curl https://api.perkville.com/v1/business/4065/referral.json -d "recommendee_email=sophia%40example.com&recommender_email=marty%40example.com&external_location_id=CaliforniaSales1" -u [email protected]
Example Response
{
  "status": "success"
}
This endpoint will create a recommendation between two customers of the applicable business. If the emails are not associated with any customer, a new customer will be created and an email recommending the business will be sent to the recommendee. If the recommendee is already a customer of the business, points for a referral will be awarded to the recommender.

URL Parameters

name type required description
BUSINESS_ID integer True The perkville unique identifier of the business

Query Parameters

name type required description
recommendee_email email True The email address of the person who is being recommended to
location_id integer False The perkville id of the location the referral email should recommend visiting
external_location_id string False The business' internal id of the location the referral email should recommend visiting
content string False A personalized message to display inside the recommendation email
recommender_email email True The email address of the person who is making the recommendation
act_as_sender boolean False If Admin/Employee credentials are used for authentication. Set act_as_sender to true to send the recommendation as the user.

Returns

A success message upon successful creation of the recommendation

Restrictions

The authenticated user must either be a user associated with the recommender_email, or must be an EMPLOYEE or ADMIN of the applicable business.


Get Customer Social Postings

/v1/business/{BUSINESS_ID}/social Example
Example Request
curl https://api.perkville.com/v1/business/4065/social.json -u [email protected]
Example Response
TODO Get Stephen to generate some data for this
Gets Facebook and Twitter social media posts made by customers

URL Parameters

name type required description
BUSINESS_ID integer True The perkville unique identifier of the business

Query Parameters

name type required description
count integer False The number of social media postings to return. Must be between 1 and 20
min_content integer False The minimum number of characters contained in the posting
start date (YYYY-MM-DD format) False The oldest date to retrieve postings from
end date (YYYY-MM-DD format) False The newest date to retrieve postings from
recent boolean False If true, postings will be sorted from newest to oldest. If False, postings will be randomized.
user_id integer False The perkville customer id can be provided to show results only from that one user.
loc_id integer False If provided, only show social media postings from customers who earned at the provided location
network string False If provided, only show social media postings from the specified network. Can be either 'FACEBOOK' or 'TWITTER'

Returns

A list of the applicable social media posting objects

Restrictions

The authenticated user must be an ADMIN of the applicable business


Get All Business Vouchers

GET /v1/business/{BUSINESS_ID}/voucher/{VOUCHER_CODE} Example
Example Request
curl https://api.perkville.com/v1/business/4065/voucher.json -u [email protected]
Example Response
{
  "status": "success",
  "links": [
    "/v1/business/4065/voucher/2242488955",
    "/v1/business/4065/voucher/2329577490",
    "/v1/business/4065/voucher/2725794023",
    "/v1/business/4065/voucher/2906424523",
    "/v1/business/4065/voucher/2931221130",
    "/v1/business/4065/voucher/3097589448",
    "/v1/business/4065/voucher/3109058496",
    "/v1/business/4065/voucher/3810857426",
    "/v1/business/4065/voucher/3907227329",
    "/v1/business/4065/voucher/3928690662",
    "/v1/business/4065/voucher/3929675005",
    "/v1/business/4065/voucher/3957548150",
    "/v1/business/4065/voucher/3979119172",
    "/v1/business/4065/voucher/4020665882"
  ]
}
Return vouchers that have been created by customers for the applicable business.

URL Parameters

name type required description
BUSINESS_ID integer True The perkville unique identifier of the business
VOUCHER_CODE integer False If specified, only a single voucher will be returned. Else, all applicable vouchers will be returned.

Query Parameters

name type required description
voucher_status string False If provided, only returns vouchers of the specified status. Can be 'UNUSED', 'USED', 'EXPIRED', or 'CREDITED'

Returns

If VOUCHER_CODE is provided, returns a voucher object. Else, returns links to all the applicable vouchers.

Restrictions

The authorized user must be an EMPLOYEE or ADMIN of the applicable business.


Update a Voucher

PUT /v1/business/{BUSINESS_ID}/voucher/{VOUCHER_CODE} Example
Example Request
curl https://api.perkville.com/v1/business/4065/voucher/2242488955.json -X PUT -d "voucher_status=USED" -u [email protected]
Example Response
{
  "status": "success",
  "entity": {
    "voucher_status": "USED",
    "voucher_code": "2242488955",
    "user_id": 948345,
    "external_coupon_code": ""
  }
}
Update a voucher's status or external coupon code

URL Parameters

name type required description
BUSINESS_ID integer True The perkville unique identifier of the business
VOUCHER_CODE integer True The voucher's generated code

Query Parameters

name type required description
status string True May be 'USED' or 'UNUSED'
external_coupon_code string False If provided, update the voucher's external_coupon_code field.

Returns

The updated voucher object

Restrictions

The authorized user must be an EMPLOYEE or ADMIN of the applicable business.


Get User Connections

/v1/user/{USER_ID}/connection Example
Example Request
curl https://api.perkville.com/v1/user/[email protected]/connection.json -u [email protected]
Example Response
{
  "status": "success",
  "links": [
    "/v1/business/3/connection/3743181",
    "/v1/business/4065/connection/3743181"
  ]
}
Shows which businesses a specified user is a customer of.

URL Parameters

name type required description
USER_ID string False Can be either Perkville ID OR Email address.

Returns

A list of links to the applicable customer objects.

Restrictions

The authenticated user must be the same user as specified by the USER_ID.


Get Users

/v1/user/{USER_ID} Example
Example Request
curl https://api.perkville.com/v1/user/[email protected] -u [email protected]
Example Response
{
  "status": "success",
  "entity": {
    "user_id": 3743181,
    "email": "[email protected]"
  }
}
Returns users the authenticated user has access to.

URL Parameters

name type required description
USER_ID string False Can be either Perkville ID OR Email address. If provided, returns only the applicable user object. Else, returns links to all users who are customers of the business the authenticated user is a staff of.

Returns

If the USER_ID is provided, returns a user object. Else, returns a list of user links.

Restrictions

The returned user links will only be customers of the businesses the authenticated user is a staff of.


Get User Staff Connections

/v1/user/{USER_ID}/staff Example
Example Request
curl https://api.perkville.com/v1/user/[email protected]/staff.json -u [email protected]
Example Response
{
  "status": "success",
  "links": [
    "/v1/business/3"
  ]
}
Shows which businesses a specified user is a staff member of.

URL Parameters

name type required description
USER_ID string False Can be either Perkville ID OR Email address.

Returns

A list of links to the applicable business objects.

Restrictions

The authenticated user must be the same user as specified by the USER_ID.