Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Mobile Notifications API
version: '1.0'
contact:
name: Punchh Dev Support
url: https://developers.punchh.com
description: 'Punchh provides a robust platform for offering loyalty programs to customers. When a business integrates its back-end with the Punchh server, the Punchh APIs become instrumental in executing loyalty programs for enrolled customers, primarily via business-branded mobile apps and websites tailored by Punchh.
To establish integration with the Punchh APIs, you need to understand how they are invoked and what responses are returned by the Punchh server. You can call APIs using any suitable API test client, such as Postman. Thus, 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.'
servers:
- url: https://SERVER_NAME_GOES_HERE.punchh.com
tags:
- name: Notifications
paths:
/api2/mobile/notifications:
get:
responses:
'200':
description: ''
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: integer
description: 'ID of the notification
'
format: int64
kind:
type: string
description: 'Type of notification. There are three types of notifications that a user can receive: ''system'', ''campaign'', or ''news''.
'
message:
type: string
description: 'Message sent to the user in the notification
'
created_at:
type: string
description: 'Date/time when the notification was created in the system, in ISO 8601 format
'
enum:
- YYYY-MM-DDThh:mm:ssZ
format: date-time
read_at:
type: string
description: 'Date/time when the notification was read by the user from the user''s device, in ISO 8601 format
'
enum:
- YYYY-MM-DDThh:mm:ssZ
format: date-time
user_survey_id:
type: integer
description: 'ID of the attached survey. For details, see [Fetch User Survey API](/docs/dev-portal-mobile/apis/mobile-api/paths/~1api2~1mobile~1survey_details/get).
'
examples:
default:
value:
- id: 22240773
kind: system
message: Something to cheer you up!!
created_at: '2016-03-30T01:50:13-05:00'
read_at: null
user_survey_id: null
- id: 22240649
kind: campaign
message: Thanks for signing up for the Club. Enjoy your first 25 points on us!
created_at: '2016-03-29T01:38:28-05:00'
read_at: null
user_survey_id: null
- id: 22240545
kind: system
message: Thank you for signing up for the Wing Bar. You will receive 25 free points in 24 hours.
created_at: '2016-03-28T01:38:34-05:00'
read_at: null
user_survey_id: null
'400':
description: ''
content:
application/json:
schema:
type: object
properties:
errors:
type: object
properties:
invalid_language:
type: array
items:
type: string
examples:
Bad Request (invalid language):
value: "{\n \"errors\": {\n \"invalid_language\": [\n \"Unknown/Invalid locale in Accept-Language Header. Supported locales are en-GB, es-CR, en, es.\"\n ]\n }\n}"
Bad request (invalid quantity):
value: "{ \n \"errors\":{ \n \"qty\":\"Number of Notifications should be greater than zero. '-1' is zero, Blank or non-integer value\"\n }\n}"
'401':
description: ''
content:
application/json:
schema:
type: object
properties:
errors:
type: object
properties:
unknown_client:
type: array
items:
type: string
examples:
default:
value:
errors:
unknown_client:
- Client ID is incorrect. Please check client param or contact us.
'403':
description: ''
content:
application/json:
schema:
type: object
properties:
errors:
type: object
properties:
invalid_access_token:
type: array
items:
type: string
examples:
default:
value:
errors:
invalid_access_token:
- 'Error: access_token not found or is incorrect! Valid access_token of the user required'
'412':
description: ''
content:
application/json:
schema:
type: object
properties:
errors:
type: object
properties:
invalid_signature:
type: array
items:
type: string
examples:
default:
value:
errors:
invalid_signature:
- Signature doesn't match. See [this topic](/docs/dev-portal-mobile/17c2f8eb39142-generating-x-pch-digest-header-for-mobile-ap-is)
summary: Fetch User Notifications
description: 'Returns the details of notifications received by a user
For more information about push notifications and payload based on different types of notifications, including platform configurations required to enable push notifications, see [Push Notifications](/docs/dev-portal-mobile/additional-topics/notifications-push).
Also, see [Notifications and Badges Count](/docs/dev-portal-mobile/additional-topics/notifications-badgecounts) for information about various use cases and best practices.'
operationId: mobile_fetch_user_notifications
tags:
- Notifications
parameters:
- $ref: '#/components/parameters/signature'
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/Accept-Language'
- $ref: '#/components/parameters/Authorization'
- $ref: '#/components/parameters/Content-Type'
- $ref: '#/components/parameters/User-Agent'
x-stoplight:
id: 0285fe645c89d
requestBody:
content:
application/json:
schema:
type: object
properties:
client:
type: string
description: 'OAuth client ID provided by the business
'
qty:
type: string
description: 'Number of notifications for which the details are required. By default, a maximum of 10 notifications are returned at once in order of recency.
'
required:
- client
examples:
default:
value:
client: CLIENT_GOES_HERE
qty: '3'
/api2/mobile/notifications/id:
delete:
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties: {}
summary: Delete User Notification
description: 'Deletes a notification received by a user
'
operationId: mobile_delete_user_notification
tags:
- Notifications
parameters:
- $ref: '#/components/parameters/Content-Type'
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/signature'
- $ref: '#/components/parameters/Accept-Language'
- $ref: '#/components/parameters/Authorization'
- schema:
type: string
in: path
name: id
required: true
description: ID of the notification to be deleted
- $ref: '#/components/parameters/User-Agent'
x-stoplight:
id: 507f773849cef
requestBody:
content:
application/json:
schema:
type: object
properties:
client:
type: string
description: 'OAuth client ID provided by the business
'
required:
- client
/api2/mobile/messages:
get:
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/messages'
examples:
default:
value:
messages:
- background_content:
type: image
url: IMAGE_URL
alt_text: Black Background Image
initial_frame: ''
body: A new gastronomical experience awaits you as we launch the Double Hamburger. Juicy handmade patties treated with a gravy bath and accompanied by shredded lettuce, tomato, pickle, bulky chopped onion, mustard, and mayo.
cta:
- type: external_web_link
link: https://punchh.com
label: More Details
cta_type: primary
- type: external_web_link
link: https://punchh.com
label: Terms & Conditions
cta_type: secondary
dismissable: true
hero_content:
type: image
url: IMAGE_URL
alt_text: Double Hamburger
initial_frame: ''
launch_time: '2017-08-14T06:00:00+00:00'
message_type: business_wide
rank: 500
style_url: URL_OF_THE_STYLE_SHEET
subtitle: Double the fun!
tags:
- business_announcement
- menu_extension
- recurring
take_down_time: '2017-08-15T06:00:00+00:00'
title: Introducing Double Hamburger
read_at: '2024-08-19T15:31:28-07:00'
created_at: '2024-08-19T15:30:27-07:00'
message_id: 7491710585
deleted_at: '2024-08-20T15:30:27-07:00'
summary: Fetch Messages
description: 'Fetches the list of rich messages available for a user
Apart from the API response mentioned here, the mobile client will have to fetch the style JSON directly from S3 (Amazon Cloud Storage), which defines how to render the rich message.
For details, see [Style JSON for Rich Messages](/docs/dev-portal-mobile/additional-topics/style-json-for-rich-messages).'
operationId: mobile_messages
tags:
- Notifications
parameters:
- $ref: '#/components/parameters/Content-Type'
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/Accept-Language'
- $ref: '#/components/parameters/signature'
- $ref: '#/components/parameters/Authorization'
- $ref: '#/components/parameters/User-Agent'
x-stoplight:
id: e9485ca96ff55
requestBody:
content:
application/json:
schema:
type: object
properties:
client:
type: string
description: 'OAuth client ID provided by the business
'
required:
- client
examples:
default:
value:
client: CLIENT_GOES_HERE
/api2/mobile/message_readerships:
post:
responses:
'202':
description: ''
content:
application/json:
schema:
type: object
properties: {}
'400':
description: ''
content:
application/json:
schema:
type: object
properties:
errors:
type: object
properties:
client:
type: string
examples:
default:
value:
errors:
client: Required parameter missing or the value is empty.
'401':
description: ''
content:
application/json:
schema:
type: object
properties:
errors:
type: object
properties:
unauthorized:
type: array
items:
type: string
examples:
default:
value:
errors:
unauthorized:
- An active access token must be used to query information about the current user.
summary: Mark Messages As Read
description: 'Rich messages of type `user_specific` can be marked as read by making this request.
'
operationId: mobile_mark_messages_read
tags:
- Notifications
parameters:
- $ref: '#/components/parameters/Accept-Language'
- $ref: '#/components/parameters/Content-Type'
- $ref: '#/components/parameters/signature'
- $ref: '#/components/parameters/Authorization'
- $ref: '#/components/parameters/User-Agent'
x-stoplight:
id: 899a3394bf4e6
requestBody:
content:
application/json:
schema:
type: object
properties:
user_rich_notifications:
type: string
description: 'Comma-separated values of multiple messages that will be marked as read
'
client:
type: string
x-stoplight:
id: jpbcmandbq4y1
description: OAuth client ID provided by the business
required:
- client
examples:
default:
value:
user_rich_notifications: '821'
client: CLIENT_GOES_HERE
/api2/mobile/message_readerships/{message_id}:
delete:
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties: {}
'400':
description: ''
content:
application/json:
schema:
type: object
properties:
errors:
type: object
properties:
client:
type: string
examples:
default:
value:
errors:
client: Required parameter missing or the value is empty.
'401':
description: ''
content:
application/json:
schema:
type: object
properties:
errors:
type: object
properties:
unauthorized:
type: array
items:
type: string
examples:
default:
value:
errors:
unauthorized:
- An active access token must be used to query information about the current user.
summary: Delete Messages
description: 'Rich messages of type `user_specific` can be deleted by making this request.
'
operationId: mobile_delete_messages
tags:
- Notifications
parameters:
- $ref: '#/components/parameters/Accept-Language'
- $ref: '#/components/parameters/Content-Type'
- $ref: '#/components/parameters/signature'
- $ref: '#/components/parameters/Authorization'
- schema:
type: string
in: path
name: message_id
required: true
description: ID of the `user_specific` message that will be deleted
- $ref: '#/components/parameters/User-Agent'
x-stoplight:
id: 8dbb3bf79ad94
requestBody:
content:
application/json:
schema:
type: object
properties:
client:
type: string
x-stoplight:
id: 9il3bfrot8dnr
description: OAuth client ID provided by the business
required:
- client
examples:
default:
value:
client: CLIENT_GOES_HERE
components:
parameters:
signature:
schema:
type: string
default: '{{$$.env.signature}}'
name: x-pch-digest
in: header
description: The [signature](/docs/dev-portal-mobile/additional-topics/signature-sha256) for the API call
required: true
User-Agent:
schema:
type: string
default: AppName/AppVersion/BuildNumber (OS; Model; MANUFACTURER; MODEL; OS Version)
in: header
name: User-Agent
description: Used to identify the software, device, and application initiating the request, providing information about the client to the server. For details, see [User Agent](/docs/dev-portal-mobile/additional-topics/user-agent).
required: true
Accept-Language:
schema:
type: string
default: en
name: Accept-Language
in: header
description: Preferred language
Content-Type:
schema:
type: string
default: application/json
name: Content-Type
in: header
description: Set this header to <b>application/json</b>.
required: true
Accept:
schema:
type: string
default: application/json
name: Accept
in: header
description: Advertises which content types the client is able to understand
required: true
Authorization:
schema:
type: string
default: Bearer ACCESS_TOKEN_GOES_HERE
name: Authorization
in: header
description: Used to authorize the request with access_token. It should be supplied as `Bearer ACCESS_TOKEN_GOES_HERE`.
required: true
schemas:
cta:
type: array
items:
type: object
properties:
type:
type: string
description: 'Three possible values can be returned to the mobile client:
- web_link: The CTA button prompts the user to open the link in a web browser available on the mobile client.
- deep_link: The CTA button takes the user to a particular deep link specified in the app.
- drill_down: The CTA button opens the detailed view of the rich message received by the app.'
link:
type: string
description: 'The URL to which the user will be directed, depending on the type of the CTA
'
label:
type: string
description: 'The text that appears on the CTA button in the app
'
cta_type:
type: string
description: 'More than one CTA object can be returned to the app. The cta_type can have two possible values: primary and secondary. The primary CTA is higher priority and is the main CTA button. The secondary CTA can be something like a terms and conditions link that can be rendered appropriately in the app.'
description: "Short for call to action, a device designed to prompt an immediate response from a user\n\n```json\n[\n {\n \"type\": \"external_web_link\",\n \"link\": \"URL_GOES_HERE\",\n \"label\": \"More Details\",\n \"cta_type\": \"primary\"\n },\n {\n \"type\": \"external_web_link\",\n \"link\": \"URL_GOES_HERE\",\n \"label\": \"Terms & Conditions\",\n \"cta_type\": \"secondary\"\n }\n]\n```\n"
title: CTA (Array Object)
x-stoplight:
id: 80d7d22f4d11c
background-content:
type: object
description: "This is the content that makes the background of the message.\n\n```json\n{\n \"type\": \"image\",\n \"url\": \"IMAGE_URL_GOES_HERE\",\n \"alt_text\": \"Black Background Image\",\n \"initial_frame\": \"\"\n}\n```"
title: Background Content (Object)
properties:
type:
type: string
description: The type of the background content. It can be an image or a color.
url:
type: string
description: The URL of the image that will be used as the background
alt_text:
type: string
description: Alternate text that appears if the app cannot render the background content of the message
initial_frame:
type: string
description: The initial frame or first frame is what appears behind the play button before a user taps it to start playing the video.
x-stoplight:
id: 80de922cbc5ff
hero-content:
type: object
description: "This is the first visual content that a user encounters when the user views a rich message. This can be an image or a video.\n\n```json\n{\n \"type\": \"image\",\n \"url\": \"IMAGE_URL_GOES_HERE\",\n \"alt_text\": \"Fries\",\n \"initial_frame\": \"\"\n}\n```\n"
title: Hero Content (Object)
properties:
type:
type: string
description: Hero content can be an image or a video.
url:
type: string
description: The URL of the image/video that will be used as the hero content in a rich message
alt_text:
type: string
description: Alternate text that appears if the app cannot render the hero content of the message
initial_frame:
type: string
description: The initial frame or first frame is what appears behind the play button before a user taps it to start playing the video.
x-stoplight:
id: 4779761c509cd
messages:
type: object
description: 'Returned in response to the [Fetch Messages](/docs/dev-portal-mobile/e9485ca96ff55-fetch-messages) API
'
x-examples: []
title: Messages (Array Object)
x-stoplight:
id: 4e7b944f87362
properties:
messages:
type: array
items:
type: object
properties:
background_content:
$ref: '#/components/schemas/background-content'
body:
type: string
description: 'The text content of a rich message
'
cta:
$ref: '#/components/schemas/cta'
dismissable:
type: boolean
description: 'This boolean value decides whether guests can dismiss a message or not. When a guest dismisses a message, it should not be rendered in the app.
'
hero_content:
$ref: '#/components/schemas/hero-content'
launch_time:
type: string
description: "Date/time, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format, when the notification should be rendered by the application client. This is a useful field that can enable a business to create messages that can be sent to the mobile client in advance, and they appear in the app later when the launch time comes.\n\nIf a rich message is triggered from a campaign, from a notification template as a result of user action, as a result of test notification, or if the Launch Time and Take Down Time fields are left blank in a business announcement, the values for launch_time and take_down_time will be null.\n\nThe values of take_down_time and launch_time parameters are determined when configuring campaign announcements. To set up a campaign announcement in the Punchh platform, in the left navigation pane, navigate to <b>Loyalty Program > App Message Composer</b>, and click <b>Add App Message</b>. In the <b>New Announcement</b> page, specify the date and time of the launch in the <b>Launch Time</b> field and the take down time in the <b>Take Down Time</b> field. \n\nOnce configured, these values will be displayed in the `launch_time` and `take_down_time` parameters respectively when the messages are fetched via this Mobile API."
message_type:
type: string
description: 'There are two types of rich Messages returned in response:
1. user_specific: Rich messages that have a user context. These include rich messages created based on campaigns or user actions.
2. business_wide: Rich messages that are created as business announcements in the system.'
rank:
type: integer
description: Every message should have a rank. This marks the importance of a message. There may be a case when a more important message moves down the display list in the app as new messages are delivered to the mobile client. To keep important messages at the top of the display list, they should be given a higher number just as is the case with z-index. If two messages have the same rank, the app will determine the display order based on the launch_time.
style_url:
type: string
description: 'Link to the style sheet file for the style that will be applied to the message. The mobile client can download the style file, which can then be used to render the rich message in the app.
'
subtitle:
type: string
description: 'A subordinate title providing additional information about the content
'
tags:
type: array
description: 'Tags provide additional details about a message. A simple example could be the type (such as campaign, system_notification, etc.) that may help the app make decisions about the rendering of the message.
'
items:
type: string
take_down_time:
type: string
description: "Date/time, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format, when the mobile client should stop rendering the rich message in the app.\n\nIf a rich message is triggered from a campaign, from a notification template as a result of user action, as a result of test notification, or if the Launch Time and Take Down Time fields are left blank in a business announcement, the values for launch_time and take_down_time will be null.\n\nThe values of take_down_time and launch_time parameters are determined when configuring campaign announcements. To set up a campaign announcement in the Punchh platform, in the left navigation pane, navigate to <b>Loyalty Program > App Message Composer</b>, and click <b>Add App Message</b>. In the <b>New Announcement</b> page, specify the date and time of the launch in the <b>Launch Time</b> field and the take down time in the <b>Take Down Time</b> field. \n\nOnce configured, these values will be displayed in the `launch_time` and `take_down_time` parameters respectively when the messages are fetched via this Mobile API."
title:
type: string
description: 'A suitable title for the rich message. A well-crafted title increases the chances that a user will view a message.
'
message_id:
type: integer
description: 'Unique ID of the message sent to the user
'
read_at:
type: string
x-stoplight:
id: ten5f40qgu98e
format: date-time
description: Date/time when the message was read, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. To mark a message read, you must call the [Mark Messages As Read](/docs/dev-portal-mobile/899a3394bf4e6-mark-messages-as-read) API. The `read_at` parameter value remains null until the message is explicitly marked as read using the appropriate API.
enum:
- YYYY-MM-DDThh:mm:ssZ
created_at:
type: string
x-stoplight:
id: 04jvdgbo8cmcv
format: date-time
description: Date/time when the message was created, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format
enum:
- YYYY-MM-DDThh:mm:ssZ
deleted_at:
type: string
x-stoplight:
id: jynu306dbfuc9
format: date-time
description: Date/time when the message was deleted, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. To delete the message, you must call the [Delete Messages](/docs/dev-portal-mobile/8dbb3bf79ad94-delete-messages) API. Once deleted, the `deleted_at` parameter will return a value in the API response.
enum:
- YYYY-MM-DDThh:mm:ssZ
x-stoplight:
id: bf6eddb435209
x-ext-urls: {}