PunchTab is dedicated to provide all the tools to build loyalty around your website, application or product. We are providing out-of-the-box solutions which does 80% of the work for you. But some of you want to have ways to integrate more tightly with your product. In order to accomplish this, we provide programmatic ways to use our platform.
Not everyone has the skills to build their own integration with PunchTab's API. The JS SDK is probably the simplest version of the tools we provide to extend our services. The REST API is for more advanced developers. We will let you judge what is the best way for you to integrate with your service.
Each developer is identified with a client_id, which youc an find on your developer page if you activated your account. To use the REST API, an access token(access_token) must be retrieved first using one of the user authentication methods given below.
In order to build loyalty into your application, you will need to identify and authenticate your loyal user. Currently users can be authenticated in our system using Single Sign-On(currently in BETA).
SSO allows your users who are already authenticated on your site, to seemlessly log in to our system automatically without having them to create an account with us and log in again. Please note currently you would need to contact us to enable your account for SSO. Given below are API's to support SSO:
User account will be created if it doesn't exist.
https://api.punchtab.com/v1/auth/sso
Parameters: (Only POST parameters are supported with HTTP Referer header set to your account domain URL[ex. http://mydomain.com])
base64_encode(json_encode([‘id’ => user[‘id’], ‘first_name’=>user[‘first_name'], ‘last_name’=>user[‘last_name'], 'email'=>user['email']), 'avatar_link'=>user['avatar_link']));
id – Unique user id associated with the user account
first_name – user first name
last_name –user last name
email(optional) – user email
avatar_link(optional) - http(s) link to user avatar image (Only JPEG/GIF/PNG image format of 50x50 and less than 1MB is supported)
country_code(optional) - user country provided as ISO 3166-1 alpha-2 based two-letter country code. Any invalid values would be ignored.
All the above field values must be passed as string
HMAC_SHA1(secret_key, auth_request + ‘ ‘ + timestamp)
secret_key – Secret key from your developer page
Response: (JSON formatted except for standard HTTP response)
Example:
{
status: ‘connected’,
authResponse: {
accessToken: ‘…..’
}
}
Example:
{
status: ‘disconnected’,
error: {
description: ‘signature mismatch’
}
}
Examples: Given below are examples in different languages on how to generate parameters for SSO API. You can use any libraries such as curl to make the REST API call by passing these parameters. Remember to set HTTP header 'referer' to your registered domain name when you make the API call.
<?php
define ('PUNCHTAB_CLIENT_ID', 'your_client_id'); //client_id
define ('PUNCHTAB_SECRET_KEY', 'your_secret_key');
define ('PUNCHTAB_ACCESS_KEY', 'your_access_key'); //key
$user = array('id' => '2', 'first_name' => 'John', 'last_name' => 'Doe', 'email' => 'john.doe@johndoe.com', 'avatar_link' => 'http://johndoe.com/johndoe.jpg');
$auth_request = base64_encode(json_encode($user));
$timestamp=time();
$signature = hash_hmac('sha1', "$auth_request $timestamp", PUNCHTAB_SECRET_KEY);
?>
import base64
import hashlib
import hmac
import simplejson
import time
PUNCHTAB_CLIENT_ID = 'your_client_id' #client_id
PUNCHTAB_SECRET_KEY = 'your_secret_key'
PUNCHTAB_ACCESS_KEY = 'your_access_key' #key
user = simplejson.dumps({'id': '2', 'first_name': 'John', 'last_name': 'Doe', 'email': 'john.doe@johndoe.com', 'avatar_link': 'http://johndoe.com/johndoe.jpg'})
auth_request = base64.b64encode(user)
timestamp = int(time.time())
signature = hmac.HMAC(PUNCHTAB_SECRET_KEY, '%s %s' % (auth_request, timestamp), hashlib.sha1).hexdigest()
SSO on client side using JavaScript
<script type="text/javascript" charset="utf-8">>
var _pt_pre_config = {
auth_request: <generated auth request>,
signature: <generated signature>,
timestamp: <signature timestamp>,
client_id: <your client id>
};
</script>
https://api.punchtab.com/v1/auth/logout
Parameters: (Both GET/POST parameters are supported with HTTP_REFERRER set to your account domain name)
Response: (JSON formatted except for standard HTTP response)
https://api.punchtab.com/v1/auth/status
Parameters: (Both GET/POST parameters are supported with HTTP_REFERRER set to your account domain name)
Response: (JSON formatted except for standard HTTP response)
We are rate limitting our API to ensure smooth service for the whole platform. Contact us if you expect a high number of API hits in a short period of time.
We support two output formats: JSON & JSONP
This is the output format by default. You don't need to specify anything and you will be return JavaScript Object Notation (JSON).
This format allow JavaScript developer to work-around the "Same-Origin Policy" restriction. You need to add a callback function to be returned JSONP.
https://api.punchtab.com/v1/activity?access_token=[access_token]&callback=my_function
The response of your call will be padded with the my_function() call. The original response of the API will be the argument of the function call.
We use the HTTP protocol to communicate with the API, and the method are used to denote actions against resources
So far we use the following methods:
Activities are the actions which make users earn points.
You can retrieve the activities of a user and you can also create activity for a user.
To read the activities of a user you need:
Example:
https://api.punchtab.com/v1/activity[/activity_name]?access_token=[access_token]
Fields:
To create the activities for a user you need:
Example: You need to create a POST request which will look like this:
curl -X POST -d "points=200" "https://api.punchtab.com/v1/activity/[activity_name]?access_token=[access_token]
Redeeming an offer (from the catalog) is another activity, you just need to specify the reward_id that you get from the reward's list
curl -X POST -d "reward_id=123" https://api.punchtab.com/v1/activity/redeem?access_token=[access_token]
Leaderboard is the list of user ranked by the descending number of points for you application/site. You can only retrieve the leaderboard, it gets updated each time a user get points through the activity resource.
Reading the leaderboard for an application:
Example:
https://api.punchtab.com/v1/leaderboard?access_token=[access_token][&with=me][&days=all][&limit=N][&page=M]
Fields:
Reward is the list of items you have available for the users to redeem in your catalog. You can currently only retrieve the catalog, you can edit it on punchtab.com
To read the rewards you need:
Example:
https://api.punchtab.com/v1/reward?access_token=[access_token]
Fields:
User represent a person who connected with your loyalty program.
To read the user information you need:
Example:
https://api.punchtab.com/v1/user?access_token=[access_token]
Fields: