Make Your First Mobile API Call

Overview

You can call APIs using any suitable API test client. In the following sections, we use Postman to invoke the Punchh APIs. The response to every API call made in Postman under a chosen environment (in app and/or platform) is reflected in the app and/or platform.

Base URIs

Please reach out to your Punchh representative to receive the sandbox and production base URLs that you should be using to consume the Punchh APIs.

Step 1: Get Client and Secret

The following parameters are required in all API calls:

client: A string that identifies a particular business
secret: It is optional to pass the secret in the body of the API call, but it must be set in the settings of the environment (production/testing) before invoking any API.
x-pch-digest: A signature placed in the header section of every API call. It is generated via a secure signature generating algorithm, as described in the following section.
punchh-app-device-id: The app device ID helps Punchh identify each device so that certain rewards can be awarded individually to each device instead of per user. For example, the sign-up reward is given to each device ID to prevent fraudulent sign-ups so that a user cannot do repeated sign-ups from a single device to get rewards. It should not change even if the user resets a device. See the sample code to generate the punchh-app-device-id header.

For every business, values are different for the client and secret parameters.

Step 2: Generate Signature

You can use SHA256 (Secure Hash Algorithm) to generate a secure signature. Copy and paste the following function into the 'pre-request script' section of Postman. This function uses the secret parameter value to generate a secure signature.

Text
var index = request.url.indexOf('/api2/');
var uri_path = request.url.substring(index);
var payload;
if(_.isEmpty(request.data)){
    payload = uri_path;
}else{
    payload = uri_path + request.data;   
}
console.log("Using payload as " + payload)
var hash = CryptoJS.HmacSHA256(payload, environment.secret);
var hashInBase64 = CryptoJS.enc.Hex.stringify(hash);
postman.setGlobalVariable("signature", hashInBase64);

Function To Generate Signature

The function can be implemented in any language of your choice. For reference, we provide implementations for generating x-pch-digest header in commonly used languages.

Now place the x-pch-digest parameter in the headers section along with other parameters. In place of its value, type {{signature}} so that this fetches the signature received from the pre-request function.

The signature is generated when you click the send button in Postman, and it goes along with other parameters as a significant element of the API call.

Step 3: Make the Request

Following is an example request for the sign-up user API call, which registers a user's profile in the Punchh server. It is invoked when a user presses the Submit button after entering profile information in the sign-up section of the app. The app then makes the sign-up API call to the Punchh server. The sign-up API requires the following parameters for a successful (yet incomplete) request:

client, email, and password

With headers, HTTP request method, endpoint, and function to generate the signature in place, you can now begin to invoke the Punchh API.

An example sign-up API request in cURL is provided below.

$ curl {{base-url}}/api2/mobile/users
-H "Content-Type:application/json" \
-H "Accept: application/json" \
-H "Accept-Language:en"
-H "x-pch-digest":"SIGNATURE_GOES_HERE"  \
-X POST \
-d '{  
   "client":"CLIENT_GOES_HERE",
   "email":"test@example.com",
   "password":"PASSWORD_GOES_HERE",
   "first_name": ""
}'

On success, Punchh returns the following JSON response.

{
    "access_token": {
        "token": "ACCESS_TOKEN_GOES_HERE",
        "seconds_to_expire": null,
        "revoked_at": null,
        "refresh_token": "REFRESH_TOKEN_GOES_HERE",
        "scopes": []
    },
    "user": {
        "address": null,
        "anniversary": null,
        "avatar_remote_url": null,
        "birthday": "1999-01-01",
        "city": null,
        "communicable_email": "test@example.com",
        "created_at": "2019-12-18T02:18:31+00:00",
        "email": "test@example.com",
        "email_verified": false,
        "facebook_signup": null,
        "apple_signup": null,
        "apple_uid": null,
        "favourite_location_ids": "",
        "favourite_store_numbers": "",
        "fb_uid": null,
        "first_name": "",
        "gender": null,
        "has_generated_fb_email": false,
        "last_name": null,
        "marketing_email_subscription": false,
        "marketing_pn_subscription": false,
        "migrate_status": false,
        "passcode_configured_for_giftcards": false,
        "phone": null,
        "profile_field_answers": {},
        "referral_code": "REFERRAL_CODE_GOES_HERE",
        "referral_path": "URL_GOES_HERE",
        "secondary_email": null,
        "state": null,
        "superuser": false,
        "terms_and_conditions": true,
        "title": null,
        "updated_at": "2019-12-18T02:18:31+00:00",
        "user_as_qrcode": "QR_CODE_GOES_HERE",
        "user_code": "P11111111",
        "user_id": 111111111,
        "preferred_locale": null,
        "user_relations": [],
        "zip_code": null,
        "verification_mode": null,
        "sms_subscription": false
    }
}

For details, see the Sign up / Register API.

Getting Started With Mobile API Integrations

Punchh Wallet