Perkville Version 1 API

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:

Get Business Customers

curl https://api.perkville.com/v1/business/4065/connection/502.json?expand=1 -u staff@example.org

{
  "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": "marty@example.org"
  }
}

URL Parameters

Query Parameters

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

curl https://api.perkville.com/v1/business/4065/connection.json -d "email=stephen%40example.com&location_id=6112&perk_id=64554&quantity=1" -u employee@example.org

{
  "status": "success",
  "error_codes": [],
  "balance": 20,
  "errors": [],
  "links": [
    "/v1/business/4065/connection/3743181"
  ]
}

URL Parameters

Query Parameters

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

curl "https://api.perkville.com/v1/business/4065/connection/stephen@example.com/voucher.json?expand=TRUE" -u employee@example.org

{
  "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"
  ]
}

URL Parameters

Query Parameters

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

curl https://api.perkville.com/v1/business/4065/customer.json -d "email=stephen%40example.com&external_location_id=CaliforniaSales1" -u admin@example.org

{
  "status": "success",
  "links": [
    "/v1/business/4065/connection/3743181"
  ]
}

URL Parameters

Query Parameters

Returns

A link to the created customer object

Restrictions

The authenticated user must be an ADMIN of the applicable business

Get Business Locations

curl https://api.perkville.com/v1/business/4065/location/6112.json -u staff@example.org

{
  "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"
  }
}

URL Parameters

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

curl https://api.perkville.com/v1/business/4065/location.json -d "loc_name=Headquarters&loc_address_1=555+Embarcadero+Ave." -u admin@example.org

{
  "status": "success",
  "links": [
    "/v1/business/4065/location/9372"
  ]
}

URL Parameters

Query Parameters

Returns

A link to the created location

Restrictions

Only Admins of the relevant business have access to this method

Get Business Perks

curl "https://api.perkville.com/v1/business/4065/perk.json?perk_type=REDEEM&perk_status=ACTIVE&expand=TRUE" -u employee@example.org

{
  "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"
  }
}

URL Parameters

Query Parameters

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

curl https://api.perkville.com/v1/business/4065/perk.json -d "perk_type=EARN&perk_title=Take+a+spin+class&points=20" -u employee@example.org

{
  "status": "success",
  "links": [
    "/v1/business/4065/perk/64554"
  ]
}

URL Parameters

Query Parameters

Returns

A link to the created perk object

Restrictions

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

Update an Existing Perk

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 employee@example.org

{
  "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"
  }
}

URL Parameters

Query Parameters

Returns

The updated perk object

Restrictions

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

Create a Recommendation

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 employee@example.org

{
  "status": "success"
}

URL Parameters

Query Parameters

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

curl https://api.perkville.com/v1/business/4065/social.json -u employee@example.org

TODO Get Stephen to generate some data for this

URL Parameters

Query Parameters

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

curl https://api.perkville.com/v1/business/4065/voucher.json -u employee@example.org

{
  "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"
  ]
}

URL Parameters

Query Parameters

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

curl https://api.perkville.com/v1/business/4065/voucher/2242488955.json -X PUT -d "voucher_status=USED" -u employee@example.org

{
  "status": "success",
  "entity": {
    "voucher_status": "USED",
    "voucher_code": "2242488955",
    "user_id": 948345,
    "external_coupon_code": ""
  }
}

URL Parameters

Query Parameters

Returns

The updated voucher object

Restrictions

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

Get User Connections

curl https://api.perkville.com/v1/user/stephen@example.com/connection.json -u stephen@example.com

{
  "status": "success",
  "links": [
    "/v1/business/3/connection/3743181",
    "/v1/business/4065/connection/3743181"
  ]
}

URL Parameters

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

curl https://api.perkville.com/v1/user/stephen@example.com.json -u employee@example.org

{
  "status": "success",
  "entity": {
    "user_id": 3743181,
    "email": "stephen@example.com"
  }
}

URL Parameters

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

curl https://api.perkville.com/v1/user/stephen@example.com/staff.json -u stephen@example.com

{
  "status": "success",
  "links": [
    "/v1/business/3"
  ]
}

URL Parameters

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.