{ "openapi": "3.1.0", "info": { "title": "PassEntry API", "description": "# Getting Started\n**Welcome to Passentry**\n\nPassEntry API is an OpenAPI 3.1.0 compliant REST API with predictable URLs, JSON request bodies, standard HTTP response codes, authentication, and verbs.\nThis documentation describes the functionality of our system available for integration with your business.\n\n**API Host** `https://api.passentry.com`\n\n# Authentication\n\nThe PassEntry API uses API keys to authenticate requests. You can view and manage your API keys in [Developer tools](https://app.passentry.com/developer-tools) in the PassEntry Dashboard\n\nYour API keys carry many privileges, so be sure to keep them secure. Don't share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.\n\nAuthentication to the API is performed with Bearer authentication. These tokens must be attached to the Authorization header of the request.\n \nExample: ``\"Authorization\": \"Bearer {API KEY}\"``\n\nYou must make all API calls over [HTTPS](http://en.wikipedia.org/wiki/HTTP_Secure). Calls that you make over plain HTTP will fail. API requests without authentication will also fail.\n\n# Responses\nPassEntry API responses are generally in [JSON API](https://jsonapi.org/format/) format, which provides a consistent standard for formatting responses in JSON, including a top-level `data` object and optional `included` and `meta` objects.\n\n# Errors\n\nPassEntry uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the `2xx` range indicate success. Codes in the `4xx` range indicate an error that failed given the information provided (e.g., a required parameter was omitted, syntax error, etc.). Codes in the `5xx` range indicate an error with PassEntry's servers (these are rare).\n\nSome `4xx` errors include text that briefly explains the error reported.\n", "version": "v1", "x-logo": { "url": "https://i.ibb.co/Hrv54Cp/Group-2742265.png", "href": "https://passentry.com" } }, "servers": [ { "url": "https://api.passentry.com", "description": "Production server" } ], "tags": [ { "name": "Entities", "description": "**What are entities?**\n\nEntities serve as subdivisions within an organization, designed to help larger clients such as aggregators or resellers manage their operations more effectively. \nEach entity can represent a different department or business unit within the larger organization, enabling detailed segmentation and breakdowns.\n\nA common use case of having multiple entities is separating the passes in the Wallet (Most commonly an issue in Apple Wallet) as passes from different entities are not grouped in the Wallet.\n\nAll organisations have one entity by default. For most organisations, this is sufficient. If you would like to create additional entities, please contact PassEntry.\n\n**Example**\n\nAn organisation, \"PassEntry Enterprise\" has 2 business units, \"PassEntry Supermarket\" and \"PassEntry Coffee\".\nIn order to keep their information and data separate, they have 2 *Entities*, each with their own *Pass Templates*, *Passes*...etc\n" }, { "name": "Pass Templates", "description": "## Pass templates\n\nBefore creating passes using the PassEntry API, it is necessary to have a pass template built. A template serves as a blueprint for your passes and includes various components such as fields, colours, images and value keys.\n\n**Create pass template**\n\nTo create a pass template, you can do so directly from the Dashboard, in the Pass Templates page. Click the button 'Create Pass Template' in the top right corner (direct link: [https://passentry.com/pass-templates/create](https://passentry.com/pass-templates/create)).\n\nOnce created, the pass template will be shown in the Pass Templates page.\n\n**See pass templates list**\n\nAll pass templates are displayed in the Pass Templates page of your Dashboard (direct link: [https://passentry.com/pass-templates](https://passentry.com/pass-templates)).\n" }, { "name": "Events" }, { "name": "Passes", "description": "---\n\n## Notifications\nPassEntry supports wallet-native push notifications on both the Apple and Google Wallet.\n\nUse notifications to deliver timely and relevant updates to your customers, such as when the time for an event has changed or that their membership is about to expire.\nA push notification message will appear on the lock screen and will be stored on the back of the pass as the \"Latest Update\".\n\n\n**Best practices**\n\n**Google** currently limits their push notifications to **3 per day** per pass, if you go over this quota, the passholder will not receive a push notification on their lock screen, but it will update the \"Latest Update\" on the back of the pass.\n\n**Apple** limits their push notifications to **10 per day** and may sometimes not show push notifications if sent within a very short interval (seconds between notifications)\n\nWe suggest limiting the maximum number of notifications per day per pass to 3\n \n\n## Using PassEntry's Download Page to Deliver Passes\n\nWhen creating a pass, we return a JSON object with pass attributes and timestamps. Within this object, we include a `downloadUrl`, unique to each pass, which when clicked by the end user will open a generic pass download page, a web view hosted by PassEntry on `download.passentry.com`.\n\nAs at this stage, the passholder's device type is unknown, one of the purposes of this download page is to detect the user's device and deliver either an Apple Wallet pass or Google Wallet pass. When the download page is opened on a device other than an iPhone or Android phone, it will display a QR code directing the user to the same URL, in order to direct them to open the download page on a mobile device.\n\nUsing this download page enables simple distribution of passes to your customers via a generic, dynamic link. As a best practice, we suggest putting the `downloadUrl` behind a button or redirecting the user to it at a desired point in their user journey.\n\n## Using 'Direct' Pass Source Delivery\n\nIn some cases, use of the download page is not a viable option, such as when provisioning the pass from within an app, or when wanting to directly deliver the pass from within a web page, without redirecting the user to PassEntry's download page. \n\nIn order for this to be possible, you must know the device type when creating the pass. When delivering the pass from within an app, the device type will already be known. When delivering from a web page, there are a number of scripts that can be used to detect the device type and request the correct pass source.\n\nHere is a sample script:\n\n```javascript\n// JavaScript\nconst getMobileOS = () => {\n const userAgent = navigator.userAgent || navigator.vendor || window.opera;\n if (/android/i.test(userAgent)) {\n return \"Android\";\n } else if (/iPhone/i.test(userAgent)) {\n return \"iPhone\";\n }\n return \"Other\";\n};\n\n// Example usage\nconst mobileOS = getMobileOS();\nconsole.log(`This page is opened on: ${mobileOS}`);\n```\n\nOnce the device is known, request and deliver the correct Pass Source. \nTo request the Pass Source, include the `?includePassSource` query parameter in your `POST /passes/` or `GET /passes/:id` request. This parameter accepts `apple` or `google` as options. For more details, review the API documentation for these endpoints.\n\nIf valid, the response will include the pass attributes in JSON, alongside a `passSource` object. It will only return the `passSource` object in the response if the selected pass is not currently active in a device.\n\n### Delivering a Google Wallet Pass\n\nThe `passSource` object will contain a key, `googleDownloadUrl`, containing a unique URL, which when opened on an Android device, will prompt the user to add their pass to their Google Wallet. As the Google Wallet is linked to an individual Google Account, the user will be prompted to log in to their Google Account if they are not already logged in and to download the Google Wallet if they have not already done so.\n\nThe `googleDownloadUrl` works best when placed behind Google's \"Add to Google Wallet\" button. Here are the brand guidelines and assets provided by Google:\n\n[Add to Google Wallet](https://developers.google.com/wallet/generic/resources/brand-guidelines?hl=en)\n\n### Delivering an Apple Wallet Pass\n\nApple requires the pass source to be delivered as a file with a `.pkpass` extension. The `passSource` object will contain a key, `appleBase64`, containing the `.pkpass` file encoded in base64. Decode the base64, save it to a file with the `.pkpass` extension, and deliver this to the user. When an iPhone detects a `.pkpass` file, it will prompt the user to add it to their Apple Wallet. Deliver the pass when the user clicks Apple's \"Add to Apple Wallet\" button. Here are the brand guidelines and assets provided by Apple:\n\n[Add to Apple Wallet](https://developer.apple.com/wallet/add-to-apple-wallet-guidelines/)\n" }, { "name": "Loyalty", "description": "PassEntry provides a number of RESTful endpoints for interacting and manipulating passes created under the Loyalty vertical. \nThis includes but is not limited to: Loyalty Cards, Gift Cards, Coupons, Memberships…\n\n\n### Terminology\n\n**Balance**: This can represent loyalty points, stamps, credit, and more in an integer type. Balance can be accumulated or used. Balance is stored in our database and represented on the pass. \n\n**POS System:** handles in store sales transactions, inventory management, and reporting\n\n**Loyalty Program:** This is implemented externally to PassEntry, is where the loyalty behaviour is handled and loyalty/customer data is stored. Ideally, this would be closely integrated with the POS system, in order to allow for seamless tracking of purchases and points. _As a best practice, any loyalty data relevant to a pass must always be mirrored in the loyalty program_.\n\n**Payment Terminal:** where payment is made, can also be used to read the loyalty pass and thus identify the customer \n\n### Enabling loyalty balance\nTo allow interacting with your passes using the Loyalty API, the first step is to ensure that the parent template has loyalty balance enabled.\nOnce this is done, you must choose how you want the balance to be represented on the pass, set at the pass template level.\nWe currently offer support for **integer** and **decimal** types.\n\n- **Integer:** Choose this if your balance is represented as whole numbers. *Eg: 3, 42, 9000*. The loyalty balance will appear as an integer in our responses to the loyalty API, and any numeric value sent in a request will be coerced to an integer. The value on the pass will be represented as an integer. \n- **Decimal:** We support up to 2 decimal places. *Eg: 3.14, 10.95, 100000.34*. The loyalty balance will appear as a float in our responses to the loyalty API. When making requests, format the number as a float with no more than 2 decimal places. When displaying the value on the pass, it will be represented using thousand separators with 2 decimal places. (100,000.34)\n\n---\n \n### What does a loyalty integration with PassEntry look like?\n\n**Example**: PassEntry Coffee has a loyalty program. Every £10 spent, a customer receives 1 `Point` \nWhen a customer has received 5 points they are able to get £5 off on their order total\n\n**Distributing a loyalty pass**\n\n1. A loyalty pass is created and distributed to a customer with an `ext_id` equivalent to customer in the loyalty program\n \n2. The loyalty pass balance on this loyalty pass is `0`. This is represented on the loyalty pass as `Points 0` and is stored on the loyalty program.\n \n3. When the customer makes a purchase in store and presents their device to make payment, the reader identifies their loyalty pass and sends both the loyalty pass `ext_id` and the loyalty pass balance to the POS\n \n\n**Accumulating balance**\n\n4. The POS system takes payment, and updates the loyalty pass with a balance equal to a value determined by the loyalty program, alongside an optional push notification.\n \n5. In this example, the customer has spent £20, so the the balance is increased by 2 points and the customer receives `Thank you for your order. You've earned 2 points!` as a push notification.\n \n\n**Receiving a reward**\n\n5. The POS system takes £10 payment and customer balance is increased by 1 point.\n \n6. As the threshold of 5 points has been reached, as determined by the loyalty program, the customer is sent a push notification `Congratulations! You've got £5 off on your next order!`\n \n7. The pass design can be updated via the `/passes/` endpoint so that the `£5 off` reward appears on the loyalty pass design to inform the customer of their reward\n \n\n**Redeeming a reward**\n\n8. The POS system is ready to receive payment of £8\n \n9. The customer presents their device, and their loyalty pass `ext_id` and balance are sent to the POS system, identifying the customer to the loyalty program\n \n10. The loyalty program detects that the customer has 5 points and is thus entitled to a £5 off discount\n \n11. The POS system prompts the user to redeem their `£5 off!` reward via a `Would you like get £5 off on this order?` prompt (**Optional:** rewards can be applied automatically as determined by the loyalty program)\n \n12. The transaction amount on the payment terminal is updated to £3\n \n13. The customer makes payment\n \n14. The reward is removed from the loyalty pass alongside a `You've used your £5 off discount!` push notification\n \n\n**Resetting the balance (Optional)**\n\n17. At this stage, the loyalty balance can be reset to 0 points\n" }, { "name": "Webhook Subscriptions", "description": "Webhook subscriptions allow you to receive events as they occur, so that your backend systems can execute actions accordingly.\n\nTo enable webhooks, you must first register a valid HTTPS URL, and subscribe to the events you want to be notified by.\nTo do this, please visit the Webhook section on the PassEntry dashboard or use the API endpoints.\n\n### Setting Up Your Webhook Endpoint\n\n- **HTTPS Requirement**: Ensure your endpoint is a valid HTTPS URL and the path can receive POST requests.\n \n### Receiving Webhook Events\n\n- **Event Notification**: Upon the occurrence of a subscribed event, PassEntry will send a JSON payload to your endpoint, detailing the event type, timestamp, and relevant information.\n" }, { "name": "Webhooks", "description": "# Incoming Webhooks with PassEntry\n\n## Overview\n\nWhen building integrations with PassEntry, you might want your application to receive events as they occur, so that your backend systems can execute actions accordingly.\n\nTo enable webhooks, you must first register a valid HTTPS URL, and subscribe to the events you want to be notified by.\nTo do this, please visit the Webhook section on the PassEntry dashboard.\n\n### Setting Up Your Webhook Endpoint\n\n- **HTTPS Requirement**: Ensure your endpoint is a valid HTTPS URL and the path can receive POST requests.\n \n### Receiving Webhook Events\n\n- **Event Notification**: Upon the occurrence of a subscribed event, PassEntry will send a JSON payload to your endpoint, detailing the event type, timestamp, and relevant information.\n\n## Security Measures\n\nWe implement a number of security measures to guarantee any interactions between PassEntry and your system are verified and authentic.\n\n- **Secret Key**: When configuring your webhook endpoint, you will be provided a secret key, which PassEntry will use to sign any outbound webhooks. \nYou must store this securely.\nIf you believe your secret key has been compromised, you have the option to **rotate** your secret key. \nThis will immediately invalidate the previous secret key and sign all subsequent webhooks with the new key\n \n- **Timestamp**: Each webhook payload includes a timestamp, serving as a safeguard against replay attacks.\n \n- **HMAC-SHA256 Signature**: Every outgoing webhook includes an HMAC signature.\nThe signature is included in the `X-Webhook-Signature` header and is generated using the webhook payload and the shared secret key.\nTo verify that the webhook is authentic, you can encrypt the webhook payload using the SHA-256 encryption algorithm and your secret key.\nIf your generated signature matches the signature included in the `X-Webhook-Signature` header, you can confirm that the webhook is authentic.\n \n\n## Reliability and Retries\n\n- **Asynchronous Delivery**: Webhooks include a timestamp to reflect the actual event time.\n \n- **Retry Mechanism**: Failures in delivery due to network issues, SSL problems, or non-2xx HTTP responses will trigger retries. PassEntry retries delivery up to 10 times over 3 days, using exponential backoff.\n\n## Responding to Webhooks\n\n- **Success Responses**: Please ensure your endpoint returns a status code within the 200-299 range. Any code outside this range is considered an error, prompting retries.\n \n- **Response Body**: While optional, you may return a response body.\n\n### Example Success Response\n\n```http\nHTTP Status: 200\nContent-Type: application/json\n\n{\n \"status\": \"ok\"\n}\n```\n\n---\n" }, { "name": "Readers", "description": "Readers can be used for a variety of use cases, to validate access, redeem loyalty, claim discounts, identify the user and much more.\n\n**NFC**\n\nPassEntry's passes are NFC enabled, which allow you to set an NFC 'value' behind every pass. This value defaults to the UUID of the pass, or can be set to a custom value.\nThis NFC value is encrypted, and can only be generated by PassEntry.\nIn order for the NFC value to be read, an NFC reader must be configured.\nTo do this, two things are required, a pass identifier, which tells the reader which passes to request the device for when \"tapped\", and a private key, which allows the reader to decrypt the NFC value.\n\nOur system supports two types of Readers: **VTAP Readers** and **PassEntry Reader App**. Both types can be configured through the Passentry Dashboard or via API requests.\n\nBelow, we provide an overview of each reader type, the configuration process, and additional setup information.\n\n## VTAP Readers\n\n**VTAP Readers** come in a range of form factors, from boxed, countertop devices to embedded hardware that can be integrated in existing platforms. The NFC value can be transmitted over the internet, or over wire through USB, RS-232, RS-485, Wiegand and more.\n\n#### Configuration:\n\nSetting up a VTAP Reader consists of two parts:\n\n1. **Creating a Reader on Passentry**: You need to provide the following information:\n\n - **Name**: A friendly display name for the reader\n - **UUID**: A unique identifier for the reader, this must be the \"Reader Serial\" provided by Dot Origin\n - **Type**: Should be set to `VtapReader`\n\n\n2. **Setting up the Device on VTAP Website**: After creating the reader on Passentry, retrieve the required configuration information and use it to set up the device on the VTAP website. More detailed instructions are provided in the guide.\n\n\n## PassEntry Reader App\n\n**PassEntry Reader** is a software application available for download from the Google Play Store, MAXSTORE, and Sunmi App Store. This reader offers additional functionality and settings for scanning NFC passes, QR codes/barcodes, Mifare Classic NFC cards, and more. It can perform specific actions such as scanning taps, redeeming/adding points, and adding stamps. For more information, please [contact PassEntry](mailto:support@passentry.com).\n" }, { "name": "Image Assets", "description": "Image Assets allow you to upload images once and reference them by ID across multiple passes using `templateOverride`. This reduces duplication and simplifies pass image management.\n\nImages can be provided as a **direct URL** or **base64 encoded data**. Supported formats: **PNG, JPG, WebP**.\n\nSupported image types: `banner`, `logo`, `icon`, `thumbnail`.\n\nUpload an image using the Create Image Asset endpoint, then reference the returned `id` in your pass `templateOverride` using the `imageAssetId` field." }, { "name": "Apple Geofencing", "description": "# Overview\n\nThis document outlines the implementation of geofencing and iBeacon technology to enhance customer engagement through targeted notifications based on location proximity.\n\nCurrently, only Apple Wallet passes support this feature due to Google Wallet constraints.\n\n## Geofence Notifications\n\n- When a user enters a geofenced area, a notification appears on the lock screen, displaying a preview of the pass from the wallet app along with any set geofence message.\n- Tapping the notification opens the pass in the wallet app, facilitating quick access to barcodes or NFC validation.\n- Geofence notifications are **passive**, meaning the system does not notify PassEntry when a user enters a geofence. This design respects privacy and security considerations.\n**Note:** When setting 2 or more geofences in close proximity, there may be a delay in the notification appearing when moving between geofences. The device implements a cooldown period to ensure that the user has left the previous geofence before entering the next one.\n\n\n# Locations\n - Utilizes exact coordinates (latitude and longitude) to define the targeted area.\n - The radius for geofencing can be set between 10 and 1000 meters (depending on pass type). This allows you to tailor the geofenced area to your specific needs, such as covering the area of a small store or a larger outdoor venue.\n - Each pass can include up to 10 geofenced locations. For more extensive coverage, consider using **beacons**.\n - PassEntry is not able to track the exact location of the user, we do not have access to the user's location data, as this never leaves the device.\n\n# Beacons\n\niBeacons are a technology standard developed by Apple that allows mobile apps to listen for signals from beacons in the physical world and react accordingly. \nThe technology is based on Bluetooth Low Energy (BLE) proximity sensing, which enables a device to perform actions when in close proximity to a beacon.\nPassEntry is not able to track the exact location of the user, we do not have access to the user's location data, as this never leaves the device.\n\n\n\nLearn more about beacons here: [iBeacon](https://en.wikipedia.org/wiki/IBeacon)\n\n\nIf you have a large number of location you would like to enable geofence capabilities for, here's an example: \n\n**Use Case: PassEntry Coffee Chain**\n - Scenario: PassEntry Coffee, a chain with 100 locations across London, Dubai, and Singapore, uses iBeacons to offer location-based promotions.\n - Each location is equipped with two beacons: one in the bakery section and another in the cafe section.\n - The PassEntry Coffee loyalty pass incorporates different campaigns across regions, utilizing the same UUID for all beacons but varying Major and Minor values for location and section identification.\n - In total, PassEntry Coffee would purchase and configure 200 ibeacons (100 locations x 2 sections).\n\n Configuration Example\n - UUID: All beacons use E2C56DB5-DFFB-48D2-B060-D0F5A71096E0.\n - Major: Represents the city (e.g., 1 for London, 2 for Dubai).\n - Minor: Specifies the section within a location (e.g., 1 for the bakery, 2 for the cafe).\n\n In this example: **PassEntry Coffee** would configure their 200 beacons like so:\n```\nLondon (50 locations): \n Bakery Section beacons: \n uuid: E2C56DB5-DFFB-48D2-B060-D0F5A71096E0 \n major: 1 \n minor: 1 \n name: 'london-bakery' \n Cafe Section beacons: \n uuid: E2C56DB5-DFFB-48D2-B060-D0F5A71096E0 \n major: 1 \n minor: 2 \n name: 'london-cafe' \n\nDubai (30 locations): \n Bakery Section beacons: \n uuid: E2C56DB5-DFFB-48D2-B060-D0F5A71096E0 \n major: 2 \n minor: 1 \n name: 'dubai-bakery' \n Cafe Section beacons: \n uuid: E2C56DB5-DFFB-48D2-B060-D0F5A71096E0 \n major: 2 \n minor: 2 \n name: 'dubai-cafe' \n\nSingapore (20 locations): \n Bakery Section beacons: \n uuid: E2C56DB5-DFFB-48D2-B060-D0F5A71096E0 \n major: 3 \n minor: 1 \n name: 'singapore-section' \n Cafe Section beacons: \n uuid: E2C56DB5-DFFB-48D2-B060-D0F5A71096E0 \n major: 3 \n minor: 2 \n name: 'singapore-cafe'\n```\n\nWhen building the pass via the PassEntry API, the following JSON structure would be used to define the beacons:\n\n```\n{\n \"beacons\": [\n {\n \"proximity_uuid\": \"E2C56DB5-DFFB-48D2-B060-D0F5A71096E0\",\n \"major\": 1,\n \"minor\": 1, \n \"message\": \"£10 off on cakes!\",\n \"name\": \"london-bakery\"\n }, {\n \"proximity_uuid\": \"E2C56DB5-DFFB-48D2-B060-D0F5A71096E0\",\n \"major\": 1,\n \"minor\": 2, \n \"message\": \"Buy one get one free juice\",\n \"name\": \"london-cafe\"\n }, {\n \"proximity_uuid\": \"E2C56DB5-DFFB-48D2-B060-D0F5A71096E0\",\n \"major\": 2,\n \"minor\": 1, \n \"message\": \"AED 20 off on cakes!\",\n \"name\": \"dubai-bakery\"\n }, {\n \"proximity_uuid\": \"E2C56DB5-DFFB-48D2-B060-D0F5A71096E0\",\n \"major\": 2,\n \"minor\": 2,\n \"message\": \"Try our pumpkin spice lattes!\",\n \"name\": \"dubai-cafe\"\n }, {\n \"proximity_uuid\": \"E2C56DB5-DFFB-48D2-B060-D0F5A71096E0\",\n \"major\": 3,\n \"minor\": 1,\n \"message\": \"$5 off on kuih lapis!\",\n \"name\": \"singapore-bakery\"\n }, {\n \"proximity_uuid\": \"E2C56DB5-DFFB-48D2-B060-D0F5A71096E0\",\n \"major\": 3,\n \"minor\": 2, \n \"message\": \"Buy one get one free teh tarik!\",\n \"name\": \"singapore-cafe\"\n }\n ]\n}\n```\n" } ], "paths": { "/api/v1/passes/{id}/nullify": { "post": { "summary": "Nullify Pass", "description": "Irreversibly nullifies a pass, removing all dynamic data (fields, images, barcode, NFC, localisation) while preserving the tombstone record for billing and auditability.\n\nThe pass will appear in the expired section of the wallet with a generic \"Deactivated\" design. The `extId` is preserved on the nullified record and can be reused when creating new passes.\n\nThis endpoint is idempotent — calling it on an already-nullified pass returns 200 with no further changes.", "tags": [ "Passes" ], "operationId": "nullifyPass", "security": [ { "api_key": [] } ], "parameters": [ { "name": "id", "in": "path", "description": "Pass UUID or External ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "example": { "data": { "id": "e89b1330fc391ec89656f3c664318cff8805471e", "type": "pass", "attributes": { "downloadUrl": "https://download.passentry.com?pass=e89b1330fc391ec89656f3c664318cff8805471e", "passType": "storeCard", "deviceType": "iphone", "createdAt": "2025-01-15T10:30:00Z", "status": "nullified", "extId": "user-123", "addedAt": "2025-01-15T10:35:00Z", "nullifiedAt": "2026-03-28T14:00:00Z", "expiresAt": "2026-03-28T14:00:00Z", "passTemplateUuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "passTemplateName": "Loyalty Card", "nfc": null, "barcode": {}, "passContent": {} } } }, "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/serializedPassObject" } } } } } }, "401": { "description": "Error: Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errors" } } } }, "404": { "description": "Error: Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errors" } } } } } } }, "/api/v1/passes/{id}/notification": { "post": { "summary": "Send Notification", "tags": [ "Passes" ], "operationId": "notifyPass", "security": [ { "api_key": [] } ], "parameters": [ { "name": "id", "in": "path", "description": "Pass UUID or External ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Succesful", "headers": { "X-Notification-Status": { "schema": { "$ref": "#/components/schemas/notificationStatusHeader" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/serializedPassObject" }, "meta": { "$ref": "#/components/schemas/notificationMeta" } } } } } }, "400": { "description": "Error: Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errors" } } } }, "401": { "description": "Error: Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errors" } } } }, "404": { "description": "Error: Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errors" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/notification" }, "example": { "notification": { "message": "Use code PASSENTRY2024 for 10% off!" } } } } } } }, "/api/v1/entities/{id}/messaging/wallet": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "UUID of the entity sending the batch (the entity that owns the API key making this request). This is independent of any `entityId` used inside `segments` to target recipients.", "schema": { "type": "string" } } ], "post": { "summary": "Create wallet messaging batch", "description": "Create a new wallet messaging batch using segments, recipients, or a CSV file (via multipart/form-data).\n\nThe path parameter `{id}` is the entity **sending** the batch (your own entity). Recipients are defined separately in the request body via `segments`, `recipients`, or `csv`. Pass template and group tag segments can be combined to narrow the audience to passes that match both.\n\nFor more details, see the [Wallet Messaging](/documentation/bulk-operations/batch-notifications/guide) documentation.", "tags": [ "Batches" ], "operationId": "createWalletMessagingBatch", "security": [ { "api_key": [] } ], "parameters": [], "responses": { "202": { "description": "Accepted", "content": { "application/json": { "example": { "data": { "id": "d29455c9-afe4-4c73-b946-a5ea0b1667f7", "type": "walletMessaging", "attributes": { "name": "Summer Promotion 01/06/2025", "status": "validating", "tag": null, "content": "Hello, World!", "scheduledAt": "2030-03-31T13:16:26Z" } }, "links": { "self": "https://api.passentry.com/api/v1/batches/d29455c9-afe4-4c73-b946-a5ea0b1667f7" } }, "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/serializedWalletMessagingBatch" }, "links": { "$ref": "#/components/schemas/batchSelfLink" } } } } } }, "401": { "description": "Error: Unauthorized", "content": { "application/json": { "example": { "errors": [ "Access denied" ] }, "schema": { "$ref": "#/components/schemas/errors" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createWalletMessagingBatch" }, "examples": { "Pass Group Tag Segment": { "summary": "Pass Group Tag Segment", "value": { "batch": { "message": "Hello, World!", "segments": [ { "groupTag": "summerPromotion" } ], "scheduledAt": "2030-03-31T13:16:26Z" } } }, "Pass Template Segment": { "summary": "Pass Template Segment", "value": { "batch": { "message": "Hello, World!", "segments": [ { "passTemplateId": "bf9d5cc29114" } ], "scheduledAt": "2030-03-31T13:16:26Z" } } }, "Pass Template and Group Tags Segments": { "summary": "Pass Template + Group Tags (combined)", "value": { "batch": { "message": "Hello, World!", "segments": [ { "passTemplateId": "bf9d5cc29114" }, { "groupTags": [ "summerPromotion", "easterOffer" ] } ], "scheduledAt": "2030-03-31T13:16:26Z" } } }, "Recipients": { "summary": "Recipients example with variables", "value": { "batch": { "message": "Hello, %{name}! You are a %{tier} member.", "recipients": [ { "passId": "f94b60e0eae2233b02803fdbeff779f7dc3c48fe", "variables": { "name": "Jane Doe", "tier": "Gold" } } ], "scheduledAt": "2030-03-31T13:16:26Z" } } }, "CSV File": { "summary": "CSV File", "value": { "csv": "[binary file content not shown]", "message": "Hello, %{name}! Your ticket number is %{ticket_number}.", "scheduledAt": "2030-03-31T13:16:26Z" } } } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/createWalletMessagingBatchMultipart" }, "examples": { "Batch Wallet - valid.csv": { "summary": "Batch Wallet - valid.csv", "value": { "csv": "[binary file content not shown]", "message": "Hello, %{name}! Your ticket number is %{ticket_number}.", "scheduledAt": "2030-03-31T13:16:26Z" } } } } }, "required": true, "description": "Batch" } } }, "/api/v1/batches": { "get": { "summary": "List batches", "tags": [ "Batches" ], "operationId": "listBatches", "security": [ { "api_key": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number", "schema": { "type": "integer" } }, { "name": "perPage", "in": "query", "required": false, "description": "Number of items per page", "schema": { "type": "integer" } }, { "name": "type", "in": "query", "required": false, "description": "Type of the batch", "schema": { "type": "string", "enum": [ "walletMessaging", "passCreation", "passUpdate" ] } } ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "example": { "data": [ { "id": "8ecfc493-da04-493b-8b98-bf9d5cc29115", "type": "walletMessaging", "attributes": { "name": "Summer Promotion 2", "status": "failed", "tag": null, "content": "Hello, World!", "scheduledAt": "2030-03-31T13:16:26Z" } }, { "id": "8ecfc493-da04-493b-8b98-bf9d5cc29114", "type": "walletMessaging", "attributes": { "name": "Summer Promotion", "status": "scheduled", "tag": null, "content": "Hello, World!", "scheduledAt": "2030-03-31T13:16:26Z" } } ], "meta": { "totalCount": 2, "resultsPerPage": 25, "currentPage": 1, "totalPages": 1 }, "links": { "first": null, "prev": null, "next": null, "last": null } }, "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/serializedWalletMessagingBatch" } ] } }, "links": { "$ref": "#/components/schemas/indexLinks" }, "meta": { "$ref": "#/components/schemas/indexMeta" } } } } } }, "401": { "description": "Error: Unauthorized", "content": { "application/json": { "example": { "errors": [ "Access denied" ] }, "schema": { "$ref": "#/components/schemas/errors" } } } } } } }, "/api/v1/batches/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Batch ID", "schema": { "type": "string" } } ], "get": { "summary": "Show batch", "tags": [ "Batches" ], "operationId": "showBatch", "security": [ { "api_key": [] } ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "examples": { "walletMessaging": { "value": { "data": { "id": "8ecfc493-da04-493b-8b98-bf9d5cc29114", "type": "walletMessaging", "attributes": { "name": "Summer Promotion", "status": "scheduled", "tag": null, "content": "Hello, World!", "scheduledAt": "2030-03-31T13:16:26Z" } } } }, "passCreation": { "value": { "data": { "id": "999b774f-02ae-4931-94c6-596f614ef4f4", "type": "passCreation", "attributes": { "name": "Batch: Pass Creation 2025-11-21 15:34:02", "status": "processing", "passTemplateName": "PassEntry Ticketing", "passTemplateNameId": "acbb27e9cfb4e8f62f8cb999" } } } }, "passUpdate": { "value": { "data": { "id": "999b774f-02ae-4931-94c6-596f614ef4f4", "type": "passUpdate", "attributes": { "name": "Batch: Pass Update 2025-11-21 15:34:02", "status": "validating", "tag": "summerPromotion", "passTemplateName": "PassEntry Loyalty", "passTemplateNameId": "acbb27e9cfb4e8f62f8cb999", "scheduledAt": "2024-01-01T00:00:00Z", "errorsCsvUrl": "https://example.com/errors.csv", "totalCount": 1000, "progress": { "total": 1000, "processed": 800, "pending": 200 } } } } } }, "schema": { "type": "object", "properties": { "data": { "oneOf": [ { "$ref": "#/components/schemas/serializedWalletMessagingBatch" }, { "$ref": "#/components/schemas/serializedPassCreationBatch" }, { "$ref": "#/components/schemas/serializedPassUpdateBatch" } ] } } } } } }, "401": { "description": "Error: Unauthorized", "content": { "application/json": { "example": { "errors": [ "Access denied" ] }, "schema": { "$ref": "#/components/schemas/errors" } } } } } } }, "/api/v1/batches/{id}/send-now": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Batch ID", "schema": { "type": "string" } } ], "post": { "summary": "Send batch now", "description": "Overrides a scheduled wallet messaging batch's `scheduledAt` time and starts sending immediately. Only valid for batches of type `walletMessaging` that are currently in `scheduled` status.\n\nUse this after creating a wallet messaging batch with a future `scheduledAt` value when you want to send it without waiting for the scheduled time.", "tags": [ "Batches" ], "operationId": "sendBatchNow", "security": [ { "api_key": [] } ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "example": { "success": "Scheduled batch cancelled and batch sent now" }, "schema": { "type": "object", "properties": { "success": { "type": "string" } } } } } }, "400": { "description": "Batch is not in `scheduled` status, or the batch could not be sent", "content": { "application/json": { "examples": { "notScheduled": { "value": { "error": "Batch must be in scheduled status to send messages now" } }, "sendFailed": { "value": { "error": "Failed to send batch wallet messaging" } } }, "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Error: Unauthorized", "content": { "application/json": { "example": { "errors": [ "Access denied" ] }, "schema": { "$ref": "#/components/schemas/errors" } } } }, "404": { "description": "Batch not found", "content": { "application/json": { "example": { "errors": [ "Batch not found" ] }, "schema": { "$ref": "#/components/schemas/errors" } } } }, "422": { "description": "Batch is not a wallet messaging batch", "content": { "application/json": { "example": { "errors": [ "Only wallet messaging batches can be sent now" ] }, "schema": { "$ref": "#/components/schemas/errors" } } } } } } }, "/api/v1/batches/{id}/cancel": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Batch ID", "schema": { "type": "string" } } ], "patch": { "summary": "Cancel batch", "tags": [ "Batches" ], "operationId": "cancelBatch", "security": [ { "api_key": [] } ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "examples": { "walletMessaging": { "value": { "data": { "id": "8ecfc493-da04-493b-8b98-bf9d5cc29114", "type": "walletMessaging", "attributes": { "name": "Summer Promotion", "status": "cancelled", "tag": null, "content": "Hello, World!", "scheduledAt": "2030-03-31T13:16:26Z" } } } }, "passUpdate": { "value": { "data": { "id": "999b774f-02ae-4931-94c6-596f614ef4f4", "type": "passUpdate", "attributes": { "name": "Batch: Pass Update 2025-11-21 15:34:02", "status": "cancelled", "tag": "summerPromotion", "passTemplateName": "PassEntry Loyalty", "passTemplateNameId": "acbb27e9cfb4e8f62f8cb999", "scheduledAt": "2030-03-31T13:16:26Z" } } } } }, "schema": { "type": "object", "properties": { "data": { "oneOf": [ { "$ref": "#/components/schemas/serializedWalletMessagingBatch" } ] } } } } } }, "401": { "description": "Error: Unauthorized", "content": { "application/json": { "example": { "errors": [ "Access denied" ] }, "schema": { "$ref": "#/components/schemas/errors" } } } } } } }, "/api/v1/entities": { "get": { "summary": "List entities", "tags": [ "Entities" ], "operationId": "listEntities", "security": [ { "api_key": [] } ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "example": { "data": [ { "id": "0d10c850", "type": "entity", "attributes": { "name": "PassEntry Fitness Centre", "passDeeplinks": { "apple": "shoebox://pass/pass.com.test.test/{PASSENTRY_PASS_UUID}", "google": "https://pay.google.com/gp/v/object/3388000000022258457.{PASSENTRY_PASS_UUID}" } } }, { "id": "0d10c84f", "type": "entity", "attributes": { "name": "PassEntry Coffee", "passDeeplinks": { "apple": "shoebox://pass/pass.com.test.test/{PASSENTRY_PASS_UUID}", "google": "https://pay.google.com/gp/v/object/3388000000022258457.{PASSENTRY_PASS_UUID}" } } }, { "id": "0d10c84e", "type": "entity", "attributes": { "name": "PassEntry Supermarket", "passDeeplinks": { "apple": "shoebox://pass/pass.com.test.test/{PASSENTRY_PASS_UUID}", "google": "https://pay.google.com/gp/v/object/3388000000022258457.{PASSENTRY_PASS_UUID}" } } } ], "meta": { "totalCount": 3, "resultsPerPage": 25, "currentPage": 1, "totalPages": 1 }, "links": { "first": null, "prev": null, "next": null, "last": null } }, "schema": { "$ref": "#/components/schemas/serializedEntitiesList" } } } }, "401": { "description": "Error: Unauthorized", "content": { "application/json": { "example": { "errors": [ "Access denied" ] }, "schema": { "$ref": "#/components/schemas/errors" } } } } } } }, "/api/v1/entities/{id}": { "parameters": [ { "name": "id", "in": "path", "description": "Entity ID", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "Show Entity", "tags": [ "Entities" ], "operationId": "getEntity", "security": [ { "api_key": [] } ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "example": { "data": { "id": "37ae0eaa", "type": "entity", "attributes": { "name": "PassEntry Supermarket", "passDeeplinks": { "apple": "shoebox://pass/pass.com.test.test/{PASSENTRY_PASS_UUID}", "google": "https://pay.google.com/gp/v/object/3388000000022258457.{PASSENTRY_PASS_UUID}" } } } }, "schema": { "$ref": "#/components/schemas/serializedEntity" } } } }, "401": { "description": "Error: Unauthorized", "content": { "application/json": { "example": { "errors": [ "Access denied" ] }, "schema": { "$ref": "#/components/schemas/errors" } } } }, "404": { "description": "Error: Not Found", "content": { "application/json": { "example": { "errors": [ "Entity not found" ] }, "schema": { "$ref": "#/components/schemas/errors" } } } } } } }, "/api/v1/events/{event_uuid}": { "get": { "summary": "Show event", "tags": [ "Events" ], "operationId": "showEvent", "security": [ { "api_key": [] } ], "parameters": [ { "name": "event_uuid", "in": "path", "description": "event_uuid", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "example": { "data": { "id": "506cb78e57ee", "type": "event", "attributes": { "name": "The Lion King Live", "venueName": "Lyceum Theathre", "startTime": "2023-09-15T11:45:00Z", "endTime": "2023-09-15T11:45:00Z", "timeZone": "UTC", "status": "ended" }, "meta": { "passesCount": 0 } } }, "schema": { "$ref": "#/components/schemas/serializedEvent" } } } }, "401": { "description": "Error: Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errors" } } } }, "404": { "description": "Error: Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errors" } } } } } }, "patch": { "summary": "Update event", "tags": [ "Events" ], "operationId": "updateEvent", "security": [ { "api_key": [] } ], "parameters": [ { "name": "event_uuid", "in": "path", "description": "event_uuid", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful", "content": { "application/json": { "examples": { "Example": { "value": { "data": { "id": "506cb78e57ee", "type": "event", "attributes": { "name": "The Lion King Live", "venueName": "Lyceum Theathre", "startTime": "2023-09-15T11:45:00Z", "endTime": "2023-09-15T11:45:00Z", "timeZone": "UTC", "status": "ended" }, "meta": { "passesCount": 0 } } } } }, "schema": { "$ref": "#/components/schemas/serializedEvent" } } } }, "401": { "description": "Error: Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errors" } } } }, "422": { "description": "Error: Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errors" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/updateEvent" } } } } } }, "/api/v1/entities/{entity_id}/events": { "post": { "summary": "Create event", "tags": [ "Events" ], "operationId": "createEvent", "security": [ { "api_key": [] } ], "parameters": [ { "name": "entity_id", "in": "path", "description": "entity_id", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "Created", "content": { "application/json": { "examples": { "Example": { "value": { "data": { "id": "9f1e67ca17ee", "type": "event", "attributes": { "name": "Bob Marley Live", "venueName": "The Lyceum Theatre", "startTime": "1975-07-17T22:30:00+01:00", "endTime": "1975-07-18T02:30:00+01:00", "timeZone": "Europe/London", "status": "ended" }, "meta": { "passesCount": 0 } } } } }, "schema": { "$ref": "#/components/schemas/serializedEvent" } } } }, "401": { "description": "Error: Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errors" } } } }, "422": { "description": "Error: Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errors" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createEvent" } } } } } }, "/api/v1/loyalty/{id}": { "parameters": [ { "name": "id", "in": "path", "description": "Pass UUID or External ID", "required": true, "schema": { "type": "string" } }, { "name": "includePassDesign", "in": "query", "schema": { "type": "boolean" }, "description": "If true, includes the pass design in the response", "required": false }, { "name": "includeLocations", "in": "query", "schema": { "type": "boolean" }, "description": "If true, includes the locations in the response if any are present", "required": false }, { "name": "includeBeacons", "in": "query", "schema": { "type": "boolean" }, "description": "If true, includes the beacons in the response if any are present", "required": false } ], "get": { "summary": "Get loyalty balance", "tags": [ "Loyalty" ], "operationId": "getLoyaltyBalance", "security": [ { "api_key": [] } ], "responses": { "200": { "description": "successful", "content": { "application/json": { "example": { "data": { "id": "2258d9ed-05bc-47cd-be65-83b9bb5e0273", "type": "pass", "attributes": { "downloadUrl": "https://www.example.com?pass=2258d9ed-05bc-47cd-be65-83b9bb5e0273", "passType": "storeCard", "deviceType": "android", "createdAt": "2022-01-01T00:00:00Z", "status": "active", "extId": "4e9ab9e571bbc8ff64e7", "passTemplateUuid": "b7f3372d08eddd76f28926ff", "passTemplateName": "PassEntry Store", "nfc": "941c35348d16187199a6b41047f0b7862b2dcb67", "barcode": {}, "passContent": { "description": "Template Description", "centralTitle": "Template Central Title", "fullName": "Robert Smith", "labelOne": "1", "labelTwo": "11", "points": "7", "terms": "Your use of the Google Wallet is subject to Google's terms and conditions of use, which PassEntry are not responsible for." } } }, "meta": { "loyalty": { "balance": 7 } } }, "schema": { "$ref": "#/components/schemas/loyaltyPass" } } } }, "401": { "description": "Error: Unauthorized", "content": { "application/json": { "example": { "errors": [ "Access denied" ] }, "schema": { "$ref": "#/components/schemas/errors" } } } }, "404": { "description": "Error: Not Found", "content": { "application/json": { "example": { "errors": [ "Pass with provided id not found" ] }, "schema": { "$ref": "#/components/schemas/errors" } } } } } }, "patch": { "summary": "Update loyalty balance", "tags": [ "Loyalty" ], "operationId": "updateLoyaltyBalance", "security": [ { "api_key": [] } ], "parameters": [ { "name": "includePassDesign", "in": "query", "schema": { "type": "boolean" }, "description": "If true, includes the pass design in the response", "required": false }, { "name": "includeLocations", "in": "query", "schema": { "type": "boolean" }, "description": "If true, includes the locations in the response if any are present", "required": false }, { "name": "includeBeacons", "in": "query", "schema": { "type": "boolean" }, "description": "If true, includes the beacons in the response if any are present", "required": false } ], "responses": { "200": { "description": "successful", "content": { "application/json": { "example": { "data": { "id": "2258d9ed-05bc-47cd-be65-83b9bb5e0273", "type": "pass", "attributes": { "downloadUrl": "https://www.example.com?pass=2258d9ed-05bc-47cd-be65-83b9bb5e0273", "passType": "storeCard", "deviceType": "android", "createdAt": "2022-01-01T00:00:00Z", "status": "active", "extId": "4e9ab9e571bbc8ff64e7", "passTemplateUuid": "b7f3372d08eddd76f28926ff", "passTemplateName": "PassEntry Store", "nfc": "941c35348d16187199a6b41047f0b7862b2dcb67", "barcode": {}, "passContent": { "description": "Template Description", "centralTitle": "Template Central Title", "fullName": "Robert Smith", "labelTwo": "11", "points": "17", "terms": "Your use of the Google Wallet is subject to Google's terms and conditions of use, which PassEntry are not responsible for." } } }, "meta": { "loyalty": { "balance": 17 } } }, "schema": { "$ref": "#/components/schemas/loyaltyPass" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/loyaltyBalance" }, "examples": { "0": { "summary": "Update loyalty balance", "value": { "balance": 10 } } } } } } } }, "/api/v1/image-assets": { "post": { "summary": "Create Image Asset", "description": "Create a new image asset to be used in pass templates", "tags": [ "Image Assets" ], "operationId": "createImageAsset", "security": [ { "api_key": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/imageAsset" } } } }, "responses": { "201": { "description": "Image asset created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/serializedImageAsset" } } } }, "401": { "description": "Error: Unauthorized", "content": { "application/json": { "example": { "errors": [ "Access denied" ] }, "schema": { "$ref": "#/components/schemas/errors" } } } }, "422": { "description": "Error: Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errors" } } } } } }, "get": { "summary": "List Image Assets", "tags": [ "Image Assets" ], "operationId": "listImageAssets", "security": [ { "api_key": [] } ], "parameters": [ { "name": "perPage", "in": "query", "description": "Number of records per page. Default is 25, maximum is 100", "required": false, "schema": { "type": "integer", "default": 25 } }, { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "imageType", "in": "query", "description": "Filter by image type", "required": false, "schema": { "type": "string", "enum": [ "banner", "logo", "thumbnail", "artwork", "secondaryLogo", "venueMap" ] } }, { "name": "entityId", "in": "query", "description": "Filter by entity UUID. Only available for organisation-level API keys", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/serializedImageAssetsList" } } } }, "401": { "description": "Error: Unauthorized", "content": { "application/json": { "example": { "errors": [ "Access denied" ] }, "schema": { "$ref": "#/components/schemas/errors" } } } } } } }, "/api/v1/image-assets/{id}": { "parameters": [ { "name": "id", "in": "path", "description": "Image Asset ID", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "Show Image Asset", "tags": [ "Image Assets" ], "operationId": "getImageAsset", "security": [ { "api_key": [] } ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/serializedImageAsset" } } } }, "401": { "description": "Error: Unauthorized", "content": { "application/json": { "example": { "errors": [ "Access denied" ] }, "schema": { "$ref": "#/components/schemas/errors" } } } }, "404": { "description": "Error: Not Found", "content": { "application/json": { "example": { "errors": [ "Image asset not found" ] }, "schema": { "$ref": "#/components/schemas/errors" } } } } } } }, "/api/v1/pass_templates/{pass_template_uuid}": { "parameters": [ { "name": "pass_template_uuid", "in": "path", "description": "pass_template_uuid", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "Show Pass Template", "tags": [ "Pass Templates" ], "operationId": "getPassTemplate", "security": [ { "api_key": [] } ], "deprecated": true, "responses": { "200": { "description": "successful", "content": { "application/json": { "example": { "data": { "id": "f0af94dc3c69a80cee32c173", "type": "passTemplate", "attributes": { "backgroundColor": "#EFEFEF", "name": "Summer Sale 2023", "description": "Summer Sale Pass", "labelColor": "#FF8477", "textColor": "#29323A", "templateType": "storeCard", "header": { "header_one": { "id": "name", "label": "Name", "default_value": null }, "header_two": { "id": null, "label": null, "default_value": null }, "header_three": { "id": null, "label": null, "default_value": null } }, "primary": { "primary_one": { "id": "attendee", "label": "Attendee", "default_value": null }, "primary_two": { "id": null, "label": null, "default_value": null } }, "secondary": { "secOne": { "id": "address", "label": "Address", "default_value": null }, "secTwo": { "id": null, "label": null, "default_value": null }, "secThree": { "id": null, "label": null, "default_value": null } }, "auxiliary": { "auxOne": { "id": "dob", "label": "DOB", "default_value": null }, "auxTwo": { "id": null, "label": null, "default_value": null }, "auxThree": { "id": null, "label": null, "default_value": null } }, "backFields": { "backOne": { "id": "website", "label": "Website", "default_value": null }, "backTwo": { "id": null, "label": null, "default_value": null }, "backFive": { "id": null, "label": null, "default_value": null }, "backFour": { "id": null, "label": null, "default_value": null }, "backThree": { "id": null, "label": null, "default_value": null } } } } }, "schema": { "$ref": "#/components/schemas/serializedPassTemplateDeprecated" } } } }, "401": { "description": "Error: Unauthorized", "content": { "application/json": { "example": { "errors": [ "Access denied" ] }, "schema": { "$ref": "#/components/schemas/errors" } } } }, "404": { "description": "Error: Not Found", "content": { "application/json": { "example": { "errors": [ "Pass template not found" ] }, "schema": { "$ref": "#/components/schemas/errors" } } } } } } }, "/api/v1/webhook-subscriptions": { "post": { "summary": "Create Webhook Subscription", "description": "Create a new webhook subscription to receive events", "tags": [ "Webhook Subscriptions" ], "operationId": "createWebhookSubscription", "security": [ { "api_key": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/webhookSubscriptionRequest" }, "example": { "webhookSubscription": { "url": "https://example.com/webhook", "enabled": true, "subscribedEvents": [ "passInstalled", "passRemoved" ] } } } } }, "responses": { "201": { "description": "Webhook subscription created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/webhookSubscriptionResponse" } } }, "example": { "data": { "id": "01983282-53cf-7e16-b5e1-dd0de4ce02fa", "type": "webhookSubscription", "attributes": { "url": "https://example.com/webhook", "secretKey": "a2e2c04657b924390d2a2623439c65734d07e0f8", "enabled": true, "scopeType": "organisation", "scopeName": "Test Organisation", "subscribedEvents": [ "passInstalled", "passRemoved" ] } } } } } }, "400": { "description": "Bad Request - Invalid webhook subscription data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errors" } } } }, "401": { "description": "Unauthorized - Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errors" } } } }, "422": { "description": "Unprocessable Entity - Invalid webhook URL or configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errors" } } } } } }, "get": { "summary": "List Webhook Subscriptions", "description": "List all webhook subscriptions with pagination and filtering options", "tags": [ "Webhook Subscriptions" ], "operationId": "listWebhookSubscriptions", "security": [ { "api_key": [] } ], "parameters": [ { "name": "perPage", "in": "query", "description": "Record limiter per page. Default is 5, max is 100", "required": false, "schema": { "type": "integer", "default": 5, "maximum": 100 } }, { "name": "page", "in": "query", "description": "Page number. Default is 1", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "entityId", "in": "query", "description": "Filter by entity ID (for webhook subscriptions scoped to an entity).", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Webhook subscriptions listed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/webhookSubscriptionResponse" } }, "meta": { "$ref": "#/components/schemas/indexMeta" }, "links": { "$ref": "#/components/schemas/indexLinks" } } }, "example": { "data": [ { "id": "01983282-53cf-7e16-b5e1-dd0de4ce02fa", "type": "webhookSubscription", "attributes": { "url": "https://example.com/webhook", "secretKey": "a2e2c04657b924390d2a2623439c65734d07e0f8", "enabled": true, "scopeType": "organisation", "scopeName": "Test Organisation", "subscribedEvents": [ "passInstalled", "passRemoved" ] } } ], "meta": { "totalCount": 1, "resultsPerPage": 10, "currentPage": 1, "totalPages": 1 }, "links": { "first": null, "prev": null, "next": null, "last": null } } } } }, "401": { "description": "Unauthorized - Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errors" } } } } } } }, "/api/v1/pass-templates": { "post": { "security": [ { "api_key": [] } ], "tags": [ "Pass Templates" ], "summary": "Create Pass Template", "description": "Create a new pass template", "operationId": "createPassTemplate", "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/passTemplate" }, { "properties": { "passTemplate": { "type": "object", "additionalProperties": true, "properties": { "templateType": { "description": "Type of pass template, determines the design and functionality of the pass", "$ref": "#/components/schemas/passType" }, "barcode": { "description": "Barcode for a pass template", "type": "object", "properties": { "enabled": { "type": "boolean", "description": "If true, barcode will be added to the pass" }, "type": { "type": "string", "description": "Barcode type", "enum": [ "qr", "code128", "aztec", "pdf417" ] }, "source": { "type": "string", "description": "Source of the barcode", "enum": [ "custom", "uuid", "extId" ] }, "value": { "type": "string", "description": "Barcode value. You can leave it blank if the value will be dynamically set in the pass, but you can also provide a default.\n\nYou can make the value dynamic using the `%{passData.xyz}` syntax (e.g., `Hello, %{passData.extId}`). Currently, only `%{passData.extId}` and `%{passData.uuid}` are supported.\n\nIf `source` is set to `extId` or `uuid`, the value will be automatically populated and can be left blank.", "example": "abc123" }, "displayText": { "type": "boolean", "description": "If true, display the barcode value as text on the pass" } }, "required": [ "enabled", "type", "source" ] } }, "required": [ "templateType" ] } } } ] }, "example": { "passTemplate": { "name": "PassEntry Supermarket", "templateType": "generic", "defaultLanguage": "en", "centralTitle": "PassEntry Supermarket", "notificationHeader": "PassEntry Supermarket", "description": "PassEntry Supermarket", "colors": { "background": "#dbdbdb", "label": "#000000", "text": "#000000" }, "images": { "banner": "https://example.com/images/banner.jpg", "logo": "https://example.com/images/logo.jpg", "icon": "https://example.com/images/icon.jpg", "watermark": { "color": "light", "position": "bottomRight" } }, "fields": { "header": { "one": { "id": "points", "label": "Points", "defaultValue": "0", "localisation": { "fr": { "label": "Points", "defaultValue": "0" }, "is": { "label": "Stig", "defaultValue": "0" } } } }, "central": { "one": { "id": "name", "label": "Central", "defaultValue": "Sample Name", "localisation": { "fr": { "label": "Central", "defaultValue": "Exemple de Nom" }, "is": { "label": "Miðja", "defaultValue": "Sýnishorn Nafn" } } } }, "details": { "one": { "id": "name", "label": "Name", "defaultValue": "Jane Doe", "localisation": { "fr": { "label": "Nom", "defaultValue": "Jeanne Dupont" }, "is": { "label": "Nafn", "defaultValue": "Jóna Jónsdóttir" } } }, "two": { "id": "discount", "label": "Discount", "defaultValue": "15%", "localisation": { "fr": { "label": "Réduction", "defaultValue": "15%" }, "is": { "label": "Afsláttur", "defaultValue": "15%" } } }, "three": { "id": "tier", "label": "Membership Tier", "defaultValue": "Silver", "localisation": { "fr": { "label": "Niveau de fidélité", "defaultValue": "Argent" }, "is": { "label": "Aðildarstig", "defaultValue": "Silfur" } } } }, "back": { "one": { "id": "email", "label": "Email", "defaultValue": "jane.doe@example.com", "localisation": { "fr": { "label": "E-mail", "defaultValue": "jeanne.dupont@exemple.com" }, "is": { "label": "Netfang", "defaultValue": "jona.jonsdottir@daemi.is" } } } } }, "appLinking": { "apple": { "appStoreUrl": [ "https://apps.apple.com/gb/app/whatsapp-messenger/id310633997" ] }, "google": { "app": { "playStoreUrl": "https://play.google.com/store/apps/details?id=com.whatsapp" }, "displayText": { "text": "Click here for more!" } } }, "barcode": { "enabled": true, "type": "qr", "source": "custom", "value": "123abcd" }, "locations": [ { "name": "Venue", "latitude": 51.54321132456805, "longitude": -0.022901231803803924, "radius": 100, "message": "Welcome to the venue" } ], "beacons": [ { "name": "Beacon", "proximityUuid": "123e4567-e89b-12d3-a456-426614174000", "major": 1, "minor": 1, "message": "Welcome to the venue" } ] } } } } }, "responses": { "202": { "description": "Succesful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/serializedProcessingPassTemplate" } } } }, "400": { "description": "Error: Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errors" } } } }, "401": { "description": "Error: Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errors" } } } }, "404": { "description": "Error: Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errors" } } } } } }, "get": { "summary": "List Pass Templates", "description": "List all pass templates", "tags": [ "Pass Templates" ], "operationId": "listPassTemplates", "security": [ { "api_key": [] } ], "parameters": [ { "name": "perPage", "in": "query", "description": "Record limiter per page. Default is 10, max is 100", "required": false, "schema": { "type": "integer", "default": 10, "maximum": 100 } }, { "name": "page", "in": "query", "description": "Page number. Default is 1", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "templateType", "in": "query", "description": "Filter by template type", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Filter by lifecycle status. Accepts a comma-separated list of one or more values. Defaults to `published` only when omitted.", "required": false, "schema": { "type": "string", "example": "draft,published", "enum": [ "draft", "published", "draft,published" ] } }, { "name": "fields", "in": "query", "schema": { "type": "string", "example": "name,description,templateType" }, "description": "Returns a partial response (Sparse fieldset) per record, instead of the whole record. Set one or many comma separated record attributes", "required": false } ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/serializedPassTemplate" }, { "$ref": "#/components/schemas/serializedProcessingPassTemplate" } ] } }, "meta": { "type": "object", "properties": { "totalCount": { "type": "integer", "description": "Total count" }, "resultsPerPage": { "type": "integer" }, "currentPage": { "type": "integer" }, "totalPages": { "type": "integer" } } }, "links": { "type": "object", "properties": { "first": { "type": "string" }, "prev": { "type": "string" }, "next": { "type": "string" }, "last": { "type": "string" } } } } }, "example": { "data": [ { "id": "19cb334f9696e64e10e7759f0", "type": "passTemplate", "attributes": { "name": "PassEntry Supermarket", "templateType": "generic", "defaultLanguage": "en", "centralTitle": "PassEntry Supermarket", "notificationHeader": "PassEntry Supermarket", "status": "published", "colors": { "background": "#EFEFEF", "label": "#FF8477", "text": "#29323A" }, "images": { "banner": "https://example.com/banner.png", "logo": "https://example.com/logo.png", "icon": "https://example.com/icon.png" }, "fields": { "header": { "one": { "id": "membership_tier", "label": "Membership Tier", "defaultValue": "Gold" } }, "central": { "one": { "id": "membership_tier", "label": "Membership Tier", "defaultValue": "Gold" } }, "details": { "one": { "id": "membership_tier", "label": "Membership Tier", "defaultValue": "Gold" } }, "back": { "one": { "id": "membership_tier", "label": "Membership Tier", "defaultValue": "Gold" } } } } } ], "meta": { "totalCount": 1, "resultsPerPage": 10, "currentPage": 1, "totalPages": 1 }, "links": { "first": null, "prev": null, "next": null, "last": null } } } } } } } }, "/api/v1/pass-templates/{id}": { "get": { "summary": "Show Pass Template", "tags": [ "Pass Templates" ], "operationId": "showPassTemplate", "security": [ { "api_key": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Pass Template UUID", "schema": { "type": "string" } }, { "name": "fields", "in": "query", "schema": { "type": "string", "example": "name,description,templateType" }, "description": "Returns a partial response (Sparse fieldset), instead of the whole record. Set one or many comma separated record attributes", "required": false } ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "oneOf": [ { "$ref": "#/components/schemas/serializedPassTemplate" }, { "$ref": "#/components/schemas/serializedProcessingPassTemplate" } ] } } }, "example": { "data": { "id": "19cb334f9696e64e10e7759f0", "type": "passTemplate", "attributes": { "name": "PassEntry Supermarket", "templateType": "generic", "defaultLanguage": "en", "centralTitle": "PassEntry Supermarket", "notificationHeader": "PassEntry Supermarket", "status": "published", "colors": { "background": "#EFEFEF", "label": "#FF8477", "text": "#29323A" }, "images": { "banner": "https://example.com/banner.png", "logo": "https://example.com/logo.png", "icon": "https://example.com/icon.png" }, "fields": { "header": { "one": { "id": "membership_tier", "label": "Membership Tier", "defaultValue": "Gold" } }, "central": { "one": { "id": "membership_tier", "label": "Membership Tier", "defaultValue": "Gold" } }, "details": { "one": { "id": "membership_tier", "label": "Membership Tier", "defaultValue": "Gold" } }, "back": { "one": { "id": "membership_tier", "label": "Membership Tier", "defaultValue": "Gold" } } } } } } } } }, "401": { "description": "Error: Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errors" } } } }, "404": { "description": "Error: Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errors" } } } } } }, "patch": { "summary": "Update Pass Template", "tags": [ "Pass Templates" ], "operationId": "updatePassTemplate", "security": [ { "api_key": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Pass Template UUID", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/passTemplate" }, { "type": "object", "properties": { "passTemplate": { "type": "object", "properties": { "transitType": { "$ref": "#/components/schemas/passTemplateTransitType" }, "nfc": { "$ref": "#/components/schemas/nfcUpdate" }, "barcode": { "$ref": "#/components/schemas/barcodeUpdate" }, "fields": { "type": "object", "properties": { "header": { "type": "object", "properties": { "one": { "$ref": "#/components/schemas/fieldUpdate" }, "two": { "$ref": "#/components/schemas/fieldUpdate" } } }, "central": { "type": "object", "properties": { "one": { "$ref": "#/components/schemas/fieldUpdate" }, "two": { "$ref": "#/components/schemas/fieldUpdate" } } }, "details": { "type": "object", "properties": { "one": { "$ref": "#/components/schemas/fieldUpdate" }, "two": { "$ref": "#/components/schemas/fieldUpdate" }, "three": { "$ref": "#/components/schemas/fieldUpdate" }, "four": { "$ref": "#/components/schemas/fieldUpdate" }, "five": { "$ref": "#/components/schemas/fieldUpdate" }, "six": { "$ref": "#/components/schemas/fieldUpdate" } } }, "back": { "type": "object", "properties": { "one": { "$ref": "#/components/schemas/fieldUpdate" }, "two": { "$ref": "#/components/schemas/fieldUpdate" }, "three": { "$ref": "#/components/schemas/fieldUpdate" }, "four": { "$ref": "#/components/schemas/fieldUpdate" }, "five": { "$ref": "#/components/schemas/fieldUpdate" }, "six": { "$ref": "#/components/schemas/fieldUpdate" } } } } } } } } } ] }, "example": { "passTemplate": { "name": "PassEntry Coffee Shop", "colors": { "background": "#EEEEEE" }, "images": { "watermark": { "color": "dark", "position": "topLeft" } }, "appLinking": { "apple": { "appStoreUrl": [] } }, "beacons": [] } } } } }, "responses": { "200": { "description": "Successful", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/serializedPassTemplate" }, { "$ref": "#/components/schemas/serializedProcessingPassTemplate" } ] }, "example": { "data": { "id": "19cb334f9696e64e10e7759f0", "type": "passTemplate", "attributes": { "name": "PassEntry Supermarket", "templateType": "generic", "defaultLanguage": "en", "centralTitle": "PassEntry Supermarket", "notificationHeader": "PassEntry Supermarket", "status": "published", "colors": { "background": "#EFEFEF", "label": "#FF8477", "text": "#29323A" }, "images": { "banner": "https://example.com/banner.png", "logo": "https://example.com/logo.png", "icon": "https://example.com/icon.png", "watermark": { "color": "light", "position": "topLeft" } }, "fields": { "header": { "one": { "id": "membership_tier", "label": "Membership Tier", "defaultValue": "Gold" } }, "central": { "one": { "id": "membership_tier", "label": "Membership Tier", "defaultValue": "Gold" } }, "details": { "one": { "id": "membership_tier", "label": "Membership Tier", "defaultValue": "Gold" } }, "back": { "one": { "id": "membership_tier", "label": "Membership Tier", "defaultValue": "Gold" } } } } } } } } }, "202": { "description": "Successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/serializedProcessingPassTemplate" } } } }, "400": { "description": "Error: Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errors" } } } }, "401": { "description": "Error: Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errors" } } } }, "404": { "description": "Error: Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errors" } } } } } } }, "/api/v1/passes": { "post": { "summary": "Create pass", "tags": [ "Passes" ], "operationId": "createPass", "security": [ { "api_key": [] } ], "parameters": [ { "name": "passTemplate", "in": "query", "required": true, "description": "Identifies the pass template to use", "schema": { "type": "string" } }, { "name": "extId", "in": "query", "description": "External ID used to identify the pass. Optional", "schema": { "type": "string" } }, { "name": "includePassDesign", "in": "query", "schema": { "type": "boolean" }, "description": "If true, includes the pass design in the response", "required": false }, { "name": "includeLocations", "in": "query", "schema": { "type": "boolean" }, "description": "If true, includes the locations in the response if any are present", "required": false }, { "name": "includeBeacons", "in": "query", "schema": { "type": "boolean" }, "description": "If true, includes the beacons in the response if any are present", "required": false }, { "name": "includePassSource", "in": "query", "schema": { "type": "string", "enum": [ "apple", "google" ] }, "description": "Used when delivering the pass directly to the passholder, without using PassEntry's download page.\n Choose one of Apple/Google, includes the pass source in the response.\n The passSource object is only included if the pass is not currently 'active'\n ", "required": false } ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "example": { "data": { "id": "33b680b7a5460e6cd4646dfd2c1a8c33a6fbfa5c", "type": "pass", "attributes": { "downloadUrl": "https://www.example.com?pass=33b680b7a5460e6cd4646dfd2c1a8c33a6fbfa5c", "passType": "generic", "createdAt": "2022-06-05T10:06:53Z", "status": "issued", "extId": "123", "passTemplateUuid": "2e2d7ee8c306e8f0223dbdc1", "passTemplateName": "PassEntry Ticketing", "nfc": "33b680b7a5460e6cd4646dfd2c1a8c33a6fbfa5c", "barcode": { "enabled": true, "type": "qr", "source": "custom", "value": "123abcd", "displayText": true }, "passContent": { "nfc": { "enabled": true }, "fullName": { "value": "Jane Smith" }, "website": "https://passentry.com", "barcode": { "enabled": true, "type": "qr", "source": "custom", "value": "123abcd", "displayText": true } } } } }, "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/serializedPassObject" } } } } } }, "400": { "description": "Error: Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errors" } } } }, "401": { "description": "Error: Unauthorized", "content": { "application/json": { "example": { "errors": [ "Access denied" ] }, "schema": { "$ref": "#/components/schemas/errors" } } } }, "404": { "description": "Error: Not Found", "content": { "application/json": { "example": { "errors": [ "Pass template with provided uuid not found" ] }, "schema": { "$ref": "#/components/schemas/errors" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/createPassRequest" }, { "properties": { "pass": { "properties": { "barcode": { "required": [ "enabled", "type", "source" ] } } } } } ] }, "examples": { "0": { "summary": "Create pass", "value": { "pass": { "nfc": { "enabled": true }, "fullName": { "value": "Jane Smith" }, "website": "https://passentry.com", "barcode": { "enabled": true, "type": "qr", "source": "custom", "value": "123abcd", "displayText": true } }, "locations": [ { "name": "Venue", "latitude": 51.54321132456805, "longitude": -0.022901231803803924, "radius": 100, "message": "Welcome to the venue" } ] } }, "1": { "summary": "Create pass with account binding", "value": { "pass": { "nfc": { "enabled": true }, "fullName": { "value": "Jane Smith" }, "website": "https://passentry.com" }, "binding": { "email": "user@gmail.com", "learnMoreUrl": "https://support.example.com/pass-binding" } } } } } } } }, "get": { "summary": "List passes", "tags": [ "Passes" ], "operationId": "listPasses", "security": [ { "api_key": [] } ], "parameters": [ { "name": "perPage", "in": "query", "description": "Record limiter per page. Default is 100", "required": false, "schema": { "type": "integer" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "issued", "active", "removed", "deactivated", "nullified" ] }, "description": "Filter passes by status. Accepts single status value.", "required": false }, { "name": "status[]", "in": "query", "schema": { "type": "array", "items": { "type": "string", "enum": [ "issued", "active", "removed", "deactivated", "nullified" ] } }, "description": "Filter passes by multiple statuses. Use array notation: status[]=active&status[]=issued", "required": false }, { "name": "deviceType", "in": "query", "schema": { "type": "string", "enum": [ "android", "iphone" ] }, "description": "Filter passes by device type", "required": false }, { "name": "groupTag", "in": "query", "schema": { "type": "string" }, "description": "Filter passes by group tag", "required": false }, { "name": "groupTags[]", "in": "query", "schema": { "type": "array", "items": { "type": "string" } }, "description": "Filter passes by multiple group tags. Use array notation: groupTags[]=tag1&groupTags[]=tag2", "required": false }, { "name": "extIdPrefix", "in": "query", "schema": { "type": "string" }, "description": "Filter passes by external ID prefix. Example: '123456' will match '123456' and '1234567890'. Case sensitive.", "required": false }, { "name": "passTemplateUuid", "in": "query", "schema": { "type": "string" }, "description": "Filter passes by pass template UUID", "required": false }, { "name": "passTemplateName", "in": "query", "schema": { "type": "string" }, "description": "Filter passes by pass template name. Must be URL encoded", "required": false }, { "name": "eventUuid", "in": "query", "schema": { "type": "string" }, "description": "Filter passes by event UUID", "required": false }, { "name": "eventName", "in": "query", "schema": { "type": "string" }, "description": "Filter passes by event name. Must be URL encoded", "required": false }, { "name": "createdAfter", "in": "query", "schema": { "type": "string" }, "description": "Returns passes created after given datetime. Format is ISO 8601", "required": false }, { "name": "createdBefore", "in": "query", "schema": { "type": "string" }, "description": "Returns passes created before given datetime. Format is ISO 8601. Can be combined with createdBefore parameter", "required": false }, { "name": "fields", "in": "query", "schema": { "type": "string" }, "description": "Returns a partial response (Sparse fieldset) per record, instead of the whole record. Set one or many comma separated record attributes", "required": false }, { "name": "includePassDesign", "in": "query", "schema": { "type": "boolean" }, "description": "If true, includes the pass design in the response", "required": false }, { "name": "includeLocations", "in": "query", "schema": { "type": "boolean" }, "description": "If true, includes the locations in the response if any are present", "required": false }, { "name": "includeBeacons", "in": "query", "schema": { "type": "boolean" }, "description": "If true, includes the beacons in the response if any are present", "required": false }, { "name": "includeBinding", "in": "query", "schema": { "type": "boolean" }, "description": "If true, includes the account binding data in the response for passes that have binding configured.", "required": false }, { "name": "includeNullified", "in": "query", "schema": { "type": "boolean" }, "description": "If true, includes nullified passes in the response. By default, nullified passes are excluded from list results.", "required": false } ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "example": { "data": [ { "id": "237f0526-b2aa-4dd1-884b-ed49abbd7447", "type": "pass", "attributes": { "downloadUrl": "https://www.example.com?pass=237f0526-b2aa-4dd1-884b-ed49abbd7447", "passType": "generic", "createdAt": "2022-01-08T00:00:00Z", "status": "issued", "extId": "d994dfcf8b6d0b0a3267", "passTemplateUuid": "2e2d7ee8c306e8f0223dbdc1", "passTemplateName": "PassEntry Ticketing", "nfc": null, "barcode": {}, "passContent": { "fullName": "John Johnson" } } }, { "id": "237f0526-b2aa-4dd1-884b-ed49abbd7446", "type": "pass", "attributes": { "downloadUrl": "https://www.example.com?pass=237f0526-b2aa-4dd1-884b-ed49abbd7446", "passType": "generic", "createdAt": "2022-01-07T00:00:00Z", "status": "issued", "extId": "d994dfcf8b6d0b0a3266", "passTemplateUuid": "2e2d7ee8c306e8f0223dbdc1", "passTemplateName": "PassEntry Ticketing", "nfc": null, "barcode": {}, "passContent": { "fullName": "John Johnson" } } }, { "id": "237f0526-b2aa-4dd1-884b-ed49abbd7445", "type": "pass", "attributes": { "downloadUrl": "https://www.example.com?pass=237f0526-b2aa-4dd1-884b-ed49abbd7445", "passType": "generic", "createdAt": "2022-01-06T00:00:00Z", "status": "issued", "extId": "d994dfcf8b6d0b0a3265", "passTemplateUuid": "2e2d7ee8c306e8f0223dbdc1", "passTemplateName": "PassEntry Ticketing", "nfc": null, "barcode": {}, "passContent": { "fullName": "John Johnson" } } }, { "id": "237f0526-b2aa-4dd1-884b-ed49abbd7444", "type": "pass", "attributes": { "downloadUrl": "https://www.example.com?pass=237f0526-b2aa-4dd1-884b-ed49abbd7444", "passType": "generic", "createdAt": "2022-01-05T00:00:00Z", "status": "issued", "extId": "d994dfcf8b6d0b0a3264", "passTemplateUuid": "2e2d7ee8c306e8f0223dbdc1", "passTemplateName": "PassEntry Ticketing", "nfc": null, "barcode": {}, "passContent": { "fullName": "John Johnson" } } }, { "id": "237f0526-b2aa-4dd1-884b-ed49abbd7443", "type": "pass", "attributes": { "downloadUrl": "https://www.example.com?pass=237f0526-b2aa-4dd1-884b-ed49abbd7443", "passType": "generic", "createdAt": "2022-01-04T00:00:00Z", "status": "issued", "extId": "d994dfcf8b6d0b0a3263", "passTemplateUuid": "2e2d7ee8c306e8f0223dbdc1", "passTemplateName": "PassEntry Ticketing", "nfc": null, "barcode": {}, "passContent": { "fullName": "John Johnson" } } } ], "meta": { "totalCount": 8, "resultsPerPage": 5, "currentPage": 1, "totalPages": 2 }, "links": { "first": null, "prev": null, "next": "/api/v1/passes?page=2&perPage=5", "last": "/api/v1/passes?page=2&perPage=5" } }, "schema": { "$ref": "#/components/schemas/serializedPassesList" } } } }, "400": { "description": "Error: Bad Request", "content": { "application/json": { "example": { "errors": [ "Invalid date format: foo foo. Please check your request and try again." ] }, "schema": { "$ref": "#/components/schemas/errors" } } } }, "401": { "description": "Error: Unauthorized", "content": { "application/json": { "example": { "errors": [ "Access denied" ] }, "schema": { "$ref": "#/components/schemas/errors" } } } } } } }, "/api/v1/passes/{id}": { "patch": { "summary": "Update pass", "tags": [ "Passes" ], "operationId": "updatePass", "security": [ { "api_key": [] } ], "parameters": [ { "name": "id", "in": "path", "description": "Pass UUID or External ID", "required": true, "schema": { "type": "string" } }, { "name": "includePassDesign", "in": "query", "schema": { "type": "boolean" }, "description": "If true, includes the pass design in the response", "required": false }, { "name": "includeLocations", "in": "query", "schema": { "type": "boolean" }, "description": "If true, includes the locations in the response if any are present", "required": false }, { "name": "includeBeacons", "in": "query", "schema": { "type": "boolean" }, "description": "If true, includes the beacons in the response if any are present", "required": false } ], "responses": { "200": { "description": "Successful", "headers": { "X-Notification-Status": { "schema": { "$ref": "#/components/schemas/notificationStatusHeader" } } }, "content": { "application/json": { "example": { "data": { "id": "d2ac8d95-6914-4cac-957c-2a5ccf534390", "type": "pass", "attributes": { "downloadUrl": "https://www.example.com?pass=d2ac8d95-6914-4cac-957c-2a5ccf534390", "passType": "generic", "createdAt": "2022-01-01T00:00:00Z", "status": "issued", "extId": "b1985e420025dd92ccf2", "passTemplateUuid": "2e2d7ee8c306e8f0223dbdc1", "passTemplateName": "PassEntry Ticketing", "nfc": null, "barcode": {}, "latestMessage": "Your pass details have been updated. Click to show pass", "passContent": { "fullName": { "value": "Jane Roberts" }, "nfc": { "enabled": false } } } }, "meta": { "notifications": { "status": "notDelivered", "message": "Pass has not been added to the wallet" } } }, "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/serializedPassObject" }, "meta": { "$ref": "#/components/schemas/notificationMeta" } } } } } }, "400": { "description": "Error: Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errors" } } } }, "401": { "description": "Error: Unauthorized", "content": { "application/json": { "example": { "errors": [ "Access denied" ] }, "schema": { "$ref": "#/components/schemas/errors" } } } }, "404": { "description": "Error: Not Found", "content": { "application/json": { "example": { "errors": [ "Pass with provided id not found" ] }, "schema": { "$ref": "#/components/schemas/errors" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pass" }, "examples": { "0": { "summary": "Update pass", "value": { "pass": { "nfc": { "enabled": false }, "fullName": { "value": "Jane Roberts" } }, "message": "Your pass details have been updated. Click to show pass", "locations": [ { "name": "Venue", "latitude": 51.54321132456805, "longitude": -0.022901231803803924, "radius": 100, "message": "Welcome to the venue" } ] } } } } } } }, "get": { "summary": "Get pass", "tags": [ "Passes" ], "operationId": "getPass", "security": [ { "api_key": [] } ], "parameters": [ { "name": "id", "in": "path", "description": "Pass UUID or External ID", "required": true, "schema": { "type": "string" } }, { "name": "includePassDesign", "in": "query", "schema": { "type": "boolean" }, "description": "If true, includes the pass design in the response", "required": false }, { "name": "includeLocations", "in": "query", "schema": { "type": "boolean" }, "description": "If true, includes the locations in the response if any are present", "required": false }, { "name": "includeBeacons", "in": "query", "schema": { "type": "boolean" }, "description": "If true, includes the beacons in the response if any are present", "required": false }, { "name": "includePassSource", "in": "query", "schema": { "type": "string", "enum": [ "apple", "google" ] }, "description": "Used when delivering the pass directly to the passholder, without using PassEntry's download page.\n Choose one of Apple/Google, includes the pass source in the response.\n The passSource object is only included if the pass is not currently 'active'\n ", "required": false } ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "example": { "data": { "id": "d2ac8d95-6914-4cac-957c-2a5ccf534390", "type": "pass", "attributes": { "downloadUrl": "https://www.example.com?pass=d2ac8d95-6914-4cac-957c-2a5ccf534390", "passType": "generic", "createdAt": "2022-01-01T00:00:00Z", "status": "issued", "extId": "b1985e420025dd92ccf2", "passTemplateUuid": "2e2d7ee8c306e8f0223dbdc1", "passTemplateName": "PassEntry Ticketing", "nfc": null, "barcode": {}, "passContent": { "fullName": "John Johnson" } } } }, "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/serializedPassObject" } } } } } }, "401": { "description": "Error: Unauthorized", "content": { "application/json": { "example": { "errors": [ "Access denied" ] }, "schema": { "$ref": "#/components/schemas/errors" } } } }, "404": { "description": "Error: Not Found", "content": { "application/json": { "example": { "errors": [ "Pass with provided id not found" ] }, "schema": { "$ref": "#/components/schemas/errors" } } } } } } }, "/api/v1/passes/batch": { "post": { "summary": "Create pass batch", "description": "Create passes in bulk via a CSV file. \n\n For more details, see the [Batch Pass Creation](/documentation/bulk-operations/batch-pass-creation/guide) documentation.", "tags": [ "Batches" ], "operationId": "createPassBatch", "security": [ { "api_key": [] } ], "parameters": [], "responses": { "202": { "description": "Accepted", "content": { "application/json": { "example": { "data": { "id": "999b774f-02ae-4931-94c6-596f614ef4f4", "type": "passCreation", "attributes": { "name": "Batch: Pass Creation 2025-11-21 15:34:02", "status": "processing", "passTemplateName": "PassEntry Ticketing", "passTemplateNameId": "acbb27e9cfb4e8f62f8cb999" } }, "links": { "self": "https://api.passentry.com/api/v1/batches/999b774f-02ae-4931-94c6-596f614ef4f4" } }, "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/serializedPassCreationBatch" }, "links": { "$ref": "#/components/schemas/batchSelfLink" } } } } } }, "401": { "description": "Error: Unauthorized", "content": { "application/json": { "example": { "errors": [ "Access denied" ] }, "schema": { "$ref": "#/components/schemas/errors" } } } } }, "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/createPassCreationBatchMultipart" }, "examples": { "Batch Passes - valid.csv": { "summary": "Batch Passes - valid.csv", "value": { "csv": "[binary file content not shown]", "passTemplate": "bf9d5cc29114" } } } } }, "required": true, "description": "Batch" } } }, "/api/v1/passes/batch/update": { "post": { "summary": "Update pass batch", "description": "Update passes in bulk via a CSV file. \n\n", "tags": [ "Batches" ], "operationId": "updatePassBatch", "security": [ { "api_key": [] } ], "parameters": [], "responses": { "202": { "description": "Accepted", "content": { "application/json": { "example": { "data": { "id": "999b774f-02ae-4931-94c6-596f614ef4f4", "type": "passUpdate", "attributes": { "name": "Batch: Pass Update 2025-11-21 15:34:02", "status": "validating", "tag": "summerPromotion", "passTemplateName": "PassEntry Loyalty", "passTemplateNameId": "acbb27e9cfb4e8f62f8cb999", "scheduledAt": "2024-01-01T00:00:00Z", "errorsCsvUrl": "https://example.com/errors.csv", "totalCount": 1000, "progress": { "total": 1000, "processed": 800, "pending": 200 } } }, "links": { "self": "https://api.passentry.com/api/v1/batches/999b774f-02ae-4931-94c6-596f614ef4f4" } }, "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/serializedPassUpdateBatch" }, "links": { "$ref": "#/components/schemas/batchSelfLink" } } } } } }, "401": { "description": "Error: Unauthorized", "content": { "application/json": { "example": { "errors": [ "Access denied" ] }, "schema": { "$ref": "#/components/schemas/errors" } } } } }, "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/createPassUpdateBatchMultipart" }, "examples": { "Batch Passes Update - valid.csv": { "summary": "Batch Passes Update - valid.csv", "value": { "csv": "[binary file content not shown]", "tag": "summerPromotion", "name": "Summer Promotion Update #1", "scheduledAt": "2030-03-31T13:16:26Z" } } } } }, "required": true, "description": "Batch Update" } } }, "/api/v1/readers/{id}": { "get": { "summary": "Get reader", "tags": [ "Readers" ], "operationId": "getReader", "security": [ { "api_key": [] } ], "parameters": [ { "name": "id", "in": "path", "description": "Reader ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "example": { "data": { "id": "south-gate-1", "type": "reader", "attributes": { "name": "South Gate Reader", "readerType": "PassentryReader", "loggedIn": false, "qrEnabled": false, "mifareClassicNfcEnabled": false, "scanEnabled": true, "redeemEnabled": false, "addPointsEnabled": false, "ndefTagScanningEnabled": false, "lastSeenAt": "2020-03-13T13:00:00Z" } } }, "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/serializedReaderObject" } } } } } }, "401": { "description": "Error: Unauthorized", "content": { "application/json": { "example": { "errors": [ "Access denied" ] }, "schema": { "$ref": "#/components/schemas/errors" } } } }, "404": { "description": "Error: Not Found", "content": { "application/json": { "example": { "errors": [ "Reader not found" ] }, "schema": { "$ref": "#/components/schemas/errors" } } } } } }, "patch": { "summary": "Update reader", "tags": [ "Readers" ], "operationId": "updateReader", "security": [ { "api_key": [] } ], "parameters": [ { "name": "id", "in": "path", "description": "Reader ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful", "content": { "application/json": { "examples": { "Example": { "value": { "data": { "id": "south-gate-3", "type": "reader", "attributes": { "name": "South Gate Reader", "readerType": "PassentryReader", "loggedIn": false, "qrEnabled": true, "mifareClassicNfcEnabled": true, "scanEnabled": false, "redeemEnabled": true, "addPointsEnabled": false, "ndefTagScanningEnabled": false, "lastSeenAt": "2020-03-13T13:00:00Z" } } } } }, "schema": { "$ref": "#/components/schemas/serializedReaderObject" } } } }, "401": { "description": "Error: Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errors" } } } }, "422": { "description": "Error: Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errors" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/updateReader" }, "examples": { "0": { "summary": "Update reader", "value": { "reader": { "id": "south-gate-3", "password": "Test789!", "mifareClassicNfcEnabled": true, "scanEnabled": false, "redeemEnabled": true, "qrEnabled": true } } } } } } } } }, "/api/v1/entities/{entity_id}/readers": { "post": { "summary": "Create reader", "tags": [ "Readers" ], "operationId": "createReader", "security": [ { "api_key": [] } ], "parameters": [ { "name": "entity_id", "in": "path", "description": "entity_id", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "Created", "content": { "application/json": { "examples": { "Example": { "value": { "data": { "id": "east-gate-1", "type": "reader", "attributes": { "name": "East Gate Reader", "readerType": "PassentryReader", "loggedIn": false, "qrEnabled": true, "mifareClassicNfcEnabled": false, "scanEnabled": true, "redeemEnabled": false, "addPointsEnabled": false, "ndefTagScanningEnabled": false } } } } }, "schema": { "$ref": "#/components/schemas/serializedReaderObject" } } } }, "401": { "description": "Error: Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errors" } } } }, "422": { "description": "Error: Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errors" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createReader" } } } } } }, "/api/v1/entities/{entity_id}/readerConfiguration": { "get": { "summary": "Get reader configuration", "tags": [ "Readers" ], "operationId": "getReaderConfiguration", "security": [ { "api_key": [] } ], "parameters": [ { "name": "entity_id", "in": "path", "description": "entity_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "example": { "data": { "id": "defd0867", "type": "readerConfiguration", "attributes": { "nfcPrivateKey": "-----BEGIN EC PRIVATE KEY-----\n PRIVATE KEY\n -----END EC PRIVATE KEY-----", "googleCollectorId": "95415519", "applePassTypeId": "pass.com.test.test", "googleKeyVersion": 1, "readerConfigurationApiKey": "uwMGo/K/8SNxEznuFDZhe/lZLdk0ruGgikh1fGOGXh8KV1cdGU7vDzl8Dit0MEBhuF7sRhec2aCU9b1t3WiZDg==", "validationConfiguration": { "validationType": "internal" } } } }, "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/serializedReaderConfigurationObject" } } } } } }, "401": { "description": "Error: Unauthorized", "content": { "application/json": { "example": { "errors": [ "Access denied" ] }, "schema": { "$ref": "#/components/schemas/errors" } } } }, "404": { "description": "Error: Not Found", "content": { "application/json": { "example": { "errors": [ "Entity not found" ] }, "schema": { "$ref": "#/components/schemas/errors" } } } } } } }, "/api/v1/scans": { "post": { "summary": "Create scan", "tags": [ "Scans" ], "operationId": "createScan", "security": [ { "api_key": [] } ], "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "examples": { "Example": { "value": { "validationResponse": { "status": "successful", "statusDetail": "", "readerInstructions": { "message": "10 points added to your balance. Current balance: 25" }, "loyalty": { "balanceChange": "10", "updatedBalance": "25", "operation": "add" } }, "scanInfo": { "scanId": "019488b8-c2fc-7b5b-b5b4-deb2b7f33bdd", "scanType": "barcode", "scanValue": "7882e98b-0eba-4625-9223-5221eb8dad7f", "validationType": "internalValidation", "status": "successful", "statusDetail": "", "scannedAt": "2025-01-21T11:56:37Z", "passId": "7882e98b-0eba-4625-9223-5221eb8dad7f", "passExtId": "4312d68fd106e3e6dd15", "readerId": "south-gate-1" } } } }, "schema": { "$ref": "#/components/schemas/internalValidationResponse" } } } }, "401": { "description": "Error: Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errors" } } } }, "422": { "description": "Error: Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errors" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/createScan" }, "examples": { "0": { "summary": "Create scan", "value": { "scan": { "readerId": "south-gate-1", "passId": "7882e98b-0eba-4625-9223-5221eb8dad7f", "scanType": "barcode", "loyalty": { "balance": 10 } } } } } } } } }, "get": { "summary": "List scans", "tags": [ "Scans" ], "operationId": "listScans", "security": [ { "api_key": [] } ], "parameters": [ { "name": "perPage", "in": "query", "description": "Record limiter per page. Default is 100", "required": false, "schema": { "type": "integer" } }, { "name": "entity", "in": "query", "description": "Filter by entity uuid", "required": false, "schema": { "type": "string" } }, { "name": "readerId", "in": "query", "description": "Filter by reader uuid", "required": false, "schema": { "type": "string" } }, { "name": "passId", "in": "query", "description": "Filter by pass uuid or ext_id", "required": false, "schema": { "type": "string" } }, { "name": "validationType", "in": "query", "description": "Filter by validation type", "required": false, "schema": { "oneOf": [ { "type": "string", "enum": [ "internalValidation", "externalValidation" ] } ] } }, { "name": "scanType", "in": "query", "description": "Filter by scan type", "required": false, "schema": { "oneOf": [ { "type": "string", "enum": [ "nfc", "barcode" ] } ] } }, { "name": "status", "in": "query", "description": "Filter by status", "required": false, "schema": { "oneOf": [ { "type": "string", "enum": [ "successful", "failed" ] } ] } }, { "name": "eventId", "in": "query", "description": "Filter by event uuid", "required": false, "schema": { "type": "string" } }, { "name": "passTemplateName", "in": "query", "description": "Filter by pass template name", "required": false, "schema": { "type": "string" } }, { "name": "groupTag", "in": "query", "description": "Filter by group tag", "required": false, "schema": { "type": "string" } }, { "name": "groupTags[]", "in": "query", "description": "Filter by multiple group tags. Use array notation: groupTags[]=tag1&groupTags[]=tag2", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "createdAfter", "in": "query", "description": "Filter by created after. Format: ISO 8601", "required": false, "schema": { "type": "string" } }, { "name": "createdBefore", "in": "query", "description": "Filter by created before. Format: ISO 8601", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "example": { "data": [ { "id": "0195ebee-62d2-7a98-83b7-1fe98465a401", "type": "scan", "attributes": { "scanType": "barcode", "scanValue": "factory_scan_value", "validationType": "internalValidation", "status": "failed", "statusDetail": "Pass is not active", "scannedAt": "2025-01-13T13:00:00Z" }, "relationships": { "pass": { "data": { "id": "7882e98b-0eba-4625-9223-5221eb8dad7f", "type": "pass" } }, "reader": { "data": { "id": "south-gate-1", "type": "reader" } } } }, { "id": "0195ebee-62d1-72b3-bd35-a101b24878a9", "type": "scan", "attributes": { "scanType": "nfc", "scanValue": "factory_scan_value", "validationType": "internalValidation", "status": "failed", "statusDetail": "Pass is not active", "scannedAt": "2025-01-13T13:02:00Z" }, "relationships": { "pass": { "data": { "id": "7882e98b-0eba-4625-9223-5221eb8dad7f", "type": "pass" } }, "reader": { "data": { "id": "south-gate-1", "type": "reader" } } } }, { "id": "0195ebee-62d0-77cb-b8b1-0a81f99efc2c", "type": "scan", "attributes": { "scanType": "barcode", "scanValue": "factory_scan_value", "validationType": "internalValidation", "status": "failed", "statusDetail": "Pass is not active", "scannedAt": "2025-01-13T13:05:00Z" }, "relationships": { "pass": { "data": { "id": "7882e98b-0eba-4625-9223-5221eb8dad7f", "type": "pass" } }, "reader": { "data": { "id": "south-gate-1", "type": "reader" } } } } ], "included": [ { "id": "7882e98b-0eba-4625-9223-5221eb8dad7f", "type": "pass", "attributes": { "downloadUrl": "https://www.example.com?pass=7882e98b-0eba-4625-9223-5221eb8dad7f", "passType": "generic", "createdAt": "2022-01-01T00:00:00Z", "status": "issued", "extId": "4312d68fd106e3e6dd15", "passTemplateUuid": "7f24e7371e67c7af15103815", "passTemplateName": "PassEntry Event", "nfc": null, "barcode": {}, "passContent": { "fullName": "John Johnson" } } }, { "id": "south-gate-1", "type": "reader", "attributes": { "name": "South Gate Reader", "readerType": "PassentryReader", "loggedIn": false, "qrEnabled": false, "mifareClassicNfcEnabled": false, "scanEnabled": true, "redeemEnabled": false, "addPointsEnabled": false, "ndefTagScanningEnabled": false, "lastSeenAt": "2020-03-13T13:00:00Z" } } ], "meta": { "totalCount": 3, "resultsPerPage": 25, "currentPage": 1, "totalPages": 1 }, "links": { "first": null, "prev": null, "next": null, "last": null } }, "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/serializedScanObject" } }, "meta": { "$ref": "#/components/schemas/scanMeta" }, "included": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/serializedPassObject" }, { "$ref": "#/components/schemas/serializedReaderObject" } ] } }, "links": { "$ref": "#/components/schemas/indexLinks" } } } } } }, "401": { "description": "Error: Unauthorized", "content": { "application/json": { "example": { "errors": [ "Access denied" ] }, "schema": { "$ref": "#/components/schemas/errors" } } } } } } }, "/api/v1/scans/log": { "post": { "summary": "Log scan", "tags": [ "Scans" ], "operationId": "logScan", "security": [ { "api_key": [] } ], "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "examples": { "Example": { "value": { "scanInfo": { "scanId": "019488b8-c2fc-7b5b-b5b4-deb2b7f33bdd", "scanType": "nfc", "scanValue": "PROMO-CODE-123456", "validationType": "externalValidation", "status": "failed", "statusDetail": "Membership expired", "scannedAt": "2025-01-21T11:56:37Z", "passId": "7882e98b-0eba-4625-9223-5221eb8dad7f", "passExtId": "4312d68fd106e3e6dd15", "readerId": "south-gate-1" } } } }, "schema": { "$ref": "#/components/schemas/externalValidationResponse" } } } }, "401": { "description": "Error: Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errors" } } } }, "422": { "description": "Error: Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errors" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/logScan" }, "examples": { "0": { "summary": "Log scan", "value": { "scan": { "readerId": "south-gate-1", "scanType": "nfc", "status": "failed", "statusDetail": "Membership expired", "scanValue": "PROMO-CODE-123456", "passId": "7882e98b-0eba-4625-9223-5221eb8dad7f", "loyalty": { "balance": -10 } } } } } } } } } }, "/api/v1/scans/{id}": { "get": { "summary": "Get scan", "tags": [ "Scans" ], "operationId": "getScan", "security": [ { "api_key": [] } ], "parameters": [ { "name": "id", "in": "path", "description": "Scan UUID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "example": { "data": { "id": "019488b8-c2fc-7b5b-b5b4-deb2b7f33bdd", "type": "scan", "attributes": { "scanType": "nfc", "scanValue": "factory_scan_value", "validationType": "internalValidation", "status": "failed", "statusDetail": "Pass is not active", "scannedAt": "2025-01-13T13:00:00Z" }, "relationships": { "pass": { "data": { "id": "7882e98b-0eba-4625-9223-5221eb8dad7f", "type": "pass" } }, "reader": { "data": { "id": "south-gate-1", "type": "reader" } } } }, "included": [ { "id": "7882e98b-0eba-4625-9223-5221eb8dad7f", "type": "pass", "attributes": { "downloadUrl": "https://www.example.com?pass=7882e98b-0eba-4625-9223-5221eb8dad7f", "passType": "generic", "createdAt": "2022-01-01T00:00:00Z", "status": "issued", "extId": "4312d68fd106e3e6dd15", "passTemplateUuid": "7f24e7371e67c7af15103815", "passTemplateName": "PassEntry Event", "nfc": null, "barcode": {}, "passContent": { "fullName": "John Johnson" } } }, { "id": "south-gate-1", "type": "reader", "attributes": { "name": "South Gate Reader", "readerType": "PassentryReader", "loggedIn": false, "qrEnabled": false, "mifareClassicNfcEnabled": false, "scanEnabled": true, "redeemEnabled": false, "addPointsEnabled": false, "ndefTagScanningEnabled": false, "lastSeenAt": "2020-03-13T13:00:00Z" } } ] }, "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/serializedScanObject" }, "included": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/serializedPassObject" }, { "$ref": "#/components/schemas/serializedReaderObject" } ] } } } } } } }, "401": { "description": "Error: Unauthorized", "content": { "application/json": { "example": { "errors": [ "Access denied" ] }, "schema": { "$ref": "#/components/schemas/errors" } } } }, "404": { "description": "Error: Not Found", "content": { "application/json": { "example": { "errors": [ "Scan not found" ] }, "schema": { "$ref": "#/components/schemas/errors" } } } } } } }, "/api/v1/webhook-subscriptions/{id}/rotate-secret": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook subscription ID", "schema": { "type": "string" } } ], "patch": { "summary": "Rotate Secret Key", "description": "Generate a new secret key for webhook signature verification. The old key becomes invalid immediately.", "tags": [ "Webhook Subscriptions" ], "operationId": "rotateWebhookSecret", "security": [ { "api_key": [] } ], "responses": { "200": { "description": "Secret key rotated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/webhookSubscriptionResponse" } } } }, "401": { "description": "Unauthorized - Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errors" } } } }, "404": { "description": "Not Found - Webhook subscription not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errors" } } } } } } }, "/api/v1/webhook-subscriptions/{id}/test": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook subscription ID", "schema": { "type": "string" } } ], "post": { "summary": "Test Webhook Subscription", "description": "Send a test webhook to verify endpoint configuration and webhook handling.", "tags": [ "Webhook Subscriptions" ], "operationId": "testWebhookSubscription", "security": [ { "api_key": [] } ], "responses": { "200": { "description": "Test webhook sent successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Test webhook sent" } } } } } }, "401": { "description": "Unauthorized - Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errors" } } } }, "404": { "description": "Not Found - Webhook subscription not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errors" } } } }, "422": { "description": "Unprocessable Entity - Invalid webhook configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errors" } } } } } } }, "/api/v1/webhook-subscriptions/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook subscription ID", "schema": { "type": "string" } } ], "get": { "summary": "Show Webhook Subscription", "description": "Get details of a specific webhook subscription based on ID.", "tags": [ "Webhook Subscriptions" ], "operationId": "showWebhookSubscription", "security": [ { "api_key": [] } ], "responses": { "200": { "description": "Webhook subscription retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/webhookSubscriptionResponse" } } }, "example": { "data": { "id": "01983282-53cf-7e16-b5e1-dd0de4ce02fa", "type": "webhookSubscription", "attributes": { "url": "https://example.com/webhook", "secretKey": "a2e2c04657b924390d2a2623439c65734d07e0f8", "enabled": true, "scopeType": "organisation", "scopeName": "Test Organisation", "subscribedEvents": [ "passInstalled", "passRemoved" ] } } } } } }, "401": { "description": "Unauthorized - Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errors" } } } }, "404": { "description": "Not Found - Webhook subscription not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errors" }, "example": { "errors": [ "Webhook subscription not found" ] } } } } } }, "patch": { "summary": "Update Webhook Subscription", "description": "Update an existing webhook subscription configuration.", "tags": [ "Webhook Subscriptions" ], "operationId": "updateWebhookSubscription", "security": [ { "api_key": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Webhook subscription update configuration", "properties": { "webhookSubscription": { "type": "object", "properties": { "url": { "type": "string", "description": "HTTPS URL that will receive webhook events", "format": "uri", "pattern": "^https://.+", "example": "https://example.com/webhook" }, "enabled": { "type": "boolean", "description": "Whether the webhook subscription is active" }, "subscribedEvents": { "type": "array", "description": "List of events to subscribe to", "items": { "type": "string", "enum": [ "passInstalled", "passRemoved", "passScanned", "passCreated" ] }, "minItems": 1 } } } }, "required": [ "webhookSubscription" ] }, "example": { "webhookSubscription": { "url": "https://example.com/webhook/updated", "enabled": false, "subscribedEvents": [ "passInstalled", "passRemoved", "passCreated" ] } } } } }, "responses": { "200": { "description": "Webhook subscription updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/webhookSubscriptionResponse" } } }, "example": { "data": { "id": "01983282-53cf-7e16-b5e1-dd0de4ce02fa", "type": "webhookSubscription", "attributes": { "url": "https://example.com/webhook/updated", "secretKey": "a2e2c04657b924390d2a2623439c65734d07e0f8", "enabled": false, "scopeType": "organisation", "scopeName": "Test Organisation", "subscribedEvents": [ "passInstalled", "passRemoved", "passCreated" ] } } } } } }, "400": { "description": "Bad Request - Invalid webhook subscription data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errors" }, "example": { "errors": [ "Invalid URL format" ] } } } }, "401": { "description": "Unauthorized - Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errors" } } } }, "404": { "description": "Not Found - Webhook subscription not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errors" }, "example": { "errors": [ "Webhook subscription not found" ] } } } }, "422": { "description": "Unprocessable Entity - Invalid webhook URL or configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errors" }, "example": { "errors": [ "URL must be HTTPS" ] } } } } } }, "delete": { "summary": "Delete Webhook Subscription", "description": "Delete an existing webhook subscription.", "tags": [ "Webhook Subscriptions" ], "operationId": "deleteWebhookSubscription", "security": [ { "api_key": [] } ], "responses": { "200": { "description": "Webhook subscription deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Webhook subscription deleted" } } } } } }, "401": { "description": "Unauthorized - Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errors" } } } }, "404": { "description": "Not Found - Webhook subscription not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/errors" }, "example": { "errors": [ "Webhook subscription not found" ] } } } } } } } }, "webhooks": { "passInstalled": { "post": { "security": [ { "WebhookSignature": [] } ], "summary": "Pass Installed", "description": "Webhook triggered when a pass is added to the wallet by user", "operationId": "passInstalled", "tags": [ "Webhooks" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/webhook" }, "example": { "data": { "id": "018d8e07-beaa-7634-80a8-647cd33d6bb3", "type": "webhook", "attributes": { "timeStamp": "2022-01-01T00:00:00Z", "webhookType": "passInstalled" }, "relationships": { "pass": { "data": { "id": "313c3c3b950d30d7ecec486ddf9adf33b887ae29", "type": "pass" } } } }, "included": [ { "id": "e89b1330fc391ec89656f3c664318cff8805471e", "type": "pass", "attributes": { "downloadUrl": "https://localhost:3001/download?pass=e89b1330fc391ec89656f3c664318cff8805471e", "passType": "generic", "deviceType": "android", "createdAt": "2022-01-01T00:00:00Z", "status": "active", "extId": "0811d028ddf0da42c28f", "addedAt": "2022-02-01T00:00:00Z", "removedAt": null, "deactivatedAt": null, "passTemplateUuid": "c1f632d3e693a75c376b440b", "passTemplateName": "Pass Template 1 3079", "nfc": "e89b1330fc391ec89656f3c664318cff8805471e", "passContent": { "fullName": "Jane Smith" }, "barcode": { "enabled": true, "type": "qr", "source": "custom", "value": "123abcd", "displayText": true } } } ] } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully", "content": { "application/json": { "example": { "status": "ok" } } } } } } }, "passCreated": { "post": { "security": [ { "WebhookSignature": [] } ], "summary": "Pass Created", "description": "Webhook triggered when a pass is created", "operationId": "passCreated", "tags": [ "Webhooks" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/webhook" }, "example": { "data": { "id": "018d8e07-beaa-7634-80a8-647cd33d6bb3", "type": "webhook", "attributes": { "timeStamp": "2022-01-01T00:00:00Z", "webhookType": "passCreated" }, "relationships": { "pass": { "data": { "id": "313c3c3b950d30d7ecec486ddf9adf33b887ae29", "type": "pass" } } } }, "included": [ { "id": "e89b1330fc391ec89656f3c664318cff8805471e", "type": "pass", "attributes": { "downloadUrl": "https://localhost:3001/download?pass=e89b1330fc391ec89656f3c664318cff8805471e", "passType": "generic", "deviceType": "android", "createdAt": "2022-01-01T00:00:00Z", "status": "issued", "extId": "0811d028ddf0da42c28f", "addedAt": "2022-02-01T00:00:00Z", "removedAt": null, "deactivatedAt": null, "passTemplateUuid": "c1f632d3e693a75c376b440b", "passTemplateName": "Pass Template 1 3079", "nfc": "e89b1330fc391ec89656f3c664318cff8805471e", "passContent": { "fullName": "Jane Smith" }, "barcode": { "enabled": true, "type": "qr", "source": "custom", "value": "123abcd", "displayText": true } } } ] } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully", "content": { "application/json": { "example": { "status": "ok" } } } } } } }, "passRemoved": { "post": { "security": [ { "WebhookSignature": [] } ], "summary": "Pass Removed", "description": "Webhook triggered when a pass is removed from the wallet by user", "operationId": "passRemoved", "tags": [ "Webhooks" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/webhook" }, "example": { "data": { "id": "018d8e07-beaa-7634-80a8-647cd33d6bb3", "type": "webhook", "attributes": { "timeStamp": "2022-01-01T00:00:00Z", "webhookType": "passRemoved" }, "relationships": { "pass": { "data": { "id": "313c3c3b950d30d7ecec486ddf9adf33b887ae29", "type": "pass" } } } }, "included": [ { "id": "e89b1330fc391ec89656f3c664318cff8805471e", "type": "pass", "attributes": { "downloadUrl": "https://localhost:3001/download?pass=e89b1330fc391ec89656f3c664318cff8805471e", "passType": "generic", "deviceType": "android", "createdAt": "2022-01-01T00:00:00Z", "status": "removed", "extId": "0811d028ddf0da42c28f", "addedAt": "2022-02-01T00:00:00Z", "removedAt": "2023-02-01T00:00:00Z", "deactivatedAt": null, "passTemplateUuid": "c1f632d3e693a75c376b440b", "passTemplateName": "Pass Template 1 3079", "nfc": "e89b1330fc391ec89656f3c664318cff8805471e", "passContent": { "fullName": "Jane Smith" }, "barcode": { "enabled": true, "type": "qr", "source": "custom", "value": "123abcd", "displayText": true } } } ] } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully", "content": { "application/json": { "example": { "status": "ok" } } } } } } }, "passTapped": { "post": { "deprecated": true, "security": [ { "WebhookSignature": [] } ], "summary": "Pass Tapped", "description": "Webhook triggered when an NFC pass is tapped on a reader", "operationId": "passTapped", "tags": [ "Webhooks" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/webhook" }, "example": { "data": { "id": "018d8e07-beaa-7634-80a8-647cd33d6bb3", "type": "webhook", "attributes": { "timeStamp": "2022-01-01T00:00:00Z", "webhookType": "passTapped" }, "relationships": { "passTap": { "data": { "id": "857e764e-ec8d-4348-abfb-25f379983eaf", "type": "passTap" } }, "scan": { "data": { "id": "0194b1c7-be50-70f7-88eb-216d58afb575", "type": "scan" } }, "pass": { "data": { "id": "313c3c3b950d30d7ecec486ddf9adf33b887ae29", "type": "pass" } }, "reader": { "data": { "id": "CC202952", "type": "reader" } } } }, "included": [ { "id": "857e764e-ec8d-4348-abfb-25f379983eaf", "type": "scan", "attributes": { "scanType": "nfc", "scanValue": "313c3c3b950d30d7ecec486ddf9adf33b887ae29", "validationType": "internalValidation", "status": "successful", "successful": true, "statusDetail": null, "refusalReason": null, "scannedAt": "2025-01-28T10:25:11Z", "tappedAt": "2025-01-28T10:25:11Z" }, "relationships": { "pass": { "data": { "id": "313c3c3b950d30d7ecec486ddf9adf33b887ae29", "type": "pass" } }, "reader": { "data": { "id": "CC202952", "type": "reader" } } } }, { "id": "e89b1330fc391ec89656f3c664318cff8805471e", "type": "pass", "attributes": { "downloadUrl": "https://localhost:3001/download?pass=e89b1330fc391ec89656f3c664318cff8805471e", "passType": "generic", "deviceType": "android", "createdAt": "2022-01-01T00:00:00Z", "status": "removed", "extId": "0811d028ddf0da42c28f", "addedAt": "2022-02-01T00:00:00Z", "removedAt": "2023-02-01T00:00:00Z", "deactivatedAt": null, "passTemplateUuid": "c1f632d3e693a75c376b440b", "passTemplateName": "Pass Template 1 3079", "nfc": "e89b1330fc391ec89656f3c664318cff8805471e", "passContent": { "fullName": "Jane Smith" }, "barcode": { "enabled": true, "type": "qr", "source": "custom", "value": "123abcd", "displayText": true } } }, { "id": "CC202952", "type": "reader", "attributes": { "name": "West Gate" } } ] } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully", "content": { "application/json": { "example": { "status": "ok" } } } } } } }, "passScanned": { "post": { "security": [ { "WebhookSignature": [] } ], "summary": "Pass Scanned", "description": "Webhook triggered when an NFC or barcode pass is scanned by a reader", "operationId": "passScanned", "tags": [ "Webhooks" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/webhook" }, "example": { "data": { "id": "0194a887-f893-7c75-b250-ad2ef4a5d16e", "type": "webhook", "attributes": { "timeStamp": "2022-01-01T00:00:00Z", "webhookType": "passScanned" }, "relationships": { "scan": { "data": { "id": "0194a887-f880-703f-b8cf-16c1ea804b08", "type": "scan" } }, "pass": { "data": { "id": "313c3c3b950d30d7ecec486ddf9adf33b887ae29", "type": "pass" } }, "reader": { "data": { "id": "CC202952", "type": "reader" } } } }, "included": [ { "id": "0194a887-f880-703f-b8cf-16c1ea804b08", "type": "scan", "attributes": { "scanType": "nfc", "scanValue": "313c3c3b950d30d7ecec486ddf9adf33b887ae29", "validationType": "internalValidation", "status": "successful", "statusDetail": null, "scannedAt": "2025-01-28T10:25:11Z" }, "relationships": { "pass": { "data": { "id": "313c3c3b950d30d7ecec486ddf9adf33b887ae29", "type": "pass" } }, "reader": { "data": { "id": "CC202952", "type": "reader" } } } }, { "id": "e89b1330fc391ec89656f3c664318cff8805471e", "type": "pass", "attributes": { "downloadUrl": "https://localhost:3001/download?pass=e89b1330fc391ec89656f3c664318cff8805471e", "passType": "generic", "deviceType": "android", "createdAt": "2022-01-01T00:00:00Z", "status": "removed", "extId": "0811d028ddf0da42c28f", "addedAt": "2022-02-01T00:00:00Z", "removedAt": "2023-02-01T00:00:00Z", "deactivatedAt": null, "passTemplateUuid": "c1f632d3e693a75c376b440b", "passTemplateName": "Pass Template 1 3079", "nfc": "e89b1330fc391ec89656f3c664318cff8805471e", "passContent": { "fullName": "Jane Smith" }, "barcode": { "enabled": true, "type": "qr", "source": "custom", "value": "123abcd", "displayText": true } } }, { "id": "CC202952", "type": "reader", "attributes": { "name": "West Gate", "readerType": "VtapReader" } } ] } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully", "content": { "application/json": { "example": { "status": "ok" } } } } } } } }, "components": { "securitySchemes": { "api_key": { "type": "http", "scheme": "bearer" }, "WebhookSignature": { "type": "apiKey", "in": "header", "name": "X-Webhook-Signature", "description": "The `X-Webhook-Signature` header is generated using the webhook payload and shared secret key.\n To verify that the webhook is authentic, you can encrypt the webhook payload using the SHA-256\n encryption algorithm and your secret key.\n If your generated signature matches the signature included in the `X-Webhook-Signature`\n header, you can confirm that the webhook is authentic." } }, "schemas": { "eventAttributes": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the event", "example": "Bob Marley Live" }, "venueName": { "type": "string", "description": "Display name of the venue", "example": "The Lyceum Theatre" }, "startDatetime": { "type": "string", "description": "Start of the event in ISO8601 format", "example": "1975-07-17T22:30:00+01:00" }, "endDatetime": { "type": "string", "description": "End of the event in ISO8601 format, must be later than start_datetime", "example": "1975-07-18T02:30:00+01:00" }, "timeZone": { "type": "string", "description": "Time zone of the event. Must be a valid TZ identifier https://en.wikipedia.org/wiki/List_of_tz_database_time_zones", "example": "Europe/London" } } }, "createEvent": { "type": "object", "properties": { "event": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/eventAttributes" } ], "required": [ "name", "venueName", "startDatetime", "endDatetime", "timeZone" ] } } }, "updateEvent": { "type": "object", "properties": { "event": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/eventAttributes" } ] } } }, "serializedEvent": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "example": "da6b7ad694d5" }, "type": { "type": "string", "example": "event" }, "attributes": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the event" }, "venueName": { "type": "string", "description": "Display name of the venue" }, "startTime": { "type": "string", "description": "Start of the event in ISO8601 format, converted to event time zone" }, "endTime": { "type": "string", "description": "End of the event in ISO8601 format, converted to event time zone" }, "timeZone": { "type": "string", "description": "Time zone of the event" }, "status": { "type": "string", "description": "Status of the event", "enum": [ "upcoming", "ongoing", "ended" ] } } }, "meta": { "type": "object", "properties": { "passesCount": { "type": "integer", "description": "Number of passes" } } } } } } }, "serializedEntity": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "example": "entity" }, "attributes": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the entity" }, "passDeeplinks": { "type": "object", "description": " When clicked on a device, will direct the user to the pass in their wallet.\n Replace {PASSENTRY_PASS_UUID} with the pass UUID.", "properties": { "apple": { "type": "string", "description": "Apple Wallet Pass Deeplink" }, "google": { "type": "string", "description": "Google Wallet Pass Deeplink" } } } } } } } } }, "pass": { "type": "object", "properties": { "pass": { "type": "object", "properties": { "nfc[DEPRECATED]": { "type": "boolean", "description": "Whether the pass is NFC enabled. Setting this to true will set the pass UUID as the NFC message. This parameter is deprecated, please use the nfc object instead.", "example": false, "deprecated": true }, "nfc": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether the pass is NFC enabled." }, "source": { "type": "string", "enum": [ "extId", "custom", "uuid" ], "description": "Source of the NFC message", "x-enumDescriptions": { "extId": "Sets the pass extId as the NFC message, extId must be present", "uuid": "Sets the pass UUID as the NFC message", "custom": "Set a custom NFC message, using the customValue key" } }, "customValue": { "type": "string", "description": "Custom NFC message, source must be set to custom" } } }, "qr": { "type": "object", "description": "This parameter is deprecated, please use the barcode object instead.", "properties": { "value": { "type": "string", "description": "QR code value", "example": "abc123" }, "displayText": { "type": "boolean", "description": "If true, display the QR code value as text on the pass" } }, "deprecated": true }, "barcode": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "If true, barcode will be added to the pass" }, "type": { "type": "string", "description": "Barcode type", "enum": [ "qr", "code128", "aztec", "pdf417" ] }, "source": { "type": "string", "description": "Source of the barcode", "enum": [ "uuid", "extId", "custom" ] }, "value": { "type": "string", "description": "Barcode value, source must be set to custom\nIf your source type is `uuid` or `extId` don't need to set this value.\n\nYou can make the value dynamic using the `%{passData.xyz}` syntax (e.g., `Hello, %{passData.extId}`). Currently, only `%{passData.extId}` and `%{passData.uuid}` are supported.", "example": "abc123" }, "displayText": { "type": "boolean", "description": "If true, display the barcode value as text on the pass" } } }, "beacons": { "$ref": "#/components/schemas/beacons" }, "locations": { "$ref": "#/components/schemas/passLocations" }, "templateOverride": { "type": "object", "description": "Overrides the pass template design. Template overrides must be enabled for your organisation — contact support to request access. Once set, any changes to the pass template will not be applied to this pass. To revert to the original template design, pass `null` to any previously overridden value.", "properties": { "backgroundColor": { "type": [ "string", "null" ], "description": "Must be a valid hex color code. Background color cannot be overridden for Google Wallet loyalty passes and must be set at template level." }, "labelColor": { "type": [ "string", "null" ], "description": "Must be a valid hex color code. Only valid for iphone passes" }, "textColor": { "type": [ "string", "null" ], "description": "Must be a valid hex color code. Only valid for iphone passes" }, "bannerImage": { "oneOf": [ { "type": "object", "description": "Banner image using an Image Asset reference", "properties": { "imageAssetId": { "type": "string", "description": "ID of an uploaded Image Asset of type `banner`. See [Image Assets guide](/api-reference/v1/image-assets/guide)", "example": "19cb334f9696e64e10e7759f0" } } }, { "type": [ "string", "null" ], "description": "DEPRECATED: URL of the banner image. Use the object format with `imageAssetId` instead. Must be direct image URL, valid formats are PNG, JPG", "deprecated": true, "example": "https://passentry.com/static/media/logo.0f0e5d7eb4cd5f6d2d6d9243b357043e.svg" } ] }, "logoImage": { "oneOf": [ { "type": "object", "description": "Logo image using an Image Asset reference. Does not update Google logo, Google logo must be set at template level.", "properties": { "imageAssetId": { "type": "string", "description": "ID of an uploaded Image Asset of type `logo`. See [Image Assets guide](/api-reference/v1/image-assets/guide)", "example": "19cb334f9696e64e10e7759f0" } } }, { "type": [ "string", "null" ], "description": "DEPRECATED: URL of the logo image. Use the object format with `imageAssetId` instead. Must be direct image URL, valid formats are PNG, . DOES NOT UPDATE GOOGLE LOGO, GOOGLE LOGO MUST BE SET AT TEMPLATE LEVEL.", "deprecated": true, "example": "https://passentry.com/static/media/logo.0f0e5d7eb4cd5f6d2d6d9243b357043e.svg" } ] }, "thumbnailImage": { "oneOf": [ { "type": "object", "description": "Thumbnail image using an Image Asset reference. Pass type must be generic. Does not appear on Google passes.", "properties": { "imageAssetId": { "type": "string", "description": "ID of an uploaded Image Asset of type `thumbnail`. See [Image Assets guide](/api-reference/v1/image-assets/guide)", "example": "19cb334f9696e64e10e7759f0" } } }, { "type": [ "string", "null" ], "description": "DEPRECATED: URL of the thumbnail image. Use the object format with `imageAssetId` instead. Must be direct image URL, valid formats are PNG, JPG. PASS TYPE MUST BE GENERIC. DOES NOT APPEAR ON GOOGLE PASSES", "deprecated": true, "example": "https://passentry.com/static/media/logo.0f0e5d7eb4cd5f6d2d6d9243b357043e.svg" } ] }, "artworkImage": { "oneOf": [ { "type": "object", "description": "Artwork image using an Image Asset reference. Only valid for event ticket templates with enhanced event ticket enabled.", "properties": { "imageAssetId": { "type": "string", "description": "ID of an uploaded Image Asset of type `artwork`. See [Image Assets guide](/api-reference/v1/image-assets/guide)", "example": "19cb334f9696e64e10e7759f0" } } }, { "type": [ "string", "null" ], "description": "URL of the artwork image or null to reset. Must be HTTPS URL or base64 data URI. Only valid for event ticket templates with enhanced event ticket enabled. Maximum size: 1074x1344 px.", "example": "https://www.example.com/artwork.png" } ] }, "secondaryLogoImage": { "oneOf": [ { "type": "object", "description": "Secondary logo using an Image Asset reference. Only valid for event ticket templates with enhanced event ticket enabled.", "properties": { "imageAssetId": { "type": "string", "description": "ID of an uploaded Image Asset of type `secondaryLogo`. See [Image Assets guide](/api-reference/v1/image-assets/guide)", "example": "19cb334f9696e64e10e7759f0" } } }, { "type": [ "string", "null" ], "description": "URL of the secondary logo or null to reset. Must be HTTPS URL or base64 data URI. Only valid for event ticket templates with enhanced event ticket enabled. Maximum size: 405x36 px.", "example": "https://www.example.com/secondary-logo.png" } ] }, "venueMapImage": { "oneOf": [ { "type": "object", "description": "Venue map image using an Image Asset reference. Only valid for event ticket templates with enhanced event ticket enabled.", "properties": { "imageAssetId": { "type": "string", "description": "ID of an uploaded Image Asset of type `venueMap`. See [Image Assets guide](/api-reference/v1/image-assets/guide)", "example": "19cb334f9696e64e10e7759f0" } } }, { "type": [ "string", "null" ], "description": "URL of the venue map image or null to reset. Must be HTTPS URL or base64 data URI. Only valid for event ticket templates with enhanced event ticket enabled. Maximum size: 3072x3072 px.", "example": "https://www.example.com/venue-map.png" } ] } } }, "expiresAt": { "type": [ "string", "null" ], "description": "In ISO8601 format, UTC. If present, pass will be deactivated at this time. Pass status will be set to deactivated. Google wallet passes may take up to 24 hours to deactivate. If your organisation is in trial, expiresAt may not be set after the trial expiry.." }, "relevantDateTime": { "type": "string", "description": "In ISO8601 format, UTC. Currently only available on Apple devices, due to Android device restrictions. If present, this enables upcoming notifications or persistent notifications for the pass\n\n***Note**: You can only set this field if the pass type is `eventTicket` or `transit`*" }, "enhancedEventData": { "type": "object", "description": "Per-pass event data for the poster event ticket face and event guide. Only processed when the pass template has enhanced event ticket enabled. Requires pass binding to be provided when non-empty.\n\nThis data is entirely separate from legacy pass fields (primaryFields, auxiliaryFields, etc.) and does not affect legacy event ticket rendering on older devices.\n\n***Note**: This feature is in **closed beta**. The API structure may change and you may encounter bugs. Please contact PassEntry for access.*", "properties": { "event": { "type": "object", "description": "Core event information. Required when enhancedEventData is provided.", "properties": { "name": { "type": "string", "description": "Name of the event. Triggers an automatic Wallet notification to pass holders if updated after issuance.", "example": "PassEntry Christmas Party" }, "startDateTime": { "type": "string", "description": "ISO 8601 date with timezone. Displayed in the top right of the pass header.", "example": "2026-12-10T18:00:00Z" }, "endDateTime": { "type": "string", "description": "ISO 8601 date with timezone.", "example": "2026-12-10T22:00:00Z" } }, "required": ["name", "startDateTime"] }, "venue": { "type": "object", "description": "Venue information for the event. Required when enhancedEventData is provided.", "properties": { "name": { "type": "string", "description": "Shown at the bottom left of the pass chin.", "example": "Fulham Green" }, "region": { "type": "string", "description": "Used when there is no specific venue.", "example": "London" }, "location": { "type": "object", "description": "Latitude and longitude of the venue.", "properties": { "latitude": { "type": "number", "example": 51.468532 }, "longitude": { "type": "number", "example": -0.210611 } }, "required": ["latitude", "longitude"] }, "contactPhoneNumber": { "type": "string", "description": "Appears as a quick action button in the Apple event guide.", "example": "+447400123456" }, "contactEmailAddress": { "type": "string", "description": "Appears as a quick action button in the Apple event guide.", "example": "venue@passentry.com" }, "websiteUrl": { "type": "string", "description": "Appears as a quick action button in the Apple event guide.", "example": "https://www.example.com" } }, "required": ["name", "location"] }, "seat": { "type": "object", "description": "Seating information. Values can be any string.", "properties": { "number": { "type": "string", "description": "Rendered as a labelled column in the pass chin.", "example": "7" }, "row": { "type": "string", "description": "Rendered as a labelled column in the pass chin.", "example": "H" }, "section": { "type": "string", "description": "Rendered as a labelled column in the pass chin.", "example": "312" }, "gate": { "type": "string", "description": "Flexible text field for entrance information.", "example": "26" } } }, "eventGuide": { "type": "object", "description": "Event guide fields. Required when enhancedEventData is provided. URL fields appear as quick action buttons in the Apple event guide.", "properties": { "venueOpenDateTime": { "type": "string", "description": "ISO 8601 date with timezone.", "example": "2026-12-10T17:00:00Z" }, "venueCloseDateTime": { "type": "string", "description": "ISO 8601 date with timezone.", "example": "2026-12-10T22:00:00Z" }, "bagPolicyUrl": { "type": "string", "example": "https://www.example.com/bag-policy" }, "orderFoodUrl": { "type": "string", "example": "https://www.example.com/order-food" }, "transitInformationUrl": { "type": "string", "example": "https://www.example.com/transit-information" }, "parkingInformationUrl": { "type": "string", "example": "https://www.example.com/parking-information" }, "directionsInformationUrl": { "type": "string", "example": "https://www.example.com/directions-information" }, "merchandiseUrl": { "type": "string", "example": "https://www.example.com/merchandise" }, "accessibilityUrl": { "type": "string", "example": "https://www.example.com/accessibility" }, "addOnUrl": { "type": "string", "example": "https://www.example.com/add-on" } }, "required": ["venueOpenDateTime", "venueCloseDateTime"] } } } }, "additionalProperties": { "x-additionalPropertiesName": "templateKey", "anyOf": [ { "type": "object", "description": "The `templateKey` identifies a pass field in the template (using the template field ID). Its value must be an object with a required `value` string, and may optionally include a `localisation` object that maps locale codes to translated `value`s.\n\n***Note**: This feature is in **open beta** and currently only available on the API. Please contact PassEntry for access.*", "example": { "pass": { "eventName": { "value": "Summer Festival", "localisation": { "es": { "value": "Festival de Verano" }, "fr": { "value": "Festival d'Été" } } } } } }, { "type": "string", "deprecated": true, "description": "DEPRECATED — legacy format where the template value was a string.\nMigrate to the object format, e.g. `{'fullName': {'value': 'Jane Smith'}}`." } ] } }, "message": { "type": "string", "description": "Push Notification message to display. If present,\n response will include X-Notification-Status header", "example": "Your pass details have been updated. Click to show pass" }, "passAction": { "type": "string", "enum": [ "deactivate", "reactivate" ], "description": "Only available when updating the pass.\n- deactivate: Deactivates the pass, setting it to 'expired' in the wallet. When in this state, pass can receive updates but does not receive Apple notifications.\n- reactivate: Reactivates the pass, setting it to 'active' in the wallet. In the case of Apple passes, the pass will remain in the 'expired' passes section of the wallet, user will need to manually select 'unhide' to move passes to the main passes view." }, "locations": { "type": "array", "maximum": 10, "description": "Array of locations. Maximum of 10 locations", "items": { "$ref": "#/components/schemas/location" } }, "beacons": { "type": "array", "maximum": 10, "description": "Array of beacons, currently only available on Apple devices,\n due to Android device restrictions.\n Maximum of 10 beacons", "items": { "$ref": "#/components/schemas/beacon" } }, "groupTag": { "type": "string", "description": "Tag used for grouping passes", "example": "EASTER_OFFER_22" }, "groupTags": { "type": "array", "description": "Tags used for grouping passes", "example": [ "EASTER_OFFER_22", "SUMMER_SALE_22" ] } } }, "createPassRequest": { "type": "object", "properties": { "pass": { "type": "object", "properties": { "nfc[DEPRECATED]": { "type": "boolean", "description": "Whether the pass is NFC enabled. Setting this to true will set the pass UUID as the NFC message. This parameter is deprecated, please use the nfc object instead.", "example": false, "deprecated": true }, "nfc": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether the pass is NFC enabled." }, "source": { "type": "string", "enum": [ "extId", "custom", "uuid" ], "description": "Source of the NFC message", "x-enumDescriptions": { "extId": "Sets the pass extId as the NFC message, extId must be present", "uuid": "Sets the pass UUID as the NFC message", "custom": "Set a custom NFC message, using the customValue key" } }, "customValue": { "type": "string", "description": "Custom NFC message, source must be set to custom" } } }, "qr": { "type": "object", "description": "This parameter is deprecated, please use the barcode object instead.", "properties": { "value": { "type": "string", "description": "QR code value", "example": "abc123" }, "displayText": { "type": "boolean", "description": "If true, display the QR code value as text on the pass" } }, "deprecated": true }, "barcode": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "If true, barcode will be added to the pass" }, "type": { "type": "string", "description": "Barcode type", "enum": [ "qr", "code128", "aztec", "pdf417" ] }, "source": { "type": "string", "description": "Source of the barcode", "enum": [ "uuid", "extId", "custom" ] }, "value": { "type": "string", "description": "Barcode value, source must be set to custom\nIf your source type is `uuid` or `extId` don't need to set this value.\n\nYou can make the value dynamic using the `%{passData.xyz}` syntax (e.g., `Hello, %{passData.extId}`). Currently, only `%{passData.extId}` and `%{passData.uuid}` are supported.", "example": "abc123" }, "displayText": { "type": "boolean", "description": "If true, display the barcode value as text on the pass" } } }, "beacons": { "$ref": "#/components/schemas/beacons" }, "locations": { "$ref": "#/components/schemas/passLocations" }, "templateOverride": { "type": "object", "description": "Overrides the pass template design. Template overrides must be enabled for your organisation — contact support to request access. Once set, any changes to the pass template will not be applied to this pass. To revert to the original template design, pass `null` to any previously overridden value.", "properties": { "backgroundColor": { "type": [ "string", "null" ], "description": "Must be a valid hex color code. Background color cannot be overridden for Google Wallet loyalty passes and must be set at template level." }, "labelColor": { "type": [ "string", "null" ], "description": "Must be a valid hex color code. Only valid for iphone passes" }, "textColor": { "type": [ "string", "null" ], "description": "Must be a valid hex color code. Only valid for iphone passes" }, "bannerImage": { "oneOf": [ { "type": "object", "description": "Banner image using an Image Asset reference", "properties": { "imageAssetId": { "type": "string", "description": "ID of an uploaded Image Asset of type `banner`. See [Image Assets guide](/api-reference/v1/image-assets/guide)", "example": "19cb334f9696e64e10e7759f0" } } }, { "type": [ "string", "null" ], "description": "DEPRECATED: URL of the banner image. Use the object format with `imageAssetId` instead. Must be direct image URL, valid formats are PNG, JPG", "deprecated": true, "example": "https://passentry.com/static/media/logo.0f0e5d7eb4cd5f6d2d6d9243b357043e.svg" } ] }, "logoImage": { "oneOf": [ { "type": "object", "description": "Logo image using an Image Asset reference. Does not update Google logo, Google logo must be set at template level.", "properties": { "imageAssetId": { "type": "string", "description": "ID of an uploaded Image Asset of type `logo`. See [Image Assets guide](/api-reference/v1/image-assets/guide)", "example": "19cb334f9696e64e10e7759f0" } } }, { "type": [ "string", "null" ], "description": "DEPRECATED: URL of the logo image. Use the object format with `imageAssetId` instead. Must be direct image URL, valid formats are PNG, JPG. DOES NOT UPDATE GOOGLE LOGO, GOOGLE LOGO MUST BE SET AT TEMPLATE LEVEL.", "deprecated": true, "example": "https://passentry.com/static/media/logo.0f0e5d7eb4cd5f6d2d6d9243b357043e.svg" } ] }, "thumbnailImage": { "oneOf": [ { "type": "object", "description": "Thumbnail image using an Image Asset reference. Pass type must be generic. Does not appear on Google passes.", "properties": { "imageAssetId": { "type": "string", "description": "ID of an uploaded Image Asset of type `thumbnail`. See [Image Assets guide](/api-reference/v1/image-assets/guide)", "example": "19cb334f9696e64e10e7759f0" } } }, { "type": [ "string", "null" ], "description": "DEPRECATED: URL of the thumbnail image. Use the object format with `imageAssetId` instead. Must be direct image URL, valid formats are PNG, JPG. PASS TYPE MUST BE GENERIC. DOES NOT APPEAR ON GOOGLE PASSES", "deprecated": true, "example": "https://passentry.com/static/media/logo.0f0e5d7eb4cd5f6d2d6d9243b357043e.svg" } ] }, "artworkImage": { "oneOf": [ { "type": "object", "description": "Artwork image using an Image Asset reference. Only valid for event ticket templates with enhanced event ticket enabled.", "properties": { "imageAssetId": { "type": "string", "description": "ID of an uploaded Image Asset of type `artwork`. See [Image Assets guide](/api-reference/v1/image-assets/guide)", "example": "19cb334f9696e64e10e7759f0" } } }, { "type": [ "string", "null" ], "description": "URL of the artwork image or null to reset. Must be HTTPS URL or base64 data URI. Only valid for event ticket templates with enhanced event ticket enabled. Maximum size: 1074x1344 px.", "example": "https://www.example.com/artwork.png" } ] }, "secondaryLogoImage": { "oneOf": [ { "type": "object", "description": "Secondary logo using an Image Asset reference. Only valid for event ticket templates with enhanced event ticket enabled.", "properties": { "imageAssetId": { "type": "string", "description": "ID of an uploaded Image Asset of type `secondaryLogo`. See [Image Assets guide](/api-reference/v1/image-assets/guide)", "example": "19cb334f9696e64e10e7759f0" } } }, { "type": [ "string", "null" ], "description": "URL of the secondary logo or null to reset. Must be HTTPS URL or base64 data URI. Only valid for event ticket templates with enhanced event ticket enabled. Maximum size: 405x36 px.", "example": "https://www.example.com/secondary-logo.png" } ] }, "venueMapImage": { "oneOf": [ { "type": "object", "description": "Venue map image using an Image Asset reference. Only valid for event ticket templates with enhanced event ticket enabled.", "properties": { "imageAssetId": { "type": "string", "description": "ID of an uploaded Image Asset of type `venueMap`. See [Image Assets guide](/api-reference/v1/image-assets/guide)", "example": "19cb334f9696e64e10e7759f0" } } }, { "type": [ "string", "null" ], "description": "URL of the venue map image or null to reset. Must be HTTPS URL or base64 data URI. Only valid for event ticket templates with enhanced event ticket enabled. Maximum size: 3072x3072 px.", "example": "https://www.example.com/venue-map.png" } ] } } }, "expiresAt": { "type": [ "string", "null" ], "description": "In ISO8601 format, UTC. If present, pass will be deactivated at this time. Pass status will be set to deactivated. Google wallet passes may take up to 24 hours to deactivate. If your organisation is in trial, expiresAt may not be set after the trial expiry.." }, "relevantDateTime": { "type": "string", "description": "In ISO8601 format, UTC. Currently only available on Apple devices, due to Android device restrictions. If present, this enables upcoming notifications or persistent notifications for the pass\n\n***Note**: You can only set this field if the pass type is `eventTicket` or `transit`*" }, "enhancedEventData": { "type": "object", "description": "Per-pass event data for the poster event ticket face and event guide. Only processed when the pass template has enhanced event ticket enabled. Requires pass binding to be provided when non-empty.\n\nThis data is entirely separate from legacy pass fields (primaryFields, auxiliaryFields, etc.) and does not affect legacy event ticket rendering on older devices.\n\n***Note**: This feature is in **closed beta**. The API structure may change and you may encounter bugs. Please contact PassEntry for access.*", "properties": { "event": { "type": "object", "description": "Core event information. Required when enhancedEventData is provided.", "properties": { "name": { "type": "string", "description": "Name of the event. Triggers an automatic Wallet notification to pass holders if updated after issuance.", "example": "PassEntry Christmas Party" }, "startDateTime": { "type": "string", "description": "ISO 8601 date with timezone. Displayed in the top right of the pass header.", "example": "2026-12-10T18:00:00Z" }, "endDateTime": { "type": "string", "description": "ISO 8601 date with timezone.", "example": "2026-12-10T22:00:00Z" } }, "required": ["name", "startDateTime"] }, "venue": { "type": "object", "description": "Venue information for the event. Required when enhancedEventData is provided.", "properties": { "name": { "type": "string", "description": "Shown at the bottom left of the pass chin.", "example": "Fulham Green" }, "region": { "type": "string", "description": "Used when there is no specific venue.", "example": "London" }, "location": { "type": "object", "description": "Latitude and longitude of the venue.", "properties": { "latitude": { "type": "number", "example": 51.468532 }, "longitude": { "type": "number", "example": -0.210611 } }, "required": ["latitude", "longitude"] }, "contactPhoneNumber": { "type": "string", "description": "Appears as a quick action button in the Apple event guide.", "example": "+447400123456" }, "contactEmailAddress": { "type": "string", "description": "Appears as a quick action button in the Apple event guide.", "example": "venue@passentry.com" }, "websiteUrl": { "type": "string", "description": "Appears as a quick action button in the Apple event guide.", "example": "https://www.example.com" } }, "required": ["name", "location"] }, "seat": { "type": "object", "description": "Seating information. Values can be any string.", "properties": { "number": { "type": "string", "description": "Rendered as a labelled column in the pass chin.", "example": "7" }, "row": { "type": "string", "description": "Rendered as a labelled column in the pass chin.", "example": "H" }, "section": { "type": "string", "description": "Rendered as a labelled column in the pass chin.", "example": "312" }, "gate": { "type": "string", "description": "Flexible text field for entrance information.", "example": "26" } } }, "eventGuide": { "type": "object", "description": "Event guide fields. Required when enhancedEventData is provided. URL fields appear as quick action buttons in the Apple event guide.", "properties": { "venueOpenDateTime": { "type": "string", "description": "ISO 8601 date with timezone.", "example": "2026-12-10T17:00:00Z" }, "venueCloseDateTime": { "type": "string", "description": "ISO 8601 date with timezone.", "example": "2026-12-10T22:00:00Z" }, "bagPolicyUrl": { "type": "string", "example": "https://www.example.com/bag-policy" }, "orderFoodUrl": { "type": "string", "example": "https://www.example.com/order-food" }, "transitInformationUrl": { "type": "string", "example": "https://www.example.com/transit-information" }, "parkingInformationUrl": { "type": "string", "example": "https://www.example.com/parking-information" }, "directionsInformationUrl": { "type": "string", "example": "https://www.example.com/directions-information" }, "merchandiseUrl": { "type": "string", "example": "https://www.example.com/merchandise" }, "accessibilityUrl": { "type": "string", "example": "https://www.example.com/accessibility" }, "addOnUrl": { "type": "string", "example": "https://www.example.com/add-on" } }, "required": ["venueOpenDateTime", "venueCloseDateTime"] } } } }, "additionalProperties": { "x-additionalPropertiesName": "templateKey", "anyOf": [ { "type": "object", "description": "The `templateKey` identifies a pass field in the template (using the template field ID). Its value must be an object with a required `value` string, and may optionally include a `localisation` object that maps locale codes to translated `value`s.\n\n***Note**: This feature is in **open beta** and currently only available on the API. Please contact PassEntry for access.*", "example": { "pass": { "eventName": { "value": "Summer Festival", "localisation": { "es": { "value": "Festival de Verano" }, "fr": { "value": "Festival d'Été" } } } } } }, { "type": "string", "deprecated": true, "description": "DEPRECATED — legacy format where the template value was a string.\nMigrate to the object format, e.g. `{'fullName': {'value': 'Jane Smith'}}`." } ] } }, "passAction": { "type": "string", "enum": [ "deactivate", "reactivate" ], "description": "Only available when updating the pass.\n- deactivate: Deactivates the pass, setting it to 'expired' in the wallet. When in this state, pass can receive updates but does not receive Apple notifications.\n- reactivate: Reactivates the pass, setting it to 'active' in the wallet. In the case of Apple passes, the pass will remain in the 'expired' passes section of the wallet, user will need to manually select 'unhide' to move passes to the main passes view." }, "locations": { "type": "array", "maximum": 10, "description": "Array of locations. Maximum of 10 locations", "items": { "$ref": "#/components/schemas/location" } }, "beacons": { "type": "array", "maximum": 10, "description": "Array of beacons, currently only available on Apple devices,\n due to Android device restrictions.\n Maximum of 10 beacons", "items": { "$ref": "#/components/schemas/beacon" } }, "groupTag": { "type": "string", "description": "Tag used for grouping passes", "example": "EASTER_OFFER_22" }, "groupTags": { "type": "array", "description": "Tags used for grouping passes", "example": [ "EASTER_OFFER_22", "SUMMER_SALE_22" ] }, "binding": { "type": "object", "description": "Account binding restricts the pass to a specific wallet account. **This feature is in open beta.** Only available on pass creation — binding cannot be added or modified via the update endpoint.\n\n**Important:** To change binding details, a new pass must be created. Barcodes are prohibited on passes when binding is enabled — ensure your passes do not rely on barcodes before enabling binding.\n\nOnce a pass is bound to a platform (Apple or Google), it cannot be downloaded on the other platform.\n\n**Google Wallet**: The pass is restricted to the specified email account using a SHA-256 hash.\n\n**Apple Wallet**: The pass uses FIDO hardware key binding tied to the user's iCloud account, requiring Face ID or Touch ID authentication. While pass can be downloaded on a different device, binding only affects NFC. If NFC pass is created and pass is downloaded on a different device, the NFC will be disabled on the pass.\n\nSee the [Pass Binding guide](/documentation/passes/pass-binding/guide) for full details.", "properties": { "email": { "type": "string", "format": "email", "description": "Email address of the pass holder. For Google Wallet, this must match the user's Google account. The email is stored encrypted and masked in API responses.", "example": "user@gmail.com" }, "learnMoreUrl": { "type": "string", "format": "uri", "description": "HTTPS URL to a page on your website where the pass holder can get help resolving issues with their pass. This URL is shown to the user when their pass enters an invalid state. Must start with https:// and be 255 characters or less.", "example": "https://support.example.com/pass-binding" } }, "required": [ "email", "learnMoreUrl" ] } } }, "serializedPassObject": { "type": "object", "properties": { "id": { "type": "string", "description": "Auto-generated UUID of the pass", "example": "e89b1330fc391ec89656f3c664318cff8805471e" }, "type": { "type": "string", "example": "pass" }, "attributes": { "type": "object", "properties": { "downloadUrl": { "type": "string", "description": "Unique download URL of the pass" }, "passType": { "type": "string", "description": "Pass Type", "enum": [ "generic", "eventTicket", "storeCard", "transit" ] }, "deviceType": { "type": "string", "enum": [ "android", "iphone" ] }, "createdAt": { "type": "string", "description": "In ISO8601 format, UTC" }, "status": { "type": "string", "description": "Pass Status", "enum": [ "issued", "active", "removed", "deactivated", "nullified" ] }, "extId": { "type": [ "string", "null" ], "description": "Pass External ID" }, "groupTag": { "type": [ "string", "null" ], "description": "Tag used for grouping passes" }, "groupTags": { "type": [ "array", "null" ], "description": "Tag used for grouping passes" }, "addedAt": { "type": [ "string", "null" ], "description": "When pass has been added to wallet by the user. In ISO8601 format, UTC" }, "removedAt": { "type": [ "string", "null" ], "description": "When pass has been removed from wallet by the user. In ISO8601 format, UTC" }, "deactivatedAt": { "type": [ "string", "null" ], "description": "When pass has been deactivated. In ISO8601 format, UTC" }, "nullifiedAt": { "type": [ "string", "null" ], "description": "When pass has been nullified. In ISO8601 format, UTC" }, "expiresAt": { "type": [ "string", "null" ], "description": "Pass will expire at this time. In ISO8601 format, UTC" }, "passTemplateUuid": { "type": "string", "description": "UUID of corresponding pass template" }, "passTemplateName": { "type": "string", "description": "Name of corresponding pass template" }, "nfc": { "type": [ "string", "null" ], "description": "If present, the NFC message to be conveyed when the pass is tapped" }, "barcode": { "type": [ "object" ], "description": "If present, the barcode type and value", "properties": { "enabled": { "type": "boolean", "description": "Barcode enabled" }, "type": { "type": "string", "description": "Barcode type", "enum": [ "qr", "code128", "aztec", "pdf417" ] }, "source": { "type": "string", "description": "Barcode source", "enum": [ "uuid", "extId", "custom" ] }, "value": { "type": "string", "description": "Barcode value", "example": "123abcd" }, "displayText": { "type": "boolean", "description": "If true, display the barcode value as text on the pass" } } }, "latestMessage": { "type": [ "string", "null" ], "description": "If present, the last push message sent to the pass" }, "passContent": { "type": "object", "additionalProperties": { "x-additionalPropertiesName": "templateKey", "anyOf": [ { "type": "object", "description": "The `templateKey` identifies a pass field in the template (using the template field ID). Its value must be an object with a required `value` string, and may optionally include a `localisation` object that maps locale codes to translated `value`s.", "example": { "eventName": { "value": "Summer Festival", "localisation": { "es": { "value": "Festival de Verano" }, "fr": { "value": "Festival d'Été" } } } } }, { "type": "string", "deprecated": true, "description": "DEPRECATED — legacy format where the template value was a string.\nMigrate to the object format, e.g. {'fullName': {'value': 'Jane Smith'}}.", "example": "Jane Smith" } ] } }, "passDesign": { "description": "Pass design values, present if pass template has been overridden for this pass, or if\n 'includePassDesign' query param is set to true", "type": "object", "properties": { "backgroundColor": { "type": "string", "example": "#EFEFEF", "description": "Pass background color in hex format" }, "labelColor": { "type": "string", "example": "#EFEFEF", "description": "Pass label color in hex format. Only valid for iphone passes" }, "textColor": { "type": "string", "example": "#EFEFEF", "description": "Pass text color in hex format. Only valid for iphone passes" }, "bannerImageUrl": { "type": "string", "description": "URL of pass banner image" }, "logoImageUrl": { "type": "string", "description": "URL of pass logo image" }, "thumbnailImageUrl": { "type": "string", "description": "URL of pass thumbnail image. Only present for generic passes." }, "artworkImageUrl": { "type": "string", "description": "URL of pass artwork image. Only present for event ticket passes with enhanced event ticket enabled." }, "secondaryLogoImageUrl": { "type": "string", "description": "URL of pass secondary logo image. Only present for event ticket passes with enhanced event ticket enabled." }, "venueMapImageUrl": { "type": "string", "description": "URL of pass venue map image. Only present for event ticket passes with enhanced event ticket enabled." } } }, "locations": { "type": "array", "description": "Locations, present if 'includeLocations' query param is set to true", "items": { "allOf": [ { "$ref": "#/components/schemas/serializedLocation" } ] } }, "beacons": { "type": "array", "description": "Beacons, present if 'includeBeacons' query param is set to true", "items": { "allOf": [ { "$ref": "#/components/schemas/serializedBeacon" } ] } }, "enhancedEventData": { "type": "object", "description": "Enhanced event data for poster event ticket. Only present on event ticket passes with enhanced event ticket enabled on their template.\n\n***Note**: This feature is in **closed beta**. The API structure may change and you may encounter bugs. Please contact PassEntry for access.*", "properties": { "event": { "type": "object", "properties": { "name": { "type": "string", "example": "PassEntry Christmas Party" }, "startDateTime": { "type": "string", "example": "2026-12-10T18:00:00Z" }, "endDateTime": { "type": "string", "example": "2026-12-10T22:00:00Z" } } }, "venue": { "type": "object", "properties": { "name": { "type": "string", "example": "Fulham Green" }, "region": { "type": "string", "example": "London" }, "location": { "type": "object", "properties": { "latitude": { "type": "number", "example": 51.468532 }, "longitude": { "type": "number", "example": -0.210611 } } }, "contactPhoneNumber": { "type": "string", "example": "+447400123456" }, "contactEmailAddress": { "type": "string", "example": "venue@passentry.com" }, "websiteUrl": { "type": "string", "example": "https://www.example.com" } } }, "seat": { "type": "object", "properties": { "number": { "type": "string", "example": "7" }, "row": { "type": "string", "example": "H" }, "section": { "type": "string", "example": "312" }, "gate": { "type": "string", "example": "26" } } }, "eventGuide": { "type": "object", "properties": { "venueOpenDateTime": { "type": "string", "example": "2026-12-10T17:00:00Z" }, "venueCloseDateTime": { "type": "string", "example": "2026-12-10T22:00:00Z" }, "bagPolicyUrl": { "type": "string" }, "orderFoodUrl": { "type": "string" }, "transitInformationUrl": { "type": "string" }, "parkingInformationUrl": { "type": "string" }, "directionsInformationUrl": { "type": "string" }, "merchandiseUrl": { "type": "string" }, "accessibilityUrl": { "type": "string" }, "addOnUrl": { "type": "string" } } } } }, "passSource": { "description": "Pass source, present if 'includePassDesign' query param is present, one of\n Apple/Google and current pass status is not 'active'.", "type": "object", "properties": { "oneOf": { "type": "object", "properties": { "appleBase64": { "type": "string", "description": "Apple Wallet Pass Base64 string, to generate the pass,\n decode the string and save as a .pkpass file. Will prompt the user to download the pass to\n their Apple Wallet when opened on an iPhone." }, "googleDownloadUrl": { "type": "string", "description": "Google Wallet Pass download URL.\n Will prompt the user to download the pass to their Google Wallet\n when opened on an Android device." } } } } }, "binding": { "type": [ "object", "null" ], "description": "Account binding status. Present when the pass has a binding record. Automatically included for single pass responses (show, create, update). For list endpoints, use the `includeBinding=true` query parameter.", "properties": { "platform": { "type": [ "string", "null" ], "enum": [ "apple", "google", null ], "description": "The wallet platform this pass is bound to. Null when the pass has been created with binding but not yet downloaded." }, "bound": { "type": "boolean", "description": "Whether the pass binding has been finalised. True after the pass has been successfully downloaded and the binding verified." }, "bindingEmail": { "type": [ "string", "null" ], "description": "Masked email address of the pass holder (e.g. `u***@gmail.com`). Null for Apple-bound passes as the email is purged after binding initiation." }, "learnMoreUrl": { "type": "string", "description": "URL shown to the user explaining account binding." } } } } } } }, "serializedPassMeta": { "type": "object", "properties": { "loyalty": { "type": "object", "properties": { "balance": { "type": "integer", "description": "Loyalty balance" } } } } }, "serializedPassesList": { "type": "object", "properties": { "data": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/serializedPassObject" } ] } }, "meta": { "$ref": "#/components/schemas/indexMeta" }, "links": { "$ref": "#/components/schemas/indexLinks" } } }, "serializedReadersList": { "type": "object", "properties": { "data": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/serializedReaderObject" } ] } }, "meta": { "$ref": "#/components/schemas/indexMeta" }, "links": { "$ref": "#/components/schemas/indexLinks" } } }, "serializedEntitiesList": { "type": "object", "properties": { "data": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/serializedEntity" } ] } }, "meta": { "$ref": "#/components/schemas/indexMeta" }, "links": { "$ref": "#/components/schemas/indexLinks" } } }, "loyaltyPass": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/serializedPassObject" }, "meta": { "$ref": "#/components/schemas/serializedPassMeta" } } }, "loyaltyBalance": { "type": "object", "properties": { "balance": { "type": "integer", "description": "If integer is positive, balance is added. If negative, balance is subtracted. Cannot be used with overrideBalance key", "example": -10 }, "overrideBalance": { "type": "integer", "description": "Override the balance and set it to this value. Cannot be used with balance key", "example": 0 }, "message": { "type": "string", "description": "Push Notification message to display. Only used if pass is active. Use alongside balance or overrideBalance keys" } } }, "serializedPassTemplateDeprecated": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Auto-generated UUID of the pass template", "example": "1fed3fbb1a8bec4ed1bddf38" }, "type": { "type": "string", "example": "passTemplate" }, "attributes": { "type": "object", "properties": { "backgroundColor": { "type": "string", "description": "Must be a valid hex color code", "example": "#EFEFEF" }, "name": { "type": "string", "description": "Name of the pass template, set on creation. Not displayed on the pass", "example": "Summer Sale 2023" }, "description": { "type": "string", "description": "Pass description, displayed on the pass", "example": "Summer Sale Pass" }, "labelColor": { "type": "string", "description": "Must be a valid hex color code. Only valid for iphone passes", "example": "#FF8477" }, "textColor": { "type": "string", "description": "Must be a valid hex color code. Only valid for iphone passes", "example": "#29323A" }, "templateType": { "type": "string", "description": "Passes created from this template will be of this type", "enum": [ "generic", "eventTicket", "storeCard", "transit" ] }, "header": { "type": [ "string", "null" ], "description": "Pass Header Label" }, "secondary": { "type": "object", "properties": { "secOne": { "type": [ "string", "null" ] }, "secTwo": { "type": [ "string", "null" ] }, "secThree": { "type": [ "string", "null" ] } }, "description": "Pass Secondary Labels" }, "secondaryValues": { "type": "object", "properties": { "secOneValue": { "type": [ "string", "null" ] }, "secTwoValue": { "type": [ "string", "null" ] }, "secThreeValue": { "type": [ "string", "null" ] } }, "description": "Pass Secondary default values" }, "auxiliary": { "type": "object", "properties": { "auxOne": { "type": [ "string", "null" ] }, "auxTwo": { "type": [ "string", "null" ] }, "auxThree": { "type": [ "string", "null" ] } }, "description": "Pass Auxiliary Labels" }, "auxiliaryValues": { "type": "object", "properties": { "auxOneValue": { "type": [ "string", "null" ] }, "auxTwoValue": { "type": [ "string", "null" ] }, "auxThreeValue": { "type": [ "string", "null" ] } }, "description": "Pass Auxiliary default values" }, "backFields": { "type": "object", "properties": { "backOne": { "type": [ "string", "null" ] }, "backTwo": { "type": [ "string", "null" ] }, "backThree": { "type": [ "string", "null" ] }, "backFour": { "type": [ "string", "null" ] }, "backFive": { "type": [ "string", "null" ] } }, "description": "Pass Back Field Labels" }, "backFieldValues": { "type": "object", "properties": { "backOneValue": { "type": [ "string", "null" ] }, "backTwoValue": { "type": [ "string", "null" ] }, "backThreeValue": { "type": [ "string", "null" ] }, "backFourValue": { "type": [ "string", "null" ] }, "backFiveValue": { "type": [ "string", "null" ] } }, "description": "Pass Back Field default values" } } } } } } }, "beacons": { "type": "object", "properties": { "data": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/ibeacon" } ] }, "maxItems": 10 }, "actions": { "$ref": "#/components/schemas/beaconActions" } }, "description": "Array of iBeacons, currently only available on Apple devices, due to Android device restrictions. Maximum of 10 iBeacons per pass.\n To update an existing iBeacon, include the proximityUUID, major and minor values in the data array while sending a PATCH request. Only relevantText can be updated. For more actions, use the beaconActions object." }, "beacon": { "description": "Beacon object", "type": "object", "properties": { "name": { "type": "string", "description": "Name of the beacon, used for display purposes only", "example": "West Entrance" }, "proximityUuid": { "type": "string", "description": "Unique identifier of the beacon", "example": "E2C56DB5-DFFB-48D2-B060-D0F5A71096E0" }, "major": { "type": "integer", "description": "Major Value, provides additional identification for a beacon", "minimum": 0, "maximum": 65535, "example": 1246 }, "minor": { "type": "integer", "description": "Minor Value, provides additional identification for a beacon", "minimum": 0, "maximum": 65535, "example": 6421 }, "message": { "type": [ "string", "null" ], "description": "Message to display on lock screen when the user is in range of the beacon", "example": "You're near my store", "minimum": 5, "maximum": 350 } }, "required": [ "name", "proximityUuid" ] }, "serializedBeacon": { "type": "object", "properties": { "proximityUuid": { "type": "string", "description": "Unique identifier of the beacon", "example": "E2C56DB5-DFFB-48D2-B060-D0F5A71096E0" }, "major": { "type": "integer", "description": "Major Value, provides additional identification for a beacon", "example": 65535 }, "minor": { "type": "integer", "description": "Minor Value, provides additional identification for a beacon", "example": 8525 }, "message": { "type": [ "string", "null" ], "description": "Message to display on lock screen when the user is in range of\n the beacon", "example": "You're near my store", "minimum": 5, "maximum": 350 }, "name": { "type": "string", "description": "Name of the beacon, used for display purposes only", "example": "West Entrance" } } }, "ibeacon": { "type": "object", "properties": { "proximityUUID": { "type": "string", "description": "Unique identifier of a beacon", "example": "F8F589E9-C07E-58B0-AEAB-A36BE4D48FAC" }, "major": { "type": "integer", "description": "Major Value, provides additional identification for a beacon", "example": "65535" }, "minor": { "type": "integer", "description": "Minor Value, provides additional identification for a beacon", "example": "8525" }, "relevantText": { "type": "string", "description": "Text to display on lock screen when the user is in range of the beacon", "example": "You're near my store", "minimum": 5, "maximum": 350 } }, "description": "iBeacon object" }, "beaconActions": { "type": "object", "properties": { "deleteAll": { "type": "boolean", "description": "Delete all beacons. Data array must be empty." }, "replaceAll": { "type": "boolean", "description": "Include ibeacons in the data array. When this action is invoked, all existing beacons are deleted, and replaced with the new beacons." }, "delete": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/ibeacon" } ] }, "description": "Array of iBeacons to delete" } }, "description": "Actions to perform on beacons, only one at a time. Must be called using method PATCH" }, "passLocations": { "type": "object", "properties": { "data": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/passLocation" } ] }, "maxItems": 10 }, "actions": { "$ref": "#/components/schemas/passLocationActions" } }, "description": "Array of locations. Maximum of 10 locations per pass.\nTo update an existing location, include latitude and longitued values in the data array while sending a PATCH request.\nOnly relevantText and maxDistance values can be updated.\nFor more actions, use the beaconActions object.", "deprecated": true }, "passLocation": { "type": "object", "properties": { "latitude": { "type": "number", "format": "double", "description": "Latitude of the location in degrees", "example": 51.54321132456805 }, "longitude": { "type": "number", "format": "double", "description": "Longitude of the location in degrees", "example": -0.022901231803803924 }, "maxDistance": { "type": "integer", "description": "Specifies the maximum radius distance in meters. If passType is eventTicket, max is 1000. Otherwise, max is 100.\nCurrently only available on Apple devices, due to Android device restrictions.", "example": 400, "minimum": 10 }, "relevantText": { "type": "string", "description": "Text to display on lock screen when the user is in range of the location.\nCurrently only available on Apple devices, due to Android device restrictions.", "example": "You're near my store", "minimum": 5, "maximum": 350 } }, "description": "Location object" }, "location": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the location, used for display purposes only", "example": "West Entrance" }, "latitude": { "type": "number", "format": "double", "description": "Latitude of the location", "example": 51.54321132456805 }, "longitude": { "type": "number", "format": "double", "description": "Longitude of the location", "example": -0.022901231803803924 }, "radius": { "type": "integer", "description": "Effective geofence radius of the location in meters. Maximum is 1000 for eventTicket passes, 100 for other pass types.\nCurrently only available on Apple devices, due to Android device restrictions.", "example": 90, "minimum": 10, "maximum": 1000, "default": 100 }, "message": { "type": "string", "description": "Message to display when user enters geofence.\nCurrently only available on Apple devices, due to Android device restrictions.", "example": "Welcome! Enjoy the show!", "minimum": 5, "maximum": 350 } }, "required": [ "latitude", "longitude", "name" ] }, "serializedLocation": { "description": "Location object", "type": "object", "properties": { "name": { "type": "string", "description": "Name of the location, used for display purposes only", "example": "West Entrance" }, "latitude": { "type": "number", "format": "double", "description": "Latitude of the location", "example": 51.54321132456805 }, "longitude": { "type": "number", "format": "double", "description": "Longitude of the location", "example": -0.022901231803803924 }, "radius": { "type": "integer", "description": "Effective geofence radius of the location in meters. Maximum is 1000 for eventTicket passes, 100 for other pass types.\nCurrently only available on Apple devices, due to Android device restrictions.", "example": 90, "minimum": 10, "maximum": 1000, "default": 100 }, "message": { "type": "string", "description": "Message to display when user enters geofence.\nCurrently only available on Apple devices, due to Android device restrictions.", "example": "Welcome! Enjoy the show!", "minimum": 5, "maximum": 350 }, "address": { "type": "string", "description": "Geocoded address of the location. Used for display purposes only. This is calculated automatically from the latitude and longitude values", "example": "Mick's Garage, Queens Yard, London, England, E9 5EN, United Kingdom" } } }, "passLocationActions": { "type": "object", "properties": { "deleteAll": { "type": "boolean", "description": "Delete all locations. Data array must be empty." }, "replaceAll": { "type": "boolean", "description": "Include locations in the data array. When this action is invoked, all existing locations are deleted, and replaced with the new locations." }, "delete": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/passLocation" } ] }, "description": "Array of locations to delete" } }, "description": "Actions to perform on locations, only one at a time. Must be called using method PATCH" }, "notification": { "type": "object", "properties": { "notification": { "type": "object", "properties": { "message": { "type": "string", "description": "Push message to be sent" } } } } }, "errors": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } } }, "notificationStatusHeader": { "type": "string", "description": "Present when request contains a push notification message", "enum": [ "delivered", "notDelivered" ], "x-enumDescriptions": { "delivered": "Notification delivered succesfully, push message displayed on device", "notDelivered": "Notification not delivered" } }, "notificationMeta": { "type": "object", "properties": { "notifications": { "type": "object", "description": "Only present if response headers include X-Notification-Status", "properties": { "status": { "type": "string", "enum": [ "delivered", "notDelivered" ], "x-enumDescriptions": { "delivered": "Notification delivered succesfully, push message displayed on device", "notDelivered": "Notification not delivered, more details under `message` key" } }, "message": { "type": "string", "description": "Notification delivery details", "example": "Delivered succesfully" } } } } }, "indexMeta": { "type": "object", "properties": { "totalCount": { "type": "integer", "description": "Total count of records returned" }, "resultsPerPage": { "type": "integer", "description": "Number of records returned per page. Set using the perPage query parameter." }, "currentPage": { "type": "integer", "description": "Index of current page" }, "totalPages": { "type": "integer", "description": "Total pages returned" } } }, "indexLinks": { "type": "object", "properties": { "first": { "type": [ "string", "null" ], "description": "Path to first page, null if currentPage is first page" }, "prev": { "type": [ "string", "null" ], "description": "Path to prev page, null if currentPage is first page" }, "next": { "type": [ "string", "null" ], "description": "Path to next page, null if currentPage is last page" }, "last": { "type": [ "string", "null" ], "description": "Path to last page, null if currentPage is last page" } } }, "webhook": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": " Auto-generated UUID of the webhook", "example": "018d8e07-beaa-7634-80a8-647cd33d6bb3" }, "type": { "type": "string", "example": "webhook" }, "attributes": { "type": "object", "properties": { "timeStamp": { "type": "string", "description": "In ISO8601 format, UTC. Used to determine when the\n webhook was triggered", "example": "2022-09-15T11:45:00Z" }, "webhookType": { "$ref": "#/components/schemas/webhookType" } } }, "relationships": { "type": "object", "description": "Relationships to other resources.", "properties": { "pass": { "$ref": "#/components/schemas/passRelationship" }, "passTap": { "$ref": "#/components/schemas/passTapRelationship" }, "scan": { "$ref": "#/components/schemas/scanRelationship" }, "reader": { "$ref": "#/components/schemas/readerRelationship" } } } } }, "included": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/serializedPassObject" }, { "$ref": "#/components/schemas/serializedScanObject" }, { "$ref": "#/components/schemas/serializedReaderObject" } ] } } } }, "passRelationship": { "type": "object", "properties": { "pass": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Auto-generated UUID of the pass", "example": "e89b1330fc391ec89656f3c664318cff8805471e" }, "type": { "type": "string", "example": "pass" } } } } } } }, "passTapRelationship": { "type": "object", "properties": { "passTap": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Auto-generated UUID of the pass tap", "example": "857e764e-ec8d-4348-abfb-25f379983eaf" }, "type": { "type": "string", "example": "passTap" } } } } } } }, "passTemplate": { "description": "Pass Template object", "type": "object", "properties": { "passTemplate": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the pass template, used for display purposes", "example": "PassEntry Supermarket" }, "centralTitle": { "type": "string", "description": "Used for Google Wallet Passes, pass Title", "example": "PassEntry Supermarket" }, "notificationHeader": { "type": "string", "description": "Header text to be displayed on notifications", "example": "PassEntry Supermarket" }, "description": { "type": "string", "description": "Description of the pass template.\nThis text is used as the notification header for Android geofencing alerts.", "example": "PassEntry Supermarket" }, "templateType": { "type": "string", "enum": [ "eventTicket", "loyalty", "generic", "transit" ], "description": "Type of pass template, determines the design and functionality of the pass" }, "defaultLanguage": { "type": "string", "description": "Language code (ISO 639-1) used as the default language for labels on this template", "example": "en" }, "colors": { "$ref": "#/components/schemas/passTemplateColors" }, "images": { "description": "Images for the pass template, must be direct links to publicly accessible HTTPS URLs. Review our design guidelines for more information.", "$ref": "#/components/schemas/passTemplateImages" }, "fields": { "$ref": "#/components/schemas/passTemplateFields" }, "appLinking": { "$ref": "#/components/schemas/appLinking" }, "locations": { "$ref": "#/components/schemas/passTemplateLocations" }, "beacons": { "$ref": "#/components/schemas/passTemplateBeacons" }, "nfc": { "$ref": "#/components/schemas/nfc" }, "barcode": { "$ref": "#/components/schemas/barcode" }, "loyaltyBalance": { "$ref": "#/components/schemas/passTemplateLoyaltyBalance" }, "googleNfcEnabled": { "type": "boolean", "description": "For loyalty templates, if true, pass will be enabled for Google Wallet NFC." }, "transitType": { "$ref": "#/components/schemas/passTemplateTransitType", "description": "Transit type for the transit pass template.\n\n***Note**: This field is required for transit type passes.*" }, "hasDynamicForm": { "type": "boolean", "description": "If true, pass template has a dynamic pass issuance form associated with it." }, "enhancedEventTicket": { "type": "object", "description": "Configuration for Apple's poster event ticket experience (iOS 18+). Only available on event ticket templates and requires both NFC and pass binding entitlements. When images are provided, passes render as full-bleed poster event tickets on iOS 18+ and fall back to the legacy event ticket layout on older devices.\n\n***Note**: This feature is in **closed beta**. The API structure may change and you may encounter bugs. Please contact PassEntry for access.*", "properties": { "images": { "type": "object", "description": "Images for the poster event ticket experience. Providing artwork enables the poster event ticket layout.", "properties": { "artwork": { "type": "string", "description": "Full-bleed background of the poster event ticket on iOS 18+. Required to enable poster event ticket layout. Maximum size: 1074x1344 px. Avoid placing important content near top and bottom edges as they overlap with header and chin regions.", "example": "https://www.example.com/artwork.png" }, "secondaryLogo": { "type": "string", "description": "Displayed in the bottom right of the pass chin. Intended to represent the ticket issuer or platform. Maximum size: 405x36 px.", "example": "https://www.example.com/secondary-logo.png" }, "venueMap": { "type": "string", "description": "Static image of the venue layout, displayed in the event guide. Maximum size: 3072x3072 px. 16:9 to 4:5 aspect ratio recommended.", "example": "https://www.example.com/venue-map.png" } }, "required": [ "artwork" ] } } } }, "required": [ "name", "description", "templateType", "defaultLanguage", "centralTitle", "notificationHeader", "colors", "fields", "images" ] } }, "required": [ "passTemplate" ] }, "serializedPassTemplate": { "title": "Pass template", "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the pass template", "example": "19cb334f9696e64e10e7759f0" }, "type": { "type": "string", "example": "passTemplate" }, "attributes": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the pass template, used for display purposes", "example": "PassEntry Supermarket" }, "entityId": { "type": "integer", "description": "ID of the entity this pass template belongs to", "example": 1 }, "templateType": { "description": "Type of pass template, determines the design and functionality of the pass", "$ref": "#/components/schemas/passType" }, "transitType": { "$ref": "#/components/schemas/passTemplateTransitType" }, "defaultLanguage": { "type": "string", "description": "Language code (ISO 639-1) used as the default language for labels on this template", "example": "en" }, "centralTitle": { "type": "string", "description": "Used for Google Wallet Passes, pass Title", "example": "PassEntry Supermarket" }, "notificationHeader": { "type": "string", "description": "Header text to be displayed on notifications", "example": "PassEntry Supermarket" }, "status": { "type": "string", "description": "Lifecycle status of the pass template.", "enum": [ "draft", "published" ], "example": "published" }, "colors": { "$ref": "#/components/schemas/passTemplateColors" }, "images": { "description": "Images for the pass template, will be direct link URLs", "$ref": "#/components/schemas/passTemplateImages" }, "fields": { "$ref": "#/components/schemas/passTemplateFields" }, "appLinking": { "$ref": "#/components/schemas/appLinking" }, "locations": { "type": "array", "maximum": 10, "description": "Array of locations. Maximum of 10 locations", "items": { "$ref": "#/components/schemas/serializedLocation" } }, "beacons": { "$ref": "#/components/schemas/passTemplateBeacons" }, "barcode": { "$ref": "#/components/schemas/barcode" }, "loyaltyBalance": { "$ref": "#/components/schemas/passTemplateLoyaltyBalance" }, "googleNfcEnabled": { "type": "boolean", "description": "Only included on loyalty templates, if true, pass will be enabled for Google Wallet NFC." }, "hasDynamicForm": { "type": "boolean", "description": "If true, pass template has a dynamic pass issuance form associated with it." }, "enhancedEventTicket": { "type": "object", "description": "Poster event ticket configuration. Only present on event ticket templates with enhanced event ticket enabled.\n\n***Note**: This feature is in **closed beta**. The API structure may change and you may encounter bugs. Please contact PassEntry for access.*", "properties": { "images": { "type": "object", "description": "Poster event ticket images.", "properties": { "artwork": { "type": "string", "description": "URL of the artwork image." }, "secondaryLogo": { "type": "string", "description": "URL of the secondary logo image." }, "venueMap": { "type": "string", "description": "URL of the venue map image." } } } } } } } } }, "serializedProcessingPassTemplate": { "type": "object", "title": "Processing pass template", "properties": { "id": { "type": "string", "description": "Unique identifier for the pass template", "example": "19cb334f9696e64e10e7759f0" }, "type": { "type": "string", "example": "passTemplate" }, "attributes": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the pass template, used for display purposes", "example": "PassEntry Supermarket" }, "templateType": { "type": "string", "description": "Type of pass template, determines the design and functionality of the pass", "enum": [ "eventTicket", "loyalty", "generic", "transit" ] }, "transitType": { "$ref": "#/components/schemas/passTemplateTransitType" }, "processingStatus": { "type": "string", "description": "Processing status of the pass template", "enum": [ "processing", "processed", "failed", "updating" ] }, "status": { "type": "string", "description": "Lifecycle status of the pass template.", "enum": [ "draft", "published" ], "example": "published" } } }, "meta": { "type": "object", "properties": { "message": { "type": "string", "description": "Processing status message", "example": "Your pass template is being processed, please check again in a few moments." }, "links": { "type": "object", "properties": { "self": { "type": "string", "description": "URL to the pass template. Use this URL to retrieve the pass template once it has been processed.", "example": "https://api.passentry.com/v1/pass-templates/19cb334f9696e64e10e7759f0" } } } } } } }, "passTemplateColors": { "type": "object", "properties": { "background": { "type": "string", "description": "Background color of the pass template", "example": "#EFEFEF" }, "label": { "type": "string", "description": "Label color of the pass template", "example": "#FF8477" }, "text": { "type": "string", "description": "Text color of the pass template", "example": "#29323A" } } }, "passTemplateImages": { "type": "object", "properties": { "banner": { "type": "string", "description": "Banner image URL, used unless platform specific images are provided", "example": "https://example.com/banner.png" }, "logo": { "type": "string", "description": "Logo image URL, used unless platform specific images are provided", "example": "https://example.com/logo.png" }, "icon": { "type": "string", "description": "Icon image URL, used unless platform specific images are provided", "example": "https://example.com/icon.png" }, "watermark": { "description": "PassEntry logo watermark. To remove watermark, contact Sales at PassEntry. Otherwise, watermak is required", "$ref": "#/components/schemas/imageWatermark" }, "apple": { "type": "object", "properties": { "banner": { "type": "string", "description": "Banner image URL, used for Apple Wallet", "example": "https://example.com/apple_banner.png" }, "logo": { "type": "string", "description": "Logo image URL, used for Apple Wallet", "example": "https://example.com/apple_logo.png" }, "icon": { "type": "string", "description": "Icon image URL, used for Apple Wallet", "example": "https://example.com/apple_icon.png" }, "thumbnail": { "type": "string", "description": "Thumbnail image URL, used for Apple Wallet", "example": "https://example.com/apple_thumbnail.png" }, "watermark": { "description": "PassEntry logo watermark. To remove watermark, contact Sales at PassEntry. Otherwise, watermak is required", "$ref": "#/components/schemas/imageWatermark" } } }, "google": { "type": "object", "properties": { "banner": { "type": "string", "description": "Banner image URL, used for Google Wallet", "example": "https://example.com/google_banner.png" }, "logo": { "type": "string", "description": "Logo image URL, used for Google Wallet", "example": "https://example.com/google_logo.png" }, "wideLogo": { "type": "string", "description": "Wide logo image URL, used for Google Wallet", "example": "https://example.com/google_wide_logo.png" }, "watermark": { "description": "PassEntry logo watermark. To remove watermark, contact Sales at PassEntry. Otherwise, watermak is required", "$ref": "#/components/schemas/imageWatermark" } } } } }, "appLinking": { "description": "Used to add a link on your pass to an app or website.", "type": "object", "properties": { "apple": { "type": "object", "properties": { "appStoreUrl": { "type": "array", "items": { "type": "string", "description": "Apple App Store app URL", "example": "https://apps.apple.com/gb/app/whatsapp-messenger/id310633997", "pattern": "^https://apps\\.apple\\.com/\\w+/app/.*/id\\d*$" }, "maxLength": 5 } } }, "google": { "type": "object", "description": "Link to your android App or website", "oneOf": [ { "title": "Web link", "properties": { "web": { "type": "object", "properties": { "url": { "type": "string", "description": "HTTPs URL web link, will open in browser when tapped", "example": "https://passentry.com/" } } } } }, { "title": "Android app link", "properties": { "app": { "type": "object", "oneOf": [ { "title": "Google Play package name", "properties": { "packageName": { "type": "string", "description": "Google Play package name, will open in Google Play App Store when tapped", "example": "com.whatsapp" } } }, { "title": "Google Play app URL", "properties": { "playStoreUrl": { "type": "string", "description": "Google Play app URL, will open in Google Play App Store when tapped", "example": "https://play.google.com/store/apps/details?id=com.whatsapp" } } } ] } } } ], "properties": { "displayText": { "type": "object", "properties": { "text": { "type": "string", "description": "Set custom text to be displayed as link text, default is 'Open Pass'" } } } } } } }, "nfc": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether the pass is NFC enabled." }, "source": { "type": "string", "enum": [ "extId", "custom", "uuid" ], "description": "Source of the NFC message", "x-enumDescriptions": { "extId": "Sets the pass extId as the NFC message, extId must be present", "uuid": "Sets the pass UUID as the NFC message", "custom": "Set a custom NFC message, using the customValue key" } }, "customValue": { "type": "string", "description": "Custom NFC message, source must be set to custom" } } }, "barcode": { "description": "Barcode for a pass template", "type": "object", "properties": { "enabled": { "type": "boolean", "description": "If true, barcode will be added to the pass" }, "type": { "type": "string", "description": "Barcode type", "enum": [ "qr", "code128", "aztec", "pdf417" ] }, "source": { "type": "string", "description": "Source of the barcode", "enum": [ "custom", "uuid", "extId" ] }, "value": { "type": "string", "description": "Barcode value. You can leave it blank if the value will be dynamically set in the pass, but you can also provide a default.\n\nYou can make the value dynamic using the `%{passData.xyz}` syntax (e.g., `Hello, %{passData.extId}`). Currently, only `%{passData.extId}` and `%{passData.uuid}` are supported.\n\nIf `source` is set to `extId` or `uuid`, the value will be automatically populated and can be left blank.", "example": "abc123" }, "displayText": { "type": "boolean", "description": "If true, display the barcode value as text on the pass" } } }, "passTemplateLoyaltyBalance": { "type": "object", "description": "Loyalty balance for the pass template.", "properties": { "enabled": { "type": "boolean", "description": "If enabled, pass will have a loyalty balance field that can be updated via the loyalty API." }, "numberType": { "type": "string", "description": "Type of number to be displayed on the pass, number will be converted to this type.", "enum": [ "integer", "decimal" ] } } }, "passTemplateTransitType": { "type": "string", "description": "Transit type for the transit pass template", "enum": [ "airplane", "bus", "train", "ferry", "other" ] }, "passTemplateFields": { "description": "Fields for the pass template, for exact positioning of fields please review our design guidelines", "type": "object", "properties": { "header": { "$ref": "#/components/schemas/headerField" }, "central": { "$ref": "#/components/schemas/centralField" }, "details": { "$ref": "#/components/schemas/detailsField" }, "back": { "$ref": "#/components/schemas/backField" } } }, "passTemplateLocations": { "type": "array", "maximum": 10, "description": "Array of locations. Maximum of 10 locations", "items": { "$ref": "#/components/schemas/location" } }, "passTemplateBeacons": { "type": "array", "maximum": 10, "description": "Array of beacons, currently only available on Apple devices, due to Android device restrictions. Maximum of 10 beacons", "items": { "$ref": "#/components/schemas/beacon" } }, "headerField": { "type": "object", "properties": { "one": { "$ref": "#/components/schemas/field" }, "two": { "$ref": "#/components/schemas/field" } } }, "centralField": { "type": "object", "description": "Central field for the pass template.\n\n **Note**: Please use both `one` and `two` fields for `transit` type", "properties": { "one": { "$ref": "#/components/schemas/field" }, "two": { "$ref": "#/components/schemas/field" } } }, "detailsField": { "type": "object", "properties": { "one": { "$ref": "#/components/schemas/field" }, "two": { "$ref": "#/components/schemas/field" }, "three": { "$ref": "#/components/schemas/field" }, "four": { "$ref": "#/components/schemas/field" }, "five": { "$ref": "#/components/schemas/field" }, "six": { "$ref": "#/components/schemas/field" } } }, "backField": { "type": "object", "properties": { "one": { "$ref": "#/components/schemas/field" }, "two": { "$ref": "#/components/schemas/field" }, "three": { "$ref": "#/components/schemas/field" }, "four": { "$ref": "#/components/schemas/field" }, "five": { "$ref": "#/components/schemas/field" }, "six": { "$ref": "#/components/schemas/field" } } }, "field": { "description": "Field object. Set value to null to remove the field.", "type": "object", "properties": { "id": { "type": "string", "description": "Field ID, used to to target and identify a specific field. Must be unique within the pass template or pass. Required if field is used.", "uniqueItems": true, "example": "membership_tier" }, "label": { "type": "string", "description": "Label of the field. This will be displayed to the user in the pass.", "example": "Membership Tier" }, "defaultValue": { "description": "Default value of the field. This will be displayed to the user in the pass if no value is provided.", "type": "string", "example": "Gold" }, "localisation": { "type": "object", "minProperties": 1, "additionalProperties": { "type": "object", "properties": { "label": { "type": "string", "description": "Localised label to be displayed for this field when the user language matches the provided language code" }, "defaultValue": { "type": "string", "description": "Localised default value to be displayed for this field when the user language matches the provided language code" } } }, "description": "Optional. Localised overrides for field labels and values, keyed by BCP-47/ISO language code (e.g., en, fr, is). Omitted entirely if no translations are provided. **This feature is available on request and works only via the Pass Templates API (not dashboard), please contact PassEntry to enable localisation for your organisation.**" } } }, "fieldUpdate": { "allOf": [ { "$ref": "#/components/schemas/field" } ], "properties": { "overrideFieldValue": { "description": "Set this boolean to true to override all existing pass values with the new default.\n\nIf not set, the default value will only apply to newly created passes; existing passes will remain unchanged.\n\n**Note: Use this key only when updating the default value of a field.**", "type": "boolean", "example": true } } }, "nfcUpdate": { "allOf": [ { "$ref": "#/components/schemas/nfc" } ], "properties": { "overrideNfc": { "description": "Set this boolean to true to apply the new NFC configuration to all existing passes on this template.\n\nIf not set (or `false`), NFC changes only apply to newly created passes; existing passes keep their current NFC settings.\n\nWhen the override runs, PassEntry resolves the NFC message per pass: `uuid` uses each pass's UUID, `extId` uses each pass's `extId`, and `custom` uses the `customValue`. Passes are skipped when the pass's entity does not have NFC access, or when `source` is `extId` and the pass has no `extId`.\n\n**Note: Only valid on Update Pass Template. Sending it on Create Pass Template has no effect since there are no existing passes to override.**", "type": "boolean", "example": true } } }, "barcodeUpdate": { "allOf": [ { "$ref": "#/components/schemas/barcode" } ], "properties": { "overrideBarcode": { "description": "Set this boolean to true to apply the new barcode configuration to all existing passes on this template.\n\nIf not set (or `false`), barcode changes only apply to newly created passes; existing passes keep their current barcode settings.\n\nWhen the override runs, PassEntry resolves the barcode value per pass: `uuid` uses each pass's UUID, `extId` uses each pass's `extId`, and `custom` uses the provided `value`. Passes are skipped when `source` is `extId` and the pass has no `extId`.\n\n**Note: Only valid on Update Pass Template. Sending it on Create Pass Template has no effect since there are no existing passes to override.**", "type": "boolean", "example": true } } }, "imageWatermark": { "type": "object", "properties": { "color": { "type": "string", "enum": [ "light", "dark" ], "description": "Color of the watermark, light or dark" }, "position": { "type": "string", "enum": [ "topLeft", "topRight", "bottomLeft", "bottomRight" ], "description": "Position of the watermark, top left, top right, bottom left, or bottom right" } } }, "passType": { "type": "string", "enum": [ "generic", "loyalty", "eventTicket", "transit" ] }, "scanRelationship": { "type": "object", "properties": { "scan": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Auto-generated UUID of the scan", "example": "0194a887-f880-703f-b8cf-16c1ea804b08" }, "type": { "type": "string", "example": "scan" } } } } } } }, "imageAsset": { "type": "object", "properties": { "imageAsset": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "description": "Name of the image asset. Maximum 255 characters. Must be unique within the same entity if provided", "example": "Silver tier banner" }, "imageType": { "type": "string", "description": "Type of the image asset", "example": "banner", "enum": [ "banner", "logo", "thumbnail", "artwork", "secondaryLogo", "venueMap" ] }, "image": { "type": "string", "description": "Direct HTTPS image URL or base64 encoded data URI. Supported formats: PNG, JPG, WebP", "example": "https://example.com/silver_tier_banner.png" }, "entityId": { "type": "string", "description": "UUID of the target entity. Only required for organisation-level API keys. Entity-level API keys automatically use their scoped entity", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "watermark": { "type": "object", "description": "Watermark configuration. Only allowed when imageType is banner. Required for banner images when watermarking is enabled for your organisation", "properties": { "color": { "type": "string", "description": "Watermark colour", "enum": [ "dark", "light" ] }, "position": { "type": "string", "description": "Watermark position on the image", "enum": [ "bottomLeft", "bottomRight", "topLeft", "topRight" ] } }, "required": [ "color", "position" ] } }, "required": [ "imageType", "image" ] } } }, "serializedImageAsset": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the image asset", "example": "19cb334f9696e64e10e7759f0" }, "type": { "type": "string", "description": "Resource type", "example": "imageAsset" }, "attributes": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the image asset", "example": "Silver tier banner" }, "imageType": { "type": "string", "description": "Type of the image asset", "example": "banner", "enum": [ "banner", "logo", "thumbnail", "artwork", "secondaryLogo", "venueMap" ] }, "processingStatus": { "type": "string", "description": "Current processing status of the image asset", "example": "pending", "enum": [ "pending", "successful", "failed" ] }, "size": { "type": "object", "properties": { "width": { "type": "integer", "description": "Width of the image asset", "example": 1125 }, "height": { "type": "integer", "description": "Height of the image asset", "example": 432 } } }, "entityId": { "type": "string", "description": "UUID of the entity this image asset belongs to", "example": "a1b2c3d4" }, "createdAt": { "type": "string", "description": "Timestamp of when the image asset was created", "example": "2026-03-01T12:00:00Z" }, "url": { "type": "string", "description": "URL of the original image. This URL may change over time, so do not store or cache it. Always fetch the latest URL from the API when needed.", "example": "https://cdn.passentry.com/image-assets/99/553085/19cb334f9696e64e10e7759f0.png" }, "watermark": { "type": [ "object", "null" ], "description": "Watermark configuration. Only present for banner image assets when watermarking is enabled", "properties": { "color": { "type": "string", "description": "Watermark colour", "enum": [ "dark", "light" ], "example": "light" }, "position": { "type": "string", "description": "Watermark position on the image", "enum": [ "bottomLeft", "bottomRight", "topLeft", "topRight" ], "example": "bottomRight" } } } } } } } } }, "serializedImageAssetsList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/serializedImageAsset" } }, "meta": { "$ref": "#/components/schemas/indexMeta" }, "links": { "$ref": "#/components/schemas/indexLinks" } } }, "scanMeta": { "type": "object", "properties": { "successfulScans": { "type": "integer", "description": "Total count of successful scans" }, "failedScans": { "type": "integer", "description": "Total count of failed scans" }, "readersCount": { "type": "integer", "description": "Total count of readers" }, "totalCount": { "type": "integer", "description": "Total count of records returned" }, "resultsPerPage": { "type": "integer", "description": "Number of records returned per page. Set using the perPage query parameter." }, "currentPage": { "type": "integer", "description": "Index of current page" }, "totalPages": { "type": "integer", "description": "Total pages returned" } } }, "readerRelationship": { "type": "object", "properties": { "reader": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Reader ID", "example": "CC202952" }, "type": { "type": "string", "example": "reader" } } } } } } }, "webhookType": { "type": "string", "description": "Type of webhook", "enum": [ "passInstalled", "passRemoved", "passTapped", "passScanned", "passCreated" ], "x-enumDescriptions": { "passInstalled": "Pass added to wallet by user", "passRemoved": "Pass removed from wallet by user", "passTapped": "(deprecated) Pass tapped on NFC reader", "passScanned": "NFC or barcode pass scanned by reader", "passCreated": "Pass created" } }, "readerAttributes": { "type": "object", "properties": { "name": { "type": "string", "description": "Friendly display name of the reader", "example": "South Entrance Reader 1" }, "id": { "type": "string", "description": "Identifier of the reader", "example": "south_entrance_01" }, "type": { "type": "string", "description": "Type of reader: VtapReader or PassentryReader", "enum": [ "VtapReader", "PassentryReader" ] }, "password": { "type": "string", "description": "Reader password. Required for PassentryReader type" }, "scanEnabled": { "type": "boolean", "description": "Whether the reader is enabled for scanning. Only present for PassentryReader type.", "default": true }, "redeemEnabled": { "type": "boolean", "description": "Whether the reader is enabled for redeeming. Only present for PassentryReader type.", "default": false }, "addPointsEnabled": { "type": "boolean", "description": "Whether the reader is enabled for adding points. Only present for PassentryReader type.", "default": false }, "mifareClassicNfcEnabled": { "type": "boolean", "description": "Whether the reader is enabled for Mifare Classic NFC scanning. Only present for PassentryReader type.", "default": false }, "qrEnabled": { "type": "boolean", "description": "Whether the reader is enabled for QR code scanning. Only present for PassentryReader type.", "default": false } } }, "createReader": { "type": "object", "properties": { "reader": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/readerAttributes" } ], "required": [ "name", "id", "type" ] } } }, "updateReader": { "type": "object", "properties": { "reader": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/readerAttributes" } ] } } }, "serializedReaderObject": { "type": "object", "properties": { "id": { "type": "string", "description": "Identifier of the reader", "example": "west_entrance_01" }, "type": { "type": "string", "example": "reader" }, "attributes": { "type": "object", "properties": { "name": { "type": "string", "description": "Friendly display name of the reader" }, "readerType": { "type": "string", "description": "Type of reader: VtapReader or PassentryReader" }, "lastSeenAt": { "type": "string", "description": "Timestamp of the last time the reader was seen. Only present for PassentryReader type" }, "loggedIn": { "type": "boolean", "description": "Whether the reader is currently logged in. Only present for PassentryReader type" }, "scanEnabled": { "type": "boolean", "description": "Whether the reader is enabled for scanning. Only present for PassentryReader type" }, "redeemEnabled": { "type": "boolean", "description": "Whether the reader is enabled for redeeming. Only present for PassentryReader type" }, "addPointsEnabled": { "type": "boolean", "description": "Whether the reader is enabled for adding points. Only present for PassentryReader type" }, "mifareClassicNfcEnabled": { "type": "boolean", "description": "Whether the reader is enabled for Mifare Classic NFC scanning. Only present for PassentryReader type" }, "qrEnabled": { "type": "boolean", "description": "Whether the reader is enabled for QR code scanning. Only present for PassEntryReader type" } } } } }, "serializedReaderConfigurationObject": { "type": "object", "properties": { "id": { "type": "string", "description": "Entity UUID" }, "attributes": { "type": "object", "properties": { "nfcPrivateKey": { "type": "string", "description": "Cryptographic private key that ensures that the NFC passes are securely transmitted and validated." }, "googleCollectorID": { "type": "string", "description": "8-digit numeric ID used by the reader to identify itself and request specific passes from the Google Wallet." }, "googleKeyVersion": { "type": "string", "description": "Version of the cryptographic key for securing communications with Google." }, "applePassTypeId": { "type": "string", "description": "ID used by the reader to request specific passes from the Apple Wallet." }, "readerConfigurationApiKey": { "type": "string", "description": "PassEntry API key used for authenticating the reader." }, "validationConfiguration": { "type": "object", "description": "Validation configuration for the reader.", "properties": { "validationType": { "type": "string", "description": "Type of validation: 'internal' for PassEntry Validation or 'external' for Third-Party Validation." }, "validityPeriod": { "type": "integer", "description": "Validity period in seconds for 'internal' validation." }, "externalEndpointUrl": { "type": "string", "description": "URL of the external endpoint for 'external' validation." } } } } } } }, "scanAttributes": { "type": "object", "properties": { "readerId": { "type": "string", "description": "UUID of the reader that scanned the pass" }, "passId": { "type": "string", "description": "ID (uuid or ext_id) of the pass that was scanned" }, "scanType": { "type": "string", "description": "Type of scan: nfc or barcode", "enum": [ "nfc", "barcode" ] }, "loyalty": { "type": "object", "properties": { "balance": { "type": "number", "description": "Balance to add or redeem. Can't be used together with balanceOverride." }, "balanceOverride": { "type": "number", "description": "Balance to override the pass balance with. Can't be used together with balance." }, "message": { "type": "string", "description": "Notification message to send after the operation" } } } } }, "logScanAttributes": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/scanAttributes" }, { "type": "object", "properties": { "scanValue": { "type": "string", "description": "The raw value read by the reader during the scan" }, "status": { "type": "string", "description": "Status of the scan based on third party validation", "enum": [ "successful", "failed" ] }, "statusDetail": { "type": "string", "description": "Detailed status message including error details" } } } ], "required": [ "readerId", "scanType", "scanValue", "status" ] }, "createScan": { "type": "object", "properties": { "scan": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/scanAttributes" } ], "required": [ "readerId", "passId", "scanType" ] } } }, "logScan": { "type": "object", "properties": { "scan": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/logScanAttributes" } ] } } }, "validationResponse": { "type": "object", "properties": { "status": { "type": "string", "description": "Status of the validation: 'successful' or 'failed'", "enum": [ "successful", "failed" ] }, "statusDetail": { "type": "string", "description": "Detailed status of the validation including error details" }, "readerInstructions": { "type": "object", "oneOf": [ { "type": "object", "title": "Passentry Reader", "properties": { "message": { "type": "string", "description": "Message to be displayed by the reader." } } }, { "type": "object", "title": "VTAP Reader", "properties": { "VTAPaction": { "type": "object", "properties": { "led": { "type": "string", "description": "Color of the LED to be displayed by the reader" }, "beep": { "type": "string", "description": "Sound to be played by the reader" }, "message": { "type": "string", "description": "Message to be displayed by the reader (not currently supported)" }, "success": { "type": "boolean", "description": "Whether the scan was successfully validated" } } } } } ] }, "loyalty": { "type": "object", "properties": { "balanceChange": { "type": "string", "description": "Amount of points added or subtracted from the balance" }, "updatedBalance": { "type": "string", "description": "Updated balance after the operation" }, "operation": { "type": "string", "description": "Operation performed: 'add', 'redeem', 'stamp' or 'balanceOverride'" } } } } }, "scanInfo": { "type": "object", "properties": { "scanId": { "type": "string", "description": "UUID of the scan" }, "scanType": { "type": "string", "description": "Type of scan: nfc or barcode", "enum": [ "nfc", "barcode" ] }, "scanValue": { "type": "string", "description": "The raw value read by the reader during the scan. For NFC, this is the encoded NFC message. For barcodes, this is the encoded barcode value." }, "validationType": { "type": "string", "description": "Type of validation: 'internal' for PassEntry Validation or 'external' for Third-Party Validation.", "enum": [ "internalValidation", "externalValidation" ] }, "status": { "type": "string", "description": "Status of the validation: 'successful' or 'failed'", "enum": [ "successful", "failed" ] }, "statusDetail": { "type": "string", "description": "Detailed status of the validation including error details" }, "scannedAt": { "type": "string", "description": "ISO8601 timestamp of the scan" }, "passId": { "type": "string", "description": "UUID of the pass that was scanned" }, "passExtId": { "type": "string", "description": "External ID of the pass that was scanned" }, "readerId": { "type": "string", "description": "UUID of the reader that scanned the pass" } } }, "internalValidationResponse": { "type": "object", "properties": { "validationResponse": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/validationResponse" } ] }, "scanInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/scanInfo" } ] } } }, "externalValidationResponse": { "type": "object", "properties": { "scanInfo": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/scanInfo" } ] } } }, "serializedPassTapObject": { "type": "object", "properties": { "id": { "type": "string", "description": "Auto-generated UUID of the pass tap", "example": "857e764e-ec8d-4348-abfb-25f379983eaf" }, "type": { "type": "string", "example": "passTap" }, "attributes": { "type": "object", "properties": { "tappedAt": { "type": "string", "description": "ISO8601 timestamp" }, "successful": { "type": "boolean", "description": "Whether the tap was successful" } } }, "relationships": { "type": "object", "description": "Relationships to other resources.", "allOf": [ { "$ref": "#/components/schemas/passRelationship" }, { "$ref": "#/components/schemas/readerRelationship" } ] } } }, "serializedScanObject": { "type": "object", "properties": { "id": { "type": "string", "description": "Auto-generated UUID of the scan", "example": "0194a887-f880-703f-b8cf-16c1ea804b08" }, "type": { "type": "string", "example": "scan" }, "attributes": { "type": "object", "properties": { "scanType": { "type": "string", "description": "Type of scan: nfc or barcode", "enum": [ "nfc", "barcode" ] }, "scanValue": { "type": "string", "description": "The raw value read by the reader during the scan. For NFC, this is the encoded NFC message. For barcodes, this is the encoded barcode value." }, "validationType": { "type": "string", "description": "Type of validation: 'internal' for PassEntry Validation or 'external' for Third-Party Validation.", "enum": [ "internalValidation", "externalValidation" ] }, "status": { "type": "string", "description": "Status of the validation: 'successful' or 'failed'", "enum": [ "successful", "failed" ] }, "statusDetail": { "type": "string", "description": "Detailed status of the validation including error details" }, "scannedAt": { "type": "string", "description": "ISO8601 timestamp of the scan" } } }, "relationships": { "type": "object", "description": "Relationships to other resources.", "allOf": [ { "$ref": "#/components/schemas/passRelationship" }, { "$ref": "#/components/schemas/readerRelationship" } ] } } }, "serializedWalletMessagingBatch": { "type": "object", "properties": { "id": { "type": "string", "description": "UUID of the batch" }, "type": { "type": "string", "description": "Type of batch", "enum": [ "walletMessaging" ] }, "attributes": { "type": "object", "properties": { "name": { "type": "string", "description": "Friendly name of the batch, used for display purposes. Auto-generated if not provided", "example": "PassEntry Supermarket Summer Promotion" }, "status": { "type": "string", "description": "Status of the batch", "enum": [ "validating", "scheduled", "failed", "sending", "successful", "completedWithErrors", "cancelled" ] }, "tag": { "type": [ "string", "null" ], "description": "Tag of the batch, used for grouping and filtering purposes", "example": "summerPromotion" }, "content": { "type": "string", "description": "Message content", "example": "Welcome to PassEntry Supermarket! We're excited to have you as a member. Get 10% off your first purchase by showing your pass at the till!" }, "totalRecipients": { "type": "integer", "description": "Total number of recipients in the batch", "example": 12000 }, "completedAt": { "type": "string", "description": "ISO8601 timestamp of when the batch was completed", "example": "2021-01-01T00:00:00Z" }, "scheduledAt": { "type": "string", "description": "ISO8601 timestamp of when the batch is scheduled to be sent", "example": "2022-01-01T00:00:00Z" }, "errorsCsvUrl": { "type": "string", "description": "If present, batch failed validation, or had some errors during delivery. URL to a CSV file containing errors and error details of the batch", "example": "https://example.com/errors.csv" } } } } }, "serializedPassCreationBatch": { "type": "object", "properties": { "id": { "type": "string", "description": "UUID of the batch" }, "type": { "type": "string", "description": "Type of batch", "enum": [ "passCreation" ] }, "attributes": { "type": "object", "properties": { "name": { "type": "string", "description": "Friendly name of the batch, used for display purposes. Auto-generated if not provided", "example": "PassEntry Batch #1" }, "status": { "type": "string", "description": "Status of the batch", "enum": [ "processing", "successful", "failed" ] }, "completedAt": { "type": "string", "description": "ISO8601 timestamp of when the batch was completed", "example": "2021-01-01T00:00:00Z" }, "passTemplateName": { "type": "string", "description": "Name of the pass template", "example": "PassEntry Ticketing" }, "passTemplateNameId": { "type": "string", "description": "ID of the pass template", "example": "acbb27e9cfb4e8f62f8cb999" }, "resultCsvUrl": { "type": "string", "description": "URL to a CSV file containing the results of the batch", "example": "https://example.com/errors.csv" }, "totalCount": { "type": "integer", "description": "If present, total number of passes created in the batch", "example": 100 }, "progress": { "type": "object", "description": "Shown when batch is processing. Progress of the batch, can be polled for real-time updates.", "properties": { "total": { "type": "integer", "description": "Total number of passes to be created in the batch", "example": 100 }, "processed": { "type": "integer", "description": "Number of passes processed in the batch", "example": 90 }, "pending": { "type": "integer", "description": "Number of passes pending to be created in the batch", "example": 10 } } } } } } }, "serializedPassUpdateBatch": { "type": "object", "properties": { "id": { "type": "string", "description": "UUID of the batch" }, "type": { "type": "string", "description": "Type of batch", "enum": [ "passUpdate" ] }, "attributes": { "type": "object", "properties": { "name": { "type": "string", "description": "Friendly name of the batch, used for display purposes. Auto-generated if not provided", "example": "PassEntry Summer Promotion Update #1" }, "status": { "type": "string", "description": "Status of the batch", "enum": [ "validating", "scheduled", "failed", "updating", "successful", "completedWithErrors", "cancelled" ] }, "tag": { "type": "string", "description": "Tag of the batch, used for grouping and filtering purposes", "example": "summerPromotion" }, "passTemplateName": { "type": "string", "description": "Name of the pass template", "example": "PassEntry Ticketing" }, "passTemplateNameId": { "type": "string", "description": "ID of the pass template", "example": "acbb27e9cfb4e8f62f8cb999" }, "completedAt": { "type": "string", "description": "ISO8601 timestamp of when the batch was completed", "example": "2021-01-01T00:00:00Z" }, "errorsCsvUrl": { "type": "string", "description": "If present, batch failed validation, or had some errors during update. URL to a CSV file containing errors and error details of the batch", "example": "https://example.com/errors.csv" }, "totalCount": { "type": "integer", "description": "If present, total number of passes to be updated in the batch", "example": 100 }, "progress": { "type": "object", "description": "Shown when batch is validating or updating. Progress of the batch, can be polled for real-time updates.", "properties": { "total": { "type": "integer", "description": "Total number of passes to be created in the batch", "example": 100 }, "processed": { "type": "integer", "description": "Number of passes processed in the batch", "example": 90 }, "pending": { "type": "integer", "description": "Number of passes pending to be created in the batch", "example": 10 } } } } } } }, "createWalletMessagingBatch": { "type": "object", "properties": { "batch": { "type": "object", "properties": { "message": { "type": "string", "description": "Message to be sent. Include %{variable} for dynamic content.", "example": "Hey %{memberName}, thank you for your purchase!" }, "scheduledAt": { "type": "string", "description": "ISO8601 timestamp of when the batch is scheduled to be sent" } }, "required": [ "message", "scheduledAt" ], "oneOf": [ { "title": "Segment-based targeting", "properties": { "segments": { "type": "array", "description": "Target recipients of the message. Each segment targets by pass template (`passTemplateId`), pass group tags (`groupTag`/`groupTags`), or entity UUID (`entityId`). **To message passes filtered by both pass template and group tags, send one segment of each type together** - the batch then targets passes on that template that also carry at least one of the tags. An entity segment targets all passes in the entity and cannot be combined with a pass template segment. Provide at most one segment of each type. `segments[].entityId` must match the entity `{id}` in the request URL.", "items": { "oneOf": [ { "type": "object", "title": "Pass Template segment", "properties": { "passTemplateId": { "type": "string", "description": "Pass Template UUID", "example": "426614174000" } } }, { "type": "object", "title": "Pass Group Tag segment", "properties": { "groupTag": { "type": "string", "description": "Pass group tag", "example": "summerPromotion" }, "groupTags": { "type": "array", "description": "Pass group tags. Passes matching any of the listed tags are included.", "example": [ "summerPromotion", "easterOffer" ] } } }, { "type": "object", "title": "Entity UUID segment", "properties": { "entityId": { "type": "string", "description": "Entity UUID", "example": "426614174000" } } } ] } } }, "required": [ "segments" ] }, { "title": "Recipient-based targeting", "properties": { "recipients": { "type": "array", "description": "Target recipients of the message. Must include at least one recipient.", "maxItems": 500, "items": { "type": "object", "properties": { "passId": { "type": "string", "description": "UUID of the pass", "example": "426614174000" }, "variables": { "type": "object", "description": "Variables to be replaced in the message", "example": { "name": "John Doe", "tier": "Gold" } } }, "required": [ "passId" ] } } }, "required": [ "recipients" ] } ] } } }, "createWalletMessagingBatchMultipart": { "type": "object", "properties": { "name": { "type": "string", "description": "Friendly name of the batch, used for display purposes. Auto-generated if not provided", "example": "PassEntry Supermarket Summer Promotion" }, "tag": { "type": "string", "description": "Tag of the batch, used for grouping and filtering purposes", "example": "summerPromotion" }, "csv": { "type": "string", "format": "binary", "description": "CSV file containing recipient data. 10 MB max size." }, "message": { "type": "string", "description": "Message to be sent. Include %{variable} for dynamic content." }, "scheduledAt": { "type": "string", "description": "ISO8601 timestamp of when the batch is scheduled to be sent" } }, "required": [ "csv", "message", "scheduledAt" ] }, "createPassCreationBatchMultipart": { "type": "object", "properties": { "name": { "type": "string", "description": "Friendly name of the batch, used for display purposes. Auto-generated if not provided", "example": "PassEntry Batch #1" }, "csv": { "type": "string", "format": "binary", "description": "CSV file containing pass data. 10 MB max size. Review the Batch Pass Creation guide for more information." }, "passTemplate": { "type": "string", "description": "Pass Template ID." } }, "required": [ "csv", "passTemplate" ] }, "createPassUpdateBatchMultipart": { "type": "object", "properties": { "name": { "type": "string", "description": "Friendly name of the batch, used for display purposes. Auto-generated if not provided", "example": "PassEntry Summer Promotion Update" }, "csv": { "type": "string", "format": "binary", "description": "CSV file containing pass data. 10 MB max size. Review the Batch Pass Update guide for more information." }, "tag": { "type": "string", "description": "Tag of the batch, used for grouping and filtering purposes", "example": "summerPromotion" }, "passTemplate": { "type": "string", "description": "Pass Template ID." }, "scheduledAt": { "type": "string", "description": "ISO8601 timestamp of when the batch is scheduled to be updated" } }, "required": [ "csv", "passTemplate", "scheduledAt" ] }, "batchSelfLink": { "type": "object", "properties": { "self": { "type": "string", "example": "https://api.passentry.com/api/v1/batches/d29455c9-afe4-4c73-b946-a5ea0b1667f7", "description": "Self link to the batch record" } } }, "rateLimitLimitHeader": { "type": "integer", "description": "Indicates the maximum number of requests allowed in the current period.", "example": 10 }, "rateLimitRemainingHeader": { "type": "integer", "description": "Shows the number of requests remaining in the current period.", "example": 5 }, "rateLimitResetHeader": { "type": "integer", "description": "Provides the timestamp (in UTC epoch seconds) when the current rate limit window resets. Only present when rate limit is exceeded.", "example": 1663242300 }, "webhookSubscriptionRequest": { "type": "object", "description": "Webhook subscription request configuration", "properties": { "webhookSubscription": { "type": "object", "properties": { "url": { "type": "string", "description": "HTTPS URL that will receive webhook events", "format": "uri", "pattern": "^https://.+", "example": "https://example.com/webhook" }, "enabled": { "type": "boolean", "description": "Whether the webhook subscription is active", "default": true }, "subscribedEvents": { "type": "array", "description": "List of events to subscribe to", "items": { "type": "string", "enum": [ "passInstalled", "passRemoved", "passScanned", "passCreated" ] }, "minItems": 1 }, "entityId": { "type": "string", "description": "If your organisation has multiple entities, you can scope the webhook subscription to a specific entity. If not provided, the webhook subscription will be scoped to the organisation.", "example": "7e16b5e1" } }, "required": [ "url", "subscribedEvents" ] } }, "required": [ "webhookSubscription" ] }, "webhookSubscriptionResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the webhook subscription", "example": "01983282-53cf-7e16-b5e1-dd0de4ce02fa" }, "type": { "type": "string", "enum": [ "webhookSubscription" ], "description": "Type of the resource" }, "attributes": { "type": "object", "properties": { "url": { "type": "string", "description": "HTTPS URL that will receive webhook events", "format": "uri", "pattern": "^https://.+", "example": "https://example.com/webhook" }, "secretKey": { "type": "string", "description": "Secret key used to sign webhook payloads", "example": "a2e2c04657b924390d2a2623439c65734d07e0f8" }, "enabled": { "type": "boolean", "description": "Whether the webhook subscription is active" }, "scopeType": { "type": "string", "description": "Scope type for the webhook subscription", "enum": [ "organisation", "entity" ] }, "scopeName": { "type": "string", "description": "Name of the scope", "example": "Test Organisation" }, "subscribedEvents": { "type": "array", "description": "List of events subscribed to", "items": { "type": "string", "enum": [ "passInstalled", "passRemoved", "passScanned", "passCreated" ] } } } } } } } } }