Perks Endpoints
List Perks
File: api/perks.php
Method: POST
Auth: Required JWT (POST body)
| Param | Type | Description |
|---|---|---|
jwt | string | User JWT |
housr_plus | string | If set, filters to Housr Plus (gold) deals only |
limit | int | Optional result limit |
Returns perks available to the user based on their city. Complex filtering logic:
- City-scoped (user’s city or “National”)
- Status filtering:
approvedfor regular users;approvedorpendingfor Housr internal users (email ending inhousrapp.co.uk,myhousr.com, orhousr.com) - Perk types 0-4 always shown; type 10 (code-based) shown only if unused codes exist
- Respects expiry dates
- Single-use perks hidden if already redeemed by user
- Exclusive perks shown only to designated users
- Redemption limit enforcement
- Sorted by
display_order
Each perk includes: company, description, instructions, images, deal text, gold deal text, type, link, QR link, redeem code, category, background colour, expiry, redemption stats, map highlight ID, Housr-only flag, hero flag, subscription tier, and wallet token status.
Perk Categories
File: api/perkCategories.php
Method: POST
Returns perk category definitions.
External Perk Categories
File: api/external/perkCategories.php
Method: POST
External-facing perk categories endpoint.
Featured Perks
File: api/featuredPerks.php
Method: POST
Returns featured/highlighted perks.
Perk of the Week
File: api/perkOfTheWeek.php
Method: POST
Returns the current perk of the week.
Search Perks
File: api/searchPerks.php
Method: POST
Auth: Required JWT
Searches perks by text query.
Redeem Perk
File: api/redeemPerk.php
Method: POST
Auth: Required JWT
Records a perk redemption. Inserts into perks_redeemed table.
Redeem Perk Code
File: api/redeemPerkCode.php
Method: POST
Auth: Required JWT
Redeems a unique perk code. Assigns the code to the user from the perk_codes pool.
Perks Entry
File: api/perksEntry.php
Method: POST
Auth: Required JWT
Handles perk entry (for competition/raffle-style perks).
Perks Tracker
File: api/perksTracker.php
Method: POST
Tracks perk interaction/views.
External Perks
File: api/external/perks.php
Method: POST
External-facing perks listing.
External Perks Tracker
File: api/external/perksTracker.php
Method: POST
External perk tracking.
External Perks Most Viewed
File: api/external/perksMostViewed.php
Method: POST
Returns most viewed perks for external consumers.
External Perk Redeem Routes
File: api/external/perkRedeemRoutes.php
Method: POST
Returns perk redemption routes for external consumers.
Tokens
File: api/tokens.php
Method: POST
Auth: Required JWT
Returns perk tokens in the user’s wallet.
Token Redeemed
File: api/tokenRedeemed.php
Method: POST
Auth: Required JWT
Marks a perk token as redeemed.
Weekly Token Redeemed
File: api/weeklyTokenRedeemed.php
Method: POST
Auth: Required JWT
Handles weekly token redemption tracking.
Ticket QR Code
File: api/ticketQRCode.php
Method: POST
Generates a QR code for a perk ticket.
Ticket Redeemed Check
File: api/ticketRedeemedCheck.php
Method: POST
Checks if a ticket has been redeemed.
Submit QR Code
File: api/submitQRCode.php
Method: POST
Submits/validates a scanned QR code.
Map Highlights
File: api/mapHighlights.php
Method: POST
Returns map highlight points (perk partner locations).
Get Map Highlight by Perk ID
File: api/getMapHighlightByPerkId.php
Method: POST
Returns the map highlight associated with a specific perk.
Update Perk Type
File: api/updatePerkType.php
Method: POST
Updates a perk’s type. Used for admin management.