# Cancel Batch Source: https://docs.passentry.com/api-reference/v1/batches/cancel-batch patch /api/v1/batches/{id}/cancel Cancel a Batch. Can only be used on scheduled batches. # Create Passes Batch Source: https://docs.passentry.com/api-reference/v1/batches/create-passes-batch post /api/v1/passes/batch Create passes in bulk via a CSV file. For more details, see the [Batch Pass Creation](/documentation/bulk-operations/batch-pass-creation/guide) documentation. # Create Wallet Messaging Batch Source: https://docs.passentry.com/api-reference/v1/batches/create-wallet-messaging-batch post /api/v1/entities/{id}/messaging/wallet Create a new wallet messaging batch using segments, recipients, or a CSV file (via multipart/form-data). The 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. For more details, see the [Wallet Messaging](/documentation/bulk-operations/batch-notifications/guide) documentation. # Batches Source: https://docs.passentry.com/api-reference/v1/batches/guide ## Overview In most integrations, you will often be interacting with a large number of passes or users at once. Although this can easily be done by making individual API calls, this can be inefficient and slow, especially if you are making a large number of requests. To address this, we support **Batches** for bulk operations. Although batch operations can be an efficient way to increase max request throughput, since they are processed asynchronously by PassEntry and not affected by your organisation's rate limits, at very low numbers of requests they can sometimes be slower than individual requests. ## Batch Types We support the following batch types: * **[Wallet Messaging Batch](/documentation/bulk-operations/batch-notifications/guide)** - Used to send push notifications to users, must be scheduled * **[Pass Creation Batch](/documentation/bulk-operations/batch-pass-creation/guide)** - Used to create passes in bulk **(Coming Soon to API, currently only available in Dashboard)** ## Batches API You can use the Batches API (`/api/v1/batches`) endpoints for general interactions with multiple batch types. These include: * [Show batch](/api-reference/v1/batches/show-batch) * [List batches](/api-reference/v1/batches/list-batches) * [Cancel batch](/api-reference/v1/batches/cancel-batch) (Used for scheduled batches) * [Send batch now](/api-reference/v1/batches/send-now-batch) (Wallet messaging batches only) # List Batches Source: https://docs.passentry.com/api-reference/v1/batches/list-batches get /api/v1/batches Retrieve a list of Batches # Send Batch Now Source: https://docs.passentry.com/api-reference/v1/batches/send-now-batch post /api/v1/batches/{id}/send-now Override a scheduled wallet messaging batch's `scheduledAt` time and start sending immediately. Only valid for batches currently in `scheduled` status. ## Best practices After creating a wallet messaging batch, it sits in `validating` while we verify the recipients and payload. Poll [`GET /api/v1/batches/{id}`](/api-reference/v1/batches/show-batch) until the status leaves `validating` before calling `send-now`. # Show Batch Source: https://docs.passentry.com/api-reference/v1/batches/show-batch get /api/v1/batches/{id} Retrieve a Batch by ID # Update Passes Batch Source: https://docs.passentry.com/api-reference/v1/batches/update-passes-batch post /api/v1/passes/batch/update Update passes in bulk via a CSV file. # Entities Source: https://docs.passentry.com/api-reference/v1/entities/guide **What are entities?** Entities serve as subdivisions within an organization, designed to help larger clients such as aggregators or resellers manage their operations more effectively. Each entity can represent a different department or business unit within the larger organization, enabling detailed segmentation and breakdowns. A 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. All organisations have one entity by default. For most organisations, this is sufficient. If you would like to create additional entities, please contact PassEntry. **Example** An organisation, "PassEntry Enterprise" has 2 business units, "PassEntry Supermarket" and "PassEntry Coffee". In order to keep their information and data separate, they have 2 *Entities*, each with their own *Pass Templates*, *Passes*...etc # List Entities Source: https://docs.passentry.com/api-reference/v1/entities/list-entities GET /api/v1/entities Lists all entities # Show Entity Source: https://docs.passentry.com/api-reference/v1/entities/show-entity get /api/v1/entities/{id} Retrieve an entity by ID # Create Image Asset Source: https://docs.passentry.com/api-reference/v1/image-assets/create-image-asset post /api/v1/image-assets Create a new image asset # Image Assets Source: https://docs.passentry.com/api-reference/v1/image-assets/guide Upload images once and reference them by ID across multiple passes Image Assets allow you to upload images once and reference them by ID when creating or updating passes. Instead of providing a raw image URL every time, you upload the image to PassEntry and use the returned `imageAssetId` in your `templateOverride`. Images can be provided as a **direct URL** or **base64 encoded data**. Supported formats: **PNG, JPG, WebP**. ### Supported image types | Type | Description | | - | - | | `banner` | Banner image displayed at the top of the pass | | `logo` | Logo image on the pass | | `thumbnail` | Thumbnail image (generic pass type only, Apple only) | ### Watermark If your organisation has watermarking enabled, a `watermark` object is required when uploading `banner` images. The watermark is applied automatically during processing. ```json theme={null} { "imageAsset": { "image": "https://example.com/silver_tier_banner.png", "imageType": "banner", "watermark": { "color": "light", "position": "bottomRight" } } } ``` | Field | Values | | - | - | | `color` | `dark`, `light` | | `position` | `bottomLeft`, `bottomRight`, `topLeft`, `topRight` | ### Workflow 1. **Upload an image** using [Create Image Asset](/api-reference/v1/image-assets/create-image-asset) with the image data and type 2. **Get the `id`** from the response 3. **Reference the `id`** in your pass `templateOverride` when creating or updating a pass ### Using Image Assets in templateOverride Template overrides must be enabled for your organisation. Contact support to request access. Requests made without this feature enabled will return a **403 Forbidden** error. When creating or updating a pass, reference an image asset by its ID in the `templateOverride` object: ```json theme={null} { "pass": { "templateOverride": { "bannerImage": { "imageAssetId": "19cb334f9696e64e10e7759f0" }, "logoImage": { "imageAssetId": "29dc445g0797f75f21f8860g1" } } } } ``` ### Using Image Assets in Batch Operations You can reference image assets in CSV batch operations using the following columns: | CSV Column | Description | | - | - | | `override_banner_image_asset_id` | UUID of a processed banner image asset | | `override_logo_image_asset_id` | UUID of a processed logo image asset | | `override_thumbnail_image_asset_id` | UUID of a processed thumbnail image asset (generic passes only) | For batch updates, set a column to the literal string `null` to remove an image asset override. See the [Batch Pass Creation](/documentation/bulk-operations/batch-pass-creation/guide) and [Batch Pass Update](/documentation/bulk-operations/batch-pass-update/guide) guides for full details. ### Deprecated format The previous flat URL format for image overrides is deprecated but still supported. Image URLs must use **HTTPS** or be a **base64-encoded data URI** (`data:image/...`). Plain HTTP URLs are rejected. ```json theme={null} { "pass": { "templateOverride": { "bannerImage": "https://example.com/banner.png" } } } ``` We recommend migrating to the `imageAssetId` object format for better image management and reduced duplication. # List Image Assets Source: https://docs.passentry.com/api-reference/v1/image-assets/list-image-assets get /api/v1/image-assets List all image assets # Show Image Asset Source: https://docs.passentry.com/api-reference/v1/image-assets/show-image-asset get /api/v1/image-assets/{id} Show an image asset by ID # Authentication Source: https://docs.passentry.com/api-reference/v1/introduction/authentication The 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 Your 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. Authentication to the API is performed with Bearer authentication. These tokens must be attached to the Authorization header of the request. Example: ``` "Authorization": "Bearer {API KEY}" ``` You 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. # Deprecation Source: https://docs.passentry.com/api-reference/v1/introduction/deprecation PassEntry commits to maintaining backwards compatibility while evolving our API. Deprecated endpoints and parameters remain functional after deprecation, with continued bug fixes and no breaking changes. ## Notifications We notify users of deprecations through: * API documentation updates * Email notifications (via newsletter or other communication channels) * Changelog entries ## Identification Deprecated features are marked with a "Deprecated" label in documentation with alternative suggestions. ## Migration Whenever possible, please migrate to the non-deprecated endpoints and parameters. Deprecated endpoints and parameters will be removed in a future version of the API. We recommend migrating to the replacement features as soon as possible. For migration assistance, contact our support team at [support@passentry.com](mailto:support@passentry.com). # Errors Source: https://docs.passentry.com/api-reference/v1/introduction/errors PassEntry 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). Some `4xx` errors include text that briefly explains the error reported. # Rate Limiting Source: https://docs.passentry.com/api-reference/v1/introduction/rate-limiting The PassEntry API implements rate limiting to ensure service stability and fair usage across all users. Rate limits are applied separately to each combination of endpoint and HTTP method. For example, you can make up to 10 GET requests per second to `/passes` and simultaneously 10 POST requests per second to the same endpoint. ## Rate Limit Implementation We use a sliding window algorithm to track and enforce rate limits. While the rate limit is 10 requests per second, we recommend implementing a buffer in your applications to account for network latency and potential timing variations. Best practice is to limit your requests to 9 requests per second, leaving some buffer for retries and network delays. This helps prevent edge cases where requests might be counted in different time windows. ## Response Headers The API includes rate limit information in the response headers: | Header | Description | | - | - | | `x-rate-limit-limit` | Maximum number of requests allowed per second (10) | | `x-rate-limit-remaining` | Number of requests remaining in the current window | | `x-rate-limit-reset` | Unix timestamp when the rate limit window resets | | `x-rate-limit-url` | The endpoint path this rate limit applies to | ## Rate Limit Exceeded When you exceed the rate limit, the API will respond with a `429 Too Many Requests` status code and include an additional header: | Header | Description | | - | - | | `x-rate-limit-retry-after` | Time in seconds (decimal) to wait before retrying | ### Example Rate Limited Response ```json theme={null} { "errors": [ "Too Many Requests" ] } ``` ## Handling Rate Limits ### Best Practices * Implement exponential backoff with jitter for retries * Cache responses when possible to reduce API calls * Use bulk operations where available instead of multiple single requests * Implement retries if the request fails due to rate limiting # Responses Source: https://docs.passentry.com/api-reference/v1/introduction/responses PassEntry 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. # Welcome to PassEntry API Source: https://docs.passentry.com/api-reference/v1/introduction/welcome PassEntry API is an OpenAPI 3.1.0 compliant REST API with predictable URLs, JSON request bodies, standard HTTP response codes, authentication, and verbs. This documentation describes the functionality of our system available for integration with your business. **Base URL** ```Base URL theme={null} https://api.passentry.com ``` # Loyalty Source: https://docs.passentry.com/api-reference/v1/loyalty/guide PassEntry provides a number of RESTful endpoints for interacting and manipulating passes created under the Loyalty vertical.\ This includes but is not limited to: Loyalty Cards, Gift Cards, Coupons, Memberships… ### Terminology **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. **POS System:** handles in store sales transactions, inventory management, and reporting **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*. **Payment Terminal:** where payment is made, can also be used to read the loyalty pass and thus identify the customer ### Enabling loyalty balance To allow interacting with your passes using the Loyalty API, the first step is to ensure that the parent template has loyalty balance enabled. Once this is done, you must choose how you want the balance to be represented on the pass, set at the pass template level. We currently offer support for **integer** and **decimal** types. * **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. * **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) *** ### What does a loyalty integration with PassEntry look like? **Example**: PassEntry Coffee has a loyalty program. Every £10 spent, a customer receives 1 `Point`\ When a customer has received 5 points they are able to get £5 off on their order total **Distributing a loyalty pass** 1. A loyalty pass is created and distributed to a customer with an `ext_id` equivalent to customer in the loyalty program 2. 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. 3. 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 **Accumulating balance** 4. 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. 5. In this example, the customer has spent £20, so 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. **Receiving a reward** 5. The POS system takes £10 payment and customer balance is increased by 1 point. 6. 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!` 7. 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 **Redeeming a reward** 8. The POS system is ready to receive payment of £8 9. 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 10. The loyalty program detects that the customer has 5 points and is thus entitled to a £5 off discount 11. 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) 12. The transaction amount on the payment terminal is updated to £3 13. The customer makes payment 14. The reward is removed from the loyalty pass alongside a `You've used your £5 off discount!` push notification **Resetting the balance (Optional)** 17. At this stage, the loyalty balance can be reset to 0 points # Show loyalty balance Source: https://docs.passentry.com/api-reference/v1/loyalty/show-loyalty-balance get /api/v1/loyalty/{id} # Update loyalty balance Source: https://docs.passentry.com/api-reference/v1/loyalty/update-loyalty-balance patch /api/v1/loyalty/{id} # Create Pass Template Source: https://docs.passentry.com/api-reference/v1/pass-templates/create-pass-template post /api/v1/pass-templates Pass Templates are created asynchronously and the response will return a 202 status code. Use the URL returned in the response to check the status of the pass template. # Show Pass Template (Deprecated) Source: https://docs.passentry.com/api-reference/v1/pass-templates/deprecated-show-pass-template get /api/v1/pass_templates/{pass_template_uuid} Retrieve a Pass Template by ID (This endpoint is deprecated) # Pass templates guide: create, update, and manage designs Source: https://docs.passentry.com/api-reference/v1/pass-templates/guide Learn how to create, update, and manage PassEntry pass templates from the Dashboard or API, including fields, colours, images, and value keys. Before you can create passes using the PassEntry API, you need a pass template. A template serves as a blueprint for your passes and includes various components such as fields, colours, images and value keys. ## Create a pass template You can create a pass template directly from the Dashboard, on the Pass Templates page. Click **Create Pass Template** in the top right corner (direct link: [https://app.passentry.com/pass-templates/create](https://app.passentry.com/pass-templates/create)). Once created, the pass template appears in the Pass Templates page. ### See the pass templates list You can view all pass templates on the Pass Templates page of your Dashboard (direct link: [https://app.passentry.com/pass-templates](https://app.passentry.com/pass-templates)). ## Update a pass template You can update pass templates via the Dashboard or via the [Update Pass Template API](/api-reference/v1/pass-templates/update-pass-template). PassEntry applies template-level changes such as colours, images and field labels to all existing passes when the template updates. ### Field default values do not propagate by default When you change a field's `defaultValue` on a template, the new value is **only applied to newly created passes**. Existing passes keep whatever value they already have on that field. To push the new default value out to all existing passes that use the template, set `overrideFieldValue: true` on the field in your update request. Fields are keyed by section (`header`, `central`, `details`, `back`) and then by position (`one` to `six`): ```json theme={null} { "passTemplate": { "fields": { "header": { "one": { "id": "tier", "defaultValue": "Gold", "overrideFieldValue": true } } } } } ``` `overrideFieldValue` is accepted on [Update Pass Template](/api-reference/v1/pass-templates/update-pass-template) only. Sending it on [Create Pass Template](/api-reference/v1/pass-templates/create-pass-template) returns a validation error. #### When the override applies An existing pass is updated only when all of the following are true: * You send a new `defaultValue` for the field in the same request. `overrideFieldValue: true` on its own does nothing. * The new `defaultValue` differs from the one currently stored on the template. * The pass already carries that field `id`. Passes that do not have the field yet pick up the new default regardless of `overrideFieldValue`. PassEntry updates only live passes and leaves nullified and expired passes untouched. `overrideFieldValue: true` replaces the value on every live pass, including values you set per pass through the Update Pass API or a batch pass update. Those per-pass values are lost. Use `overrideFieldValue` only when updating the default value of a field. To change individual pass values without touching the template default, use the [Update Pass API](/api-reference/v1/passes/update-pass) or the [Batch Pass Update guide](/documentation/bulk-operations/batch-pass-update/guide) instead. The same flag controls localised default values. See [Localisation](/documentation/passes/localisation/guide) for details. ### NFC and barcode changes do not propagate by default Changes to the `nfc` or `barcode` objects on a template follow the same rule as field default values. By default, the new configuration **only applies to newly created passes**. Existing passes keep their current NFC or barcode settings. To push a new NFC configuration out to all existing passes, set `overrideNfc: true` inside the `nfc` object on your update request: ```json theme={null} { "passTemplate": { "nfc": { "enabled": true, "source": "uuid", "overrideNfc": true } } } ``` To push a new barcode configuration out to all existing passes, set `overrideBarcode: true` inside the `barcode` object: ```json theme={null} { "passTemplate": { "barcode": { "enabled": true, "type": "qr", "source": "uuid", "displayText": false, "overrideBarcode": true } } } ``` [Update Pass Template](/api-reference/v1/pass-templates/update-pass-template) accepts both flags. [Create Pass Template](/api-reference/v1/pass-templates/create-pass-template) ignores these flags since there are no existing passes to override. #### Per-pass resolution When an override runs, PassEntry resolves the value for each existing pass: * `source: "uuid"` uses each pass's UUID as the NFC message or barcode value. * `source: "extId"` uses each pass's `extId`. Passes without an `extId` are skipped and keep their existing settings. * `source: "custom"` uses the `customValue` (for NFC) or `value` (for barcode) from your update request. For NFC, passes belonging to an entity that does not have NFC access are also skipped. `overrideNfc: true` and `overrideBarcode: true` replace the NFC or barcode configuration on every live pass on the template. This includes values you set per pass through the Update Pass API. Those per-pass values are lost. Use these flags only when you want the new template-level NFC or barcode configuration to apply to existing passes. To change NFC or barcode values on individual passes without touching the template, use the [Update Pass API](/api-reference/v1/passes/update-pass) instead. # List Pass Templates Source: https://docs.passentry.com/api-reference/v1/pass-templates/list-pass-templates get /api/v1/pass-templates List Pass Templates # Show Pass Template Source: https://docs.passentry.com/api-reference/v1/pass-templates/show-pass-template get /api/v1/pass-templates/{id} Show a Pass Template # Update Pass Template Source: https://docs.passentry.com/api-reference/v1/pass-templates/update-pass-template patch /api/v1/pass-templates/{id} Supports partial updates.
Response may either be a 200 or 202 status code. Use the URL returned in the response to check the status of the pass template. # Create pass Source: https://docs.passentry.com/api-reference/v1/passes/create-pass post /api/v1/passes # List passes Source: https://docs.passentry.com/api-reference/v1/passes/list-passes get /api/v1/passes # Nullify Pass Source: https://docs.passentry.com/api-reference/v1/passes/nullify-pass post /api/v1/passes/{id}/nullify Irreversibly nullifies a pass, removing all dynamic data (fields, images, barcode, NFC, localisation) while preserving the tombstone record for billing and auditability. The 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. This endpoint is idempotent — calling it on an already-nullified pass returns 200 with no further changes. # Send Notification Source: https://docs.passentry.com/api-reference/v1/passes/send-notification post /api/v1/passes/{id}/notification # Show Pass Source: https://docs.passentry.com/api-reference/v1/passes/show-pass get /api/v1/passes/{id} # Update pass Source: https://docs.passentry.com/api-reference/v1/passes/update-pass patch /api/v1/passes/{id} # Create reader Source: https://docs.passentry.com/api-reference/v1/readers/create-reader post /api/v1/entities/{entity_id}/readers # Get reader Source: https://docs.passentry.com/api-reference/v1/readers/get-reader get /api/v1/readers/{id} # Get reader configuration Source: https://docs.passentry.com/api-reference/v1/readers/get-reader-configuration get /api/v1/entities/{entity_id}/readerConfiguration # Readers Source: https://docs.passentry.com/api-reference/v1/readers/guide Readers can be used for a variety of use cases, to validate access, redeem loyalty, claim discounts, identify the user and much more. **NFC** PassEntry'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. This NFC value is encrypted, and can only be generated by PassEntry. In order for the NFC value to be read, an NFC reader must be configured. To 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. Our 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. Below, we provide an overview of each reader type, the configuration process, and additional setup information. ## VTAP Readers **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. #### Configuration: Setting up a VTAP Reader consists of two parts: 1. **Creating a Reader on PassEntry**: You need to provide the following information: * **Name**: A friendly display name for the reader * **UUID**: A unique identifier for the reader, this must be the "Reader Serial" provided by Dot Origin * **Type**: Should be set to `VtapReader` 2. **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. ## PassEntry Reader App **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). # Reader heartbeat Source: https://docs.passentry.com/api-reference/v1/readers/reader-heartbeat get /api/v1/readers/{id}/heartbeat Keep a reader session alive and mark the reader as online in the Dashboard. Call it every 5 minutes with the current session token. Each successful heartbeat returns a new token and refresh token and invalidates the previous ones, so switch to the returned token immediately. # Reader login Source: https://docs.passentry.com/api-reference/v1/readers/reader-login post /api/v1/readers/login Sign in as a PassEntry Reader using its Reader ID and password, exactly as the PassEntry Reader app does. Returns a session token, a refresh token and the reader's NFC configuration. A reader holds one session at a time: logging in again invalidates the previous session's tokens. Keep the session alive with Reader heartbeat every 5 minutes. # Reader logout Source: https://docs.passentry.com/api-reference/v1/readers/reader-logout delete /api/v1/readers/{id}/logout End the reader session. The session token and refresh token are invalidated and the reader is marked as logged out in the Dashboard. # Refresh reader token Source: https://docs.passentry.com/api-reference/v1/readers/refresh-reader-token post /api/v1/readers/refresh_token Exchange a refresh token for a new session token and refresh token without the reader password. Use it when an API call returns 401 because the session token expired. The previous tokens are invalidated. # Update reader Source: https://docs.passentry.com/api-reference/v1/readers/update-reader patch /api/v1/readers/{id} # Create scan Source: https://docs.passentry.com/api-reference/v1/scans/create-scan post /api/v1/scans # Get scan Source: https://docs.passentry.com/api-reference/v1/scans/get-scan get /api/v1/scans/{id} # List scans Source: https://docs.passentry.com/api-reference/v1/scans/get-scans get /api/v1/scans # Scans Source: https://docs.passentry.com/api-reference/v1/scans/guide Overview of the Scans API and the two validation methods available. ## **Overview** A scan represents the action of reading a pass (either via NFC or barcode) using a **PassEntry-compatible reader**. The **Scans API** is essential for businesses that need to validate and process passes at physical locations. **Common Use Cases** * Event access control * Membership verification * Ticket validation * Loyalty program check-ins * etc. ## **Validation Methods** The **Scans API** enables validation of passes through two different methods: ### **Internal PassEntry Validation (Default)** * A simple and convenient out-of-the-box solution * Validates passes against **PassEntry's database** * Ensures the pass is **valid and active** * If a validity period is configured, ensures the pass **hasn't been scanned within that timeframe** * Returns **immediate validation results** and **reader instructions** * Scan value (NFC/barcode) must be the **pass UUID** or **external ID** * `/scans` endpoint is used for this flow *** ### **Third-Party Validation** * Your system handles **all validation logic** * Highly flexible – define your own validation rules and business logic * Scan value can contain **any data format** you need: * Multiple values (e.g., `"customerID-promoCode"`) * Custom formats * Full control over **reader behavior** through reader instructions: * Currently supports **display messages** * Future expansion planned for **LED colors, sounds, icons**, and more controls depending on the reader type * Results are **logged back to PassEntry** for analytics and reporting (only available for PassEntry Reader) * `/scans/log` endpoint is used for this flow * Available with **PassEntry Reader** and **VTAP reader** *** Both methods support **NFC and barcode scanning**, and provide **detailed scan information**, including timestamps, pass details, and validation status. The **validation type is configured in your [reader settings](https://app.passentry.com/readers/reader-configuration)** on the **PassEntry Dashboard**. # Log scan Source: https://docs.passentry.com/api-reference/v1/scans/log-scan post /api/v1/scans/log # Create Webhook Subscription Source: https://docs.passentry.com/api-reference/v1/webhook-subscriptions/create-webhook-subscription post /api/v1/webhook-subscriptions Create a new webhook subscription to notify your specified target URL about events happening within PassEntry. # Delete Webhook Subscription Source: https://docs.passentry.com/api-reference/v1/webhook-subscriptions/delete-webhook-subscription delete /api/v1/webhook-subscriptions/{id} Delete an existing webhook subscription. # Webhook Subscriptions Source: https://docs.passentry.com/api-reference/v1/webhook-subscriptions/guide ## Webhook Subscriptions Webhook subscriptions allow you to receive real-time notifications about events in your PassEntry account. When an event occurs (like a pass being installed or scanned), PassEntry will send an HTTP POST request to your specified endpoint with details about the event. This section covers webhook subscriptions and management. For webhook events and security best practices, see the [Webhooks](/api-reference/v1/webhooks/guide) section. ### Setting Up Webhooks To start receiving webhooks, create a subscription either via API or [PassEntry Dashboard](https://app.passentry.com/developer-tools). 1. Create a webhook subscription by providing: * An HTTPS endpoint URL that will receive the webhook events * A list of events you want to subscribe to * Optional entity scope if you want to receive events only for a specific entity 2. Store the secret key returned in the response securely. This key is used to verify webhook signatures (see [Security Measures](/api-reference/v1/webhooks/guide#security-measures)). 3. Configure your endpoint to: * Accept POST requests * Verify webhook signatures * Return a 2xx status code to acknowledge receipt ### Webhook Management #### Scoping * Your entire organisation (default) * A specific entity (if you have multiple entities) **Important Limitations:** * Cannot create multiple webhook subscriptions with the same target URL within the same scope * Cannot change the scope after subscription creation (create a new one and delete the old one) * Default limits: 10 organisation-level and 10 per entity subscriptions #### Status * **Enabled**: Actively receiving events * **Disabled**: Temporarily paused ### Debugging and Security * Use the "Test webhook" functionality via [API](/api-reference/v1/webhook-subscriptions/test-webhook-subscription) or [Dashboard](https://app.passentry.com/developer-tools) to debug your subscriptions * If you believe your secret key was compromised, rotate it via [Dashboard](https://app.passentry.com/developer-tools) or [API](/api-reference/v1/webhook-subscriptions/rotate-secret-key) * Maintain separate webhook subscriptions for each environment (development, staging, production) to isolate testing and ensure proper event handling across your deployment pipeline For implementation details and best practices, see our [Webhooks Guide](/api-reference/v1/webhooks/guide). # List Webhook Subscriptions Source: https://docs.passentry.com/api-reference/v1/webhook-subscriptions/list-webhook-subscriptions get /api/v1/webhook-subscriptions Get a list of all webhook subscriptions with pagination and filtering options # Rotate Secret Key Source: https://docs.passentry.com/api-reference/v1/webhook-subscriptions/rotate-secret-key patch /api/v1/webhook-subscriptions/{id}/rotate-secret Generate a new secret key for webhook signature verification. The old key becomes invalid immediately. # Show Webhook Subscription Source: https://docs.passentry.com/api-reference/v1/webhook-subscriptions/show-webhook-subscription get /api/v1/webhook-subscriptions/{id} Get details of a specific webhook subscription based on ID. # Test Webhook Subscription Source: https://docs.passentry.com/api-reference/v1/webhook-subscriptions/test-webhook-subscription post /api/v1/webhook-subscriptions/{id}/test Send a test webhook to verify endpoint configuration and webhook handling. # Update Webhook Subscription Source: https://docs.passentry.com/api-reference/v1/webhook-subscriptions/update-webhook-subscription patch /api/v1/webhook-subscriptions/{id} Update an existing webhook subscription configuration. Note: The scope (organisation/entity) of a webhook subscription cannot be changed after creation. To change the scope, create a new webhook subscription and delete the old one. # Receiving webhooks from PassEntry Source: https://docs.passentry.com/api-reference/v1/webhooks/guide Set up an HTTPS endpoint to receive PassEntry webhook events, verify the X-Webhook-Signature HMAC-SHA256 header, and handle retries. # Incoming Webhooks with PassEntry ## Overview When building integrations with PassEntry, you might want your application to receive events as they occur, so that your backend systems can execute actions accordingly. To enable webhooks, you must first register a valid HTTPS URL, and subscribe to the events you want to be notified by. To do this, please visit the Webhook section on the PassEntry dashboard. ### Setting Up Your Webhook Endpoint * **HTTPS Requirement**: Ensure your endpoint is a valid HTTPS URL and the path can receive POST requests. ### Receiving Webhook Events * **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. ### Request headers Each incoming webhook `POST` request from PassEntry includes the following headers: | Header | Value | | - | - | | `Content-Type` | `application/json` | | `X-Webhook-Signature` | HMAC-SHA256 hex digest of the raw request body, signed with your webhook secret key. See [Security Measures](#security-measures). | Header names only use characters from `[-A-Za-z0-9]`. PassEntry does not send additional custom headers on incoming webhooks. ## Security Measures We implement a number of security measures to guarantee any interactions between PassEntry and your system are verified and authentic. * **Secret Key**: When configuring your webhook endpoint, you will be provided a secret key, which PassEntry will use to sign any outbound webhooks. You must store this securely. If you believe your secret key has been compromised, you have the option to **rotate** your secret key. This will immediately invalidate the previous secret key and sign all subsequent webhooks with the new key * **Timestamp**: Each webhook payload includes a timestamp, serving as a safeguard against replay attacks. * **HMAC-SHA256 Signature**: Every outgoing webhook includes an HMAC signature. The signature is included in the `X-Webhook-Signature` header and is generated using the webhook payload and the shared secret key. To verify that the webhook is authentic, you can encrypt the webhook payload using the SHA-256 encryption algorithm and your secret key. If your generated signature matches the signature included in the `X-Webhook-Signature` header, you can confirm that the webhook is authentic. ## Reliability and Retries * **Asynchronous Delivery**: Webhooks include a timestamp to reflect the actual event time. * **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. ## Responding to Webhooks * **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. * **Response Body**: While optional, you may return a response body. ### Example Success Response ```http theme={null} HTTP Status: 200 Content-Type: application/json { "status": "ok" } ``` # Pass Created Source: https://docs.passentry.com/api-reference/v1/webhooks/pass-created webhook passCreated Webhook triggered when a pass is created # Pass Installed Source: https://docs.passentry.com/api-reference/v1/webhooks/pass-installed webhook passInstalled Webhook triggered when a pass is added to the wallet by user # Pass Removed Source: https://docs.passentry.com/api-reference/v1/webhooks/pass-removed webhook passRemoved Webhook triggered when a pass is removed from the wallet by user # Pass Scanned Source: https://docs.passentry.com/api-reference/v1/webhooks/pass-scanned webhook passScanned Webhook triggered when an NFC or barcode pass is scanned by a reader # Pass Tapped (Deprecated) Source: https://docs.passentry.com/api-reference/v1/webhooks/pass-tapped webhook passTapped Webhook triggered when an NFC pass is tapped on a reader (This webhook is deprecated, please use the passScanned webhook instead) # Product updates Source: https://docs.passentry.com/changelog/updates Follow release notes for the PassEntry Dashboard, API, and SDKs, including SSO improvements, new endpoints, and pass template features. ## Delete pass templates from the Dashboard You can now delete pass templates directly from the Dashboard's templates list. Templates get deleted and all associated passes will be **nullified**. This is an irreversible action. Only published templates count against your template limit Open the "…" menu on any template card and pick **Delete**. Learn more: [Pass nullification](/documentation/passes/nullification/guide) ## Apple Generic Poster Design Apple's poster face is no longer limited to event tickets. Set `appleEnhancedDesign.type` to `generic` on an event ticket, generic or loyalty template to give its passes a full-bleed poster on iOS 27. Your fields sit over the artwork, and anything that does not fit moves into the information panel underneath. * Unlike the `eventTicket` design, the `generic` design needs no NFC or pass binding entitlement. Artwork is still required. * Each pass carries its standard layout alongside the poster, so devices below iOS 27 render the pass as they always have. * Add up to two `featuredActions` buttons under the poster. Each slot takes an action `type` and an `https://` URL, and the two slots must use different types. * Passes inherit the template's actions when they are created. Override a slot per-pass under `enhancedData.generic.featuredActions`, or send the slot as `null` to remove it. Apple Wallet poster pass showing artwork, fields over the chin and two featured action buttons Check out the guide here: [Apple Poster Designs](/documentation/passes/apple-poster-designs/guide) This feature is in **closed beta**.
Please contact PassEntry for access. ## Numbers in dynamic pass fields Dynamic pass fields defined on your template now accept **integers and floats** as values, in addition to strings and `null`. This applies both to the top-level `value` and to per-locale `localisation..value` entries on the [Create Pass](/api-reference/v1/passes/create-pass) and [Update Pass](/api-reference/v1/passes/update-pass) endpoints. Send a numeric quantity (points, tier number, price) without pre-formatting it as a string. Validation stays strict, so PassEntry still rejects unsupported types. ```json theme={null} { "pass": { "points": { "value": 1250, "localisation": { "fr": { "value": 1250 } } } } } ``` Learn more: [Pass value localisation](/documentation/passes/localisation/guide#pass-value-localisation) ## Combine pass template and group tag filters in wallet messaging Wallet messaging batches can now target passes by **pass template and group tags together**. Previously you could filter by one or the other; combining them narrows the audience to passes on the chosen template that also carry at least one of the selected tags. * In the Dashboard, tick both **By pass template** and **By group tag** when filtering recipients - the counter shows the combined audience before you send * Via the API, include a `passTemplateId` segment and a `groupTags` segment in the same `segments` array ```json theme={null} "segments": [ { "passTemplateId": "bf915c229114", "groupTags": ["summerPromotion", "easterOffer"] } ] ``` Learn more: [Create Wallet Messaging Batch](/api-reference/v1/batches/create-wallet-messaging-batch) ## Okta single sign-on for Dashboard Teams can now sign in to the PassEntry Dashboard with Okta. On the login page, choose **Sign in with Okta** and enter your work email — we'll route you to your organisation's Okta tenant automatically based on your email domain. * Email-based provider discovery — enter your work email and we redirect to the right Okta tenant * Per-organisation Okta configuration, scoped to an allowed set of email domains * Works alongside existing Google and Microsoft SSO options Okta SSO is available on request. Contact [support@passentry.com](mailto:support@passentry.com) to enable it for your organisation and configure your Okta tenant. ## Draft Pass Templates You can now save pass templates as **drafts** while you iterate on them, before making them live. Drafts let you experiment with different template designs — new layouts, fields or colours — without affecting your published catalogue or existing passes. * Create and edit drafts in the Dashboard while a template is still being designed * Publish a draft when it's ready to issue passes from; delete the ones you no longer need * Drafts are capped at 20 per organisation, but **don't count against your pass template quota** — feel free to keep a working set as you experiment * Every pass template response now includes a `status` field (`"draft"` or `"published"`) * `GET /api/v1/pass-templates` accepts an optional `?status=` filter (comma-separated list of `draft` or `published`) Learn more: [Draft and published templates](/documentation/pass-template-types-explained#draft-and-published-templates) ## Apple Poster Event Ticket Support We've added support for Apple's poster event ticket experience (iOS 18+), allowing you to create full-bleed event tickets with rich event information. **Pass Templates:** * Enable poster event tickets via the `appleEnhancedDesign` field * Configure artwork, secondary logo, and venue map images at the template level **Passes:** * Add rich event data including event details, venue information, seating, and event guide URLs via the `enhancedData` field * Override template images per-pass using the new `artworkImage`, `secondaryLogoImage`, and `venueMapImage` fields in `templateOverride` This feature requires NFC entitlement and is in **closed beta**.
Please contact PassEntry for access. ## Pass Nullification You can now permanently nullify a pass via the API, irreversibly removing all dynamic data (fields, barcode, NFC, images) while preserving a tombstone record for billing and compliance. Nullified passes appear as "Deactivated" in the wallet, and their External ID is freed for reuse. Check out the guide here: [Pass Nullification](/documentation/passes/nullification/guide), [Nullify Pass endpoint](/api-reference/v1/passes/nullify-pass) ## Pass Binding in open beta Pass binding restricts a digital pass to a specific wallet account, preventing sharing or unauthorized use. **Google Wallet** — The pass is restricted to a specific Google account using a SHA-256 email hash. Only the matching account can save the pass. **Apple Wallet** — The pass is bound to the user's device using FIDO hardware key authentication, requiring Face ID or Touch ID. Apple binding is mainly beneficial for NFC passes, as it disables the NFC on the pass. API docs here: [Create Pass](/api-reference/v1/passes/create-pass) Check out the guide here: [Pass Binding](/documentation/passes/pass-binding/guide) This feature is in **open beta** and can be requested via a custom plan or reach out directly to [support@passentry.com](mailto:support@passentry.com) - let us know if you encounter any issues or have feedback. ## Geofencing Improvements on Dashboard We've enhanced Geofencing in the new pass template builder with a unified map view and overlap warnings to prevent duplicate notifications. We've also clarified Apple vs Google behaviour, including device-specific settings and limitations. ## Image Assets API Upload images once and reference them by ID across multiple passes using `templateOverride`. This reduces duplication and simplifies pass image management. * Create, list, and view image assets via the API * Supported image types: banner, logo, and thumbnail * Supports direct URL and base64 encoded uploads (PNG, JPG, WebP) * Batch operations now support image asset override columns Check out the guide here: [Image Assets](/api-reference/v1/image-assets/guide) ## New pass template builder We're rolling out a new pass template builder which includes a range of performance, design, and layout improvements. Major changes include: * Creating transit passes directly from the dashboard * Adding localisation to pass templates via the dashboard * Uploading more device-specific images for Apple and Google passes New pass template builder ## Support for external Apple Pass Type Identifier Certificates We've added support for external Apple Pass Type Identifier Certificates. This allows you to use your own Pass Type Identifier Certificates, rather using our internal certificates. Check out the guide here: [Adding an Apple Pass Certificate](/documentation/adding-an-apple-pass-certificate) ## Batch Pass Update via CSV in closed beta We've added support for batch pass update via CSV. Batch updates are scheduled to run at a specified time, and can be cancelled if needed. Check out the guide here: [Batch Pass Update](/documentation/bulk-operations/batch-pass-update/guide) Batch Update Index This feature is in **closed beta**.
Please contact PassEntry for access. ## Multi-Factor Authentication (MFA) for Dashboard We've added multi-factor authentication (MFA) for PassEntry dashboard accounts. MFA dashboard login MFA dashboard login MFA dashboard login ## Resetting overridden pass template fields After using the `templateOverride` option on pass to override template design, you can now revert to the original template design by passing `null` to any previously overridden value. Check out the guide here: [Pass Template Override](/api-reference/v1/passes/update-pass#body-pass-template-override) ## Geofencing for Android Geofencing, previously available only on Apple Wallet, is now supported for Google Wallet passes. You can configure locations and enable geofencing for Android devices. ## Pass Value Localisation We've added support for localising pass field values. This is available in the pass create and update endpoints. For more information and usage examples, check out the [Translating Passes: Localisation](../documentation/passes/localisation/guide) Guide. This feature is in **closed beta** and currently only available on the API.
Please contact PassEntry for access. ## Pass Template Localisation We've added per‑field localisation so you can present pass content in your customers' preferred language without duplicating templates. You can now localise both field labels and values by providing translations under the optional `localisation` object (keyed by language codes like `en`, `fr`, `is`). The `defaultLanguage` defines the fallback, and responses only include localisation when translations exist. You can localise any subset of fields – untranslated fields automatically use the default language. For more information and usage examples, check out the [Translating Passes: Localisation](../documentation/passes/localisation/guide) Guide. This feature is in **closed beta** and currently only available on the API.
Please contact PassEntry for access. ## New Transit Pass type We've added a new transit pass type to the API. This allows you to create a pass that is used for transit. This is currently only available on the API.
Dashboard support is limited — preview and editing are restricted. Check out the guide here: [Transit Pass Template](/api-reference/v1/pass-templates/create-pass-template), [Transit Pass](/api-reference/v1/passes/create-pass) ## Pass Download Page - Localisation We've added support for localising the pass download page into up to 5 different languages. This is available in the pass download page editor under the 'Languages' section. ## Dynamic Barcode Values You can now make the barcode value dynamic by using the `%{passData.xyz}` syntax(e.g., `Hello, %{passData.extId}!`). Currently, only `%{passData.extId}` and `%{passData.uuid}` are supported. Check out the guide here: [Pass Barcode](/api-reference/v1/passes/create-pass#body-pass-barcode-value), [Pass Template Barcode](/api-reference/v1/pass-templates/create-pass-template#body-pass-template-barcode-value) ## Webhook Subscriptions API We've introduced a new Webhook Subscriptions API that allows you to programmatically manage your webhook endpoints and supports multiple webhook subscriptions. You can now: * Create, update, and delete webhook subscriptions * List all your active webhook subscriptions * Test webhook endpoints before going live * Rotate webhook secret keys for enhanced security Each webhook subscription can be configured to receive specific event types, making it easier to manage different integration endpoints. Check out the guide here: [Webhook Subscriptions API](/api-reference/v1/webhook-subscriptions/guide) ## Pass download page troubleshooting link We've added a new option to include a Help & FAQs link on a pass download page. When enabled, this link will redirect users to the troubleshooting URL you provide—making it easier for them to get assistance during the download process. This feature is available in the pass download page editor. ## Pass Template Fields API You can now use the `override_field_value` key to enforce the latest default values from a pass template.
When this key is set to `true`, all existing pass field values will be overridden with the current defaults defined in the pass template. If the key is not provided, it defaults to `false`, which means existing field values will be preserved and not forcibly updated. This key is only available when updating a pass template. Check out the guide here: [Pass Template Fields API](/api-reference/v1/pass-templates/update-pass-template#body-pass-template-fields) ## Pass Templates API now in open beta We’ve opened up access to the Pass Templates API to all users. You can now use it to create, update, and list pass templates, as well as manage template settings. If you run into any issues or have feedback, feel free to reach out to [support@passentry.com](mailto:support@passentry.com). Read the guide to get started: [Pass Templates API](/api-reference/v1/pass-templates/create-pass-template) ## Pass Download Pages We've added a new feature that allows you to create multiple custom pass download pages for your organisation. A page can be associated with an entity or one or more pass templates. This feature is available in the pass download pages section of the dashboard. Check out the guide here: [Pass Download Pages](../documentation/passes/downloading-passes/guide) ## Pass Created Webhook We've added a new webhook for when a pass is created. This webhook is triggered when a pass is created via API, dynamic forms or any other method. ## Ability to filter passes by external ID prefix You can now filter passes by external ID prefix to group passes together by extId, if they share a common prefix text value. `extIdPrefix` Check out the guide here: [Passes API](/api-reference/v1/passes/list-passes) ## Pass Templates API released on closed beta We've added a new API for managing pass templates. This allows you to create, update, and delete pass templates, as well as manage pass template settings. This API is currently in closed beta, and is only available to select users. If you'd like to join the beta, please contact us at [support@passentry.com](mailto:support@passentry.com). Check out the guide here: [Pass Templates API](/api-reference/v1/pass-templates/create-pass-template) ## Support for different barcode types We've added support for different barcode types, including `code128`, `pdf417`, and `aztec`. You can now select the barcode type from a dropdown when creating a pass and set the default barcode type for a pass template on dashboard. Barcode template defaults ## Improved team access controls Admins can now invite and remove team members, no longer limited to the lead account. A new "member" role offers view-only access. Account Meatball menu Change role modal ## Additional app linking options **Apple** Passes now support multiple App Store links, displaying the first available app in the passholder's country. **Google** Added customisable display text for Google App links on the front of passes. ## Custom NFC source for passes and setting NFC defaults at template level When creating a pass via dashboard, you can now select the NFC source from a dropdown. This allows you to use a custom NFC source for your pass. You can also set the default NFC source for a pass template, which will be used when creating a new pass from that template. NFC template defaults ## Custom pass download success message We've added a new feature that allows you to customise the success message that is displayed when a pass is downloaded. This feature is available in the pass download page editor. ## Loyalty Info Now Visible on Scans We've added loyalty data to the `/scans` and `/scans/log` endpoints - meaning loyalty actions are now logged at the scan level and visible in the 'Scans' section on the dashboard. You can now validate a pass and manage loyalty in a single request, with support for `add`, `redeem`, `override`, and `stamp` operations. ## VTAP Automatic Reader Setup You can now set up your VTAP readers automatically via the PassEntry Dashboard - no need to access VTAP Cloud. The setup takes just a few minutes. Check out the guide here: [VTAP Automatic Reader Setup](../documentation/guides/vtap-reader/guide) ## Batches API You can now interact with batches via [API](/api-reference/v1/batches/guide). We currently support listing, cancelling, and viewing batches, as well as creating wallet messaging batches. ## Custom Pass Issuance Forms We've added a new feature that allows you to create custom pass issuance forms for your passes. This feature is available in the pass template editor. Check out the guide here: [Custom Pass Issuance Forms](/documentation/guides/custom-download-forms/guide) ## Dashboard Redesign We've redesigned the Dashboard to improve visibility, filtering, and performance. The update includes top-level stats, and enhanced Passes, Scans, and Messaging sections with detailed breakdowns and flexible date range controls (7 days, 1 month, 6 months, all time). We've also made performance improvements for faster loading. ## Auto-format notification links When sending a notification with a link, the link will now be formatted automatically so it is clickable on both Apple and Google, without needing to know the device type. Check out the guide here: [Notification links](../documentation/passes/notifications/guide) ## Third Party Validation We've added support for third-party validation. This allows you to use your own validation logic, such as a QR code scanner, to validate passes. Check out the guide here: [Third Party Validation](../documentation/guides/validation-options/guide) # Adding an Apple Pass Certificate Source: https://docs.passentry.com/documentation/adding-an-apple-pass-certificate Set up an Apple Pass Type Identifier and certificate in PassEntry to issue Apple Wallet passes, plus certificate expiration, renewal and pass grouping. ## Overview ### What is an Apple Pass Type Identifier? An Apple Pass Type Identifier is required to create and update Apple Wallet passes. Each pass must be associated with a valid Pass Type Identifier and certificate for cryptographic authentication. If the Pass Type Identifier or certificate is invalid, passes cannot be added to Apple Wallet or receive updates. ### Do I need to create an Apple Pass Type Identifier? PassEntry can issue Apple Pass Type Identifiers on behalf of clients who meet our eligibility criteria. This allows you to create and update Apple Wallet passes without managing your own Pass Type Identifier. If your use case requires you to manage your own Pass Type Identifier, follow the guide below. If you are unsure, please reach out to PassEntry via [support@passentry.com](mailto:support@passentry.com). Apple Guide: [Create Wallet identifiers and certificates](https://developer.apple.com/help/account/capabilities/create-wallet-identifiers-and-certificates/) ## Guide The first step will be to reach out to PassEntry to create an entity for your Pass Type Identifier. To create an Apple Pass Type Identifier and the corresponding certificate, you will need to enroll in the [Apple Developer Program](https://developer.apple.com/programs/enroll/) if you haven't already. Enrollment takes 1-2 business days to complete and costs \$99 per year. 1. Login to your Apple Developer Portal and [Register a Pass Type ID](https://developer.apple.com/account/resources/identifiers/passTypeId/add/). 2. Enter a Description and Identifier and click "Continue". 3. Confirm the submitted information and click "Register" to create the Pass Type Identifier. In order to create a certificate, you will need to download a Certificate Signing Request (CSR). 1. Use the PassEntry API to download your CSR file. ```bash Download your CSR file theme={null} curl --location \ --request GET \ 'https://api.passentry.com/api/v1/entities/{YOUR_ENTITY_ID}/apple/certificate-signing-request' \ --header 'Authorization: Bearer {YOUR_API_KEY}' \ --header 'Accept: application/pkcs10' \ --output PassEntry.csr ``` 2. Save the CSR file to your computer. Check that the file is a valid CSR file by opening it in a text editor. It should contain the following: ```text theme={null} -----BEGIN CERTIFICATE REQUEST----- ... -----END CERTIFICATE REQUEST----- ``` In order to create, distribute and update Apple Wallet passes, you will need to create a certificate, associated with your Pass Type Identifier. 1. From your Apple Developer Portal, navigate to the [Create a New Certificate](https://developer.apple.com/account/resources/certificates/list) page. 2. Select "Pass Type ID Certificate" from the dropdown under "Services" and click "Continue". 3. Enter your Pass certificate Name(optional) and select the Pass Type Identifier you created in the previous step, then click "Continue". 4. You will be prompted to upload your CSR file. Upload the CSR file you downloaded in the previous step and click "Continue". 5. Your certificate has been created and will display information about the certificate, such as the certificate ID and the expiration date of the certificate. At this point, it is important that you note down the expiration date of the certificate, as you will need to renew it before it expires. 6. Download the certificate and save it to your computer, this will be saved as `pass.cer` Once you have downloaded your certificate, you will need to upload it to PassEntry. 1. Use the PassEntry API to upload your certificate file. ```bash Upload your certificate file theme={null} curl --location 'https://api.passentry.com/api/v1/entities/{YOUR_ENTITY_ID}/apple/certificate' \ --header 'Authorization: Bearer {YOUR_API_KEY}' \ --form 'certificate=@"{PATH_TO_YOUR_APPLE_CERTIFICATE}"' ``` 2. Your certificate has been uploaded and will display information about the certificate, such as the Pass Type Identifier\*\* \*\*and the expiration date of the certificate. ## Considerations ### Apple Developer Program Access It is critical you ensure persistent access to your Apple Developer Program account. If you lose access to your account, you will not be able to create and update Apple Wallet passes. ### Certificate Expiration Apple Pass Type Identifier certificates are valid for 1 year. Apple will notify you via email when your certificate is about to expire, and you will need to renew it by creating a new certificate. You are responsible for renewing your certificate before it expires. If your certificate expires, you will no longer be able to create and update Apple Wallet passes. ### Certificate Renewal To renew your certificate, you will need to create a new certificate. Follow the guide above, from the step "Create an Apple Pass Type Identifier Certificate" to create a new certificate. Then proceed to the step "Upload your certificate to PassEntry" to upload the new certificate. This will replace the certificate in PassEntry with the new certificate. ### Pass Grouping Passes with the same Pass Type Identifier will be grouped together in the Apple Wallet. If you want to separate passes in the wallet, these will need to have a different Pass Type Identifier. In PassEntry's architecture, each Pass Type Identifier is associated with an entity, so you will need to create a new entity for each additional Pass Type Identifier. # Batch wallet notifications and logging Source: https://docs.passentry.com/documentation/bulk-operations/batch-notifications/guide Send wallet notifications in bulk using pass IDs, segments, or CSV uploads, and track delivery status and errors for large-scale messaging. **Batch Wallet Notifications** let you send the same wallet message to large groups of pass holders in a single operation. Use batches for announcements, reminders or campaign messages where you need to notify many recipients at once. You can define recipients using **pass IDs, dynamic segments or CSV uploads**, making this feature suitable for one-off campaigns and large data sets **without requiring API integration.** Let’s explore each option in more detail below. This guide covers creating and managing batch wallet notifications using the PassEntry Dashboard. If you want to **send batch notifications programmatically** or integrate them into automated workflows, see the [Batch Wallet Messaging API documentation](/api-reference/v1/batches/create-wallet-messaging-batch). *** ## Creating a wallet notifications batch