Overview
Coupontools API: simple & powerful
Connect our Coupontools platform with your apps or web projects. The Coupontools REST API allows you to query metadata about your account, campaigns, validations, usage data, and many more. Use the Coupontools API to integrate coupons directly into your website or app. Coupontools and your app will communicate by sending HTTP requests back and forth.
This page provides an overview of the Coupontools API. The topics in this chapter deal with several specific aspects of the API.
If you have any questions about integrating our API, don't hesitate to get in touch with us. We are happy to help!
Definitions
Coupon
A coupon is the layout/settings for one campaign for one business. Our platform generates and assigns a unique URL for each coupon in order to distinguish between different coupons. Example coupon URL: https://digicpn.com/p/vuhykb where "vuhykb" is the unique identifier for the coupon. When shared between consumers, each consumer will get a unique coupon (= coupon session).
Coupon session
Every consumer who opens or receives a coupon will have a unique URL assigned. When opening a coupon URL (f.e. https://digicpn.com/p/vuhykb), the system will automatically generate a unique coupon session and append it to the back of the URL. Example coupon session URL: https://digicpn.com/p/vuhykb/ac6s7u3g8a25ja7x9qg87 where "ac6s7u3g8a25ja7x9qg87" is the unique coupon session. When shared between consumers, each consumer will get the same coupon session. Meaning if one consumer validates the coupon, no one else can validate it again.
Directory
An application to group multiple coupons and loyalty cards for mobile apps, websites, touch TVs, Facebook tabs. Directories can require authentication or payments in order to access the coupons inside.
Loyalty card
A loyalty card is a card where consumers can earn and redeem points/stamps in order to receive coupons. Configure the number of points/stamps for each reward (coupon) in your Coupontools dashboard.
ID overview
| cam_xxxxxx | Coupon ID | Unique reference for a coupon |
| loc_xxxxxx | Coupon redeem location ID | Unique reference for a coupon redeem location |
| xxxxxx | Directory ID | Unique reference for a directory |
| xxxxxx | Directory user ID | Unique reference for a directory user |
| dir_xxxxxx | Legacy directory ID | Unique reference for a legacy directory |
| reg_xxxxxx | Legacy directory user ID | Unique reference for a legacy directory user |
| cat_xxxxxx | Legacy directory category ID | Unique reference for a legacy directory category |
| xxxxxx | Wallet loyalty card ID | Unique reference for a wallet-based loyalty card |
| xxxxxx | Wallet loyalty card user ID | Unique reference for a wallet-based loyalty card. Alternatively called a stat ID. |
| loy_xxxxxx | Web loyalty card ID | Unique reference for a web-based loyalty card |
| lus_xxxxxx | Web loyalty card user ID | Unique reference for a web-based loyalty card user |
| lloc_xxxxxx | Web loyalty card redeem location ID | Unique reference for a web-based loyalty card redeem location |
| sub_xxxxxx | Subaccount ID | Unique reference for a subaccount |
| gro_xxxxxx | Smstools group ID | Unique reference for a Smstools group |
| con_xxxxxx | Smstools contact ID | Unique reference for a Smstools contact |
Authentication
The API client ID and secret must be sent along with each API request by providing it in the HTTP call's Authorization header. Your API credentials can be found under the "REST API" integration on the "Integrations" page in your Coupontools dashboard. Of course, it's very important to keep the API keys secure. Do not ever share them!
Request headers
| X-Client-Id | Login to your account to get your API keys |
| X-Client-Secret | Login to your account to get your API keys |
API of more recent products like the version 4 directories and wallet based loyalty cards use different headers to send along their API credentials.
| x-api-key | Login to your account to get your API keys |
| x-api-secret | Login to your account to get your API keys |
Webhooks
Use webhooks to be notified about events that happen in a Coupontools account.
Webhooks are a system of automated notifications indicating that an event has occurred in your account. Rather than requiring you to pull information via our API, webhooks push information to your destination when important events occur.
Notifications are delivered via HTTP POST to a destination endpoint on your server and are sent based on the triggers you choose. Each webhook contains a notification kind and the full Coupontools object that the notification is reporting on. This information can be used to update your system or to trigger business processes.
Configuration
To configure a webhook, you'll need to:
- Create a webhook destination URL on your server
- Create a new webhook in the Control Panel by entering your webhook destination URL and selecting at least one type of notification for the webhook to fire on
- Set up your server to parse incoming webhooks
- Test your webhook handling code
Verification
Coupontools generates a signatures for each webhook using a hash-based message authentication code (HMAC) with SHA-256 as its hash function. Your API secret key will be used as the shared secret when generating the HMAC.
To verify the HMAC you'll need to:
- Compute an HMAC of the JSON payload using the SHA256 hash function and your API secret key
- Compare the computed HMAC to the HMAC received in the "x-hmac" header of the webhook request
Retries
We will resend webhook notifications every hour for up to 24 hours until both of the following are true:
- The webhook responds within 30 seconds
- The webhook responds with a successful HTTP response code. (i.e. 2xx)