---
title: "Create pass"
method: POST
path: "/api/v1/passes"
tags: ["Passes"]
---

# Create pass

`POST /api/v1/passes`

## Query parameters

- `passTemplate` string, required
- `extId` string
- `includePassDesign` boolean
- `includeLocations` boolean
- `includeBeacons` boolean
- `includePassSource` 'apple' | 'google'

## Request body

- object
  - `pass` object
    - `nfc[DEPRECATED]` boolean — 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.
    - `nfc` object
      - `enabled` boolean — Whether the pass is NFC enabled.
      - `source` 'extId' | 'custom' | 'uuid' — Source of the NFC message
      - `customValue` string — Custom NFC message, source must be set to custom
    - `qr` object — This parameter is deprecated, please use the barcode object instead.
      - `value` string — QR code value
      - `displayText` boolean — If true, display the QR code value as text on the pass
    - `barcode` object
      - `enabled` boolean, required — If true, barcode will be added to the pass
      - `type` 'qr' | 'code128' | 'aztec' | 'pdf417', required — Barcode type
      - `source` 'uuid' | 'extId' | 'custom', required — Source of the barcode
      - `value` string — Barcode value, source must be set to custom If your source type is `uuid` or `extId` don't need to set this value. You can make the value dynamic using the `%{passData.xyz}` syntax (e.g., `Hello, %{passData.extId}`). Currently, only `%{passData.extId}` and `%{passData.uuid}` are supported.
      - `displayText` boolean — If true, display the barcode value as text on the pass
    - `beacons` Beacons — Array of iBeacons, currently only available on Apple devices, due to Android device restrictions. Maximum of 10 iBeacons per pass. 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.
      - `data` Ibeacon[]
        - `proximityUUID` string — Unique identifier of a beacon
        - `major` integer — Major Value, provides additional identification for a beacon
        - `minor` integer — Minor Value, provides additional identification for a beacon
        - `relevantText` string — Text to display on lock screen when the user is in range of the beacon
      - `actions` BeaconActions — Actions to perform on beacons, only one at a time. Must be called using method PATCH
        - `deleteAll` boolean — Delete all beacons. Data array must be empty.
        - `replaceAll` boolean — Include ibeacons in the data array. When this action is invoked, all existing beacons are deleted, and replaced with the new beacons.
        - `delete` Ibeacon[] — Array of iBeacons to delete
          - `proximityUUID` string — Unique identifier of a beacon
          - `major` integer — Major Value, provides additional identification for a beacon
          - `minor` integer — Minor Value, provides additional identification for a beacon
          - `relevantText` string — Text to display on lock screen when the user is in range of the beacon
    - `locations` PassLocations — Array of locations. Maximum of 10 locations per pass. To update an existing location, include latitude and longitued values in the data array while sending a PATCH request. Only relevantText and maxDistance values can be updated. For more actions, use the beaconActions object.
      - `data` PassLocation[]
        - `latitude` number, double — Latitude of the location in degrees
        - `longitude` number, double — Longitude of the location in degrees
        - `maxDistance` integer — Specifies the maximum radius distance in meters. If passType is eventTicket, max is 1000. Otherwise, max is 100. Currently only available on Apple devices, due to Android device restrictions.
        - `relevantText` string — Text to display on lock screen when the user is in range of the location. Currently only available on Apple devices, due to Android device restrictions.
      - `actions` PassLocationActions — Actions to perform on locations, only one at a time. Must be called using method PATCH
        - `deleteAll` boolean — Delete all locations. Data array must be empty.
        - `replaceAll` boolean — Include locations in the data array. When this action is invoked, all existing locations are deleted, and replaced with the new locations.
        - `delete` PassLocation[] — Array of locations to delete
          - `latitude` number, double — Latitude of the location in degrees
          - `longitude` number, double — Longitude of the location in degrees
          - `maxDistance` integer — Specifies the maximum radius distance in meters. If passType is eventTicket, max is 1000. Otherwise, max is 100. Currently only available on Apple devices, due to Android device restrictions.
          - `relevantText` string — Text to display on lock screen when the user is in range of the location. Currently only available on Apple devices, due to Android device restrictions.
    - `templateOverride` object — 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.
      - `backgroundColor` string, nullable — 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` string, nullable — Must be a valid hex color code. Only valid for iphone passes
      - `textColor` string, nullable — Must be a valid hex color code. Only valid for iphone passes
      - `bannerImage` object — Banner image using an Image Asset reference
        - `imageAssetId` string — ID of an uploaded Image Asset of type `banner`. See [Image Assets guide](/api-reference/v1/image-assets/guide)
      - `logoImage` object — Logo image using an Image Asset reference. Does not update Google logo, Google logo must be set at template level.
        - `imageAssetId` string — ID of an uploaded Image Asset of type `logo`. See [Image Assets guide](/api-reference/v1/image-assets/guide)
      - `thumbnailImage` object — Thumbnail image using an Image Asset reference. Pass type must be generic. Does not appear on Google passes.
        - `imageAssetId` string — ID of an uploaded Image Asset of type `thumbnail`. See [Image Assets guide](/api-reference/v1/image-assets/guide)
      - `artworkImage` object — Artwork image using an Image Asset reference. Only valid for event ticket templates with enhanced event ticket enabled.
        - `imageAssetId` string — ID of an uploaded Image Asset of type `artwork`. See [Image Assets guide](/api-reference/v1/image-assets/guide)
      - `secondaryLogoImage` object — Secondary logo using an Image Asset reference. Only valid for event ticket templates with enhanced event ticket enabled.
        - `imageAssetId` string — ID of an uploaded Image Asset of type `secondaryLogo`. See [Image Assets guide](/api-reference/v1/image-assets/guide)
      - `venueMapImage` object — Venue map image using an Image Asset reference. Only valid for event ticket templates with enhanced event ticket enabled.
        - `imageAssetId` string — ID of an uploaded Image Asset of type `venueMap`. See [Image Assets guide](/api-reference/v1/image-assets/guide)
    - `expiresAt` string, nullable — 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` string — 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 ***Note**: You can only set this field if the pass type is `eventTicket` or `transit`*
    - `enhancedEventData` object — 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. This data is entirely separate from legacy pass fields (primaryFields, auxiliaryFields, etc.) and does not affect legacy event ticket rendering on older devices. ***Note**: This feature is in **closed beta**. The API structure may change and you may encounter bugs. Please contact PassEntry for access.*
      - `event` object — Core event information. Required when enhancedEventData is provided.
        - `name` string, required — Name of the event. Triggers an automatic Wallet notification to pass holders if updated after issuance.
        - `startDateTime` string, required — ISO 8601 date with timezone. Displayed in the top right of the pass header.
        - `endDateTime` string — ISO 8601 date with timezone.
      - `venue` object — Venue information for the event. Required when enhancedEventData is provided.
        - `name` string, required — Shown at the bottom left of the pass chin.
        - `region` string — Used when there is no specific venue.
        - `location` object, required — Latitude and longitude of the venue.
          - `latitude` number, required
          - `longitude` number, required
        - `contactPhoneNumber` string — Appears as a quick action button in the Apple event guide.
        - `contactEmailAddress` string — Appears as a quick action button in the Apple event guide.
        - `websiteUrl` string — Appears as a quick action button in the Apple event guide.
      - `seat` object — Seating information. Values can be any string.
        - `number` string — Rendered as a labelled column in the pass chin.
        - `row` string — Rendered as a labelled column in the pass chin.
        - `section` string — Rendered as a labelled column in the pass chin.
        - `gate` string — Flexible text field for entrance information.
      - `eventGuide` object — Event guide fields. Required when enhancedEventData is provided. URL fields appear as quick action buttons in the Apple event guide.
        - `venueOpenDateTime` string, required — ISO 8601 date with timezone.
        - `venueCloseDateTime` string, required — ISO 8601 date with timezone.
        - `bagPolicyUrl` string
        - `orderFoodUrl` string
        - `transitInformationUrl` string
        - `parkingInformationUrl` string
        - `directionsInformationUrl` string
        - `merchandiseUrl` string
        - `accessibilityUrl` string
        - `addOnUrl` string
  - `passAction` 'deactivate' | 'reactivate' — Only available when updating the pass. - 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. - 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` Location[] — Array of locations. Maximum of 10 locations
    - `name` string, required — Name of the location, used for display purposes only
    - `latitude` number, double, required — Latitude of the location
    - `longitude` number, double, required — Longitude of the location
    - `radius` integer — Effective geofence radius of the location in meters. Maximum is 1000 for eventTicket passes, 100 for other pass types. Currently only available on Apple devices, due to Android device restrictions.
    - `message` string — Message to display when user enters geofence. Currently only available on Apple devices, due to Android device restrictions.
  - `beacons` Beacon[] — Array of beacons, currently only available on Apple devices, due to Android device restrictions. Maximum of 10 beacons
    - `name` string, required — Name of the beacon, used for display purposes only
    - `proximityUuid` string, required — Unique identifier of the beacon
    - `major` integer — Major Value, provides additional identification for a beacon
    - `minor` integer — Minor Value, provides additional identification for a beacon
    - `message` string, nullable — Message to display on lock screen when the user is in range of the beacon
  - `groupTag` string — Tag used for grouping passes
  - `groupTags` unknown[] — Tags used for grouping passes
    - unknown
  - `binding` object — 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. **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. Once a pass is bound to a platform (Apple or Google), it cannot be downloaded on the other platform. **Google Wallet**: The pass is restricted to the specified email account using a SHA-256 hash. **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. See the [Pass Binding guide](/documentation/passes/pass-binding/guide) for full details.
    - `email` string, email, required — 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.
    - `learnMoreUrl` string, uri, required — 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.

## Response `200`

Successful

- object
  - `data` SerializedPassObject
    - `id` string — Auto-generated UUID of the pass
    - `type` string
    - `attributes` object
      - `downloadUrl` string — Unique download URL of the pass
      - `passType` 'generic' | 'eventTicket' | 'storeCard' | 'transit' — Pass Type
      - `deviceType` 'android' | 'iphone'
      - `createdAt` string — In ISO8601 format, UTC
      - `status` 'issued' | 'active' | 'removed' | 'deactivated' | 'nullified' — Pass Status
      - `extId` string, nullable — Pass External ID
      - `groupTag` string, nullable — Tag used for grouping passes
      - `groupTags` unknown
      - `addedAt` string, nullable — When pass has been added to wallet by the user. In ISO8601 format, UTC
      - `removedAt` string, nullable — When pass has been removed from wallet by the user. In ISO8601 format, UTC
      - `deactivatedAt` string, nullable — When pass has been deactivated. In ISO8601 format, UTC
      - `nullifiedAt` string, nullable — When pass has been nullified. In ISO8601 format, UTC
      - `expiresAt` string, nullable — Pass will expire at this time. In ISO8601 format, UTC
      - `passTemplateUuid` string — UUID of corresponding pass template
      - `passTemplateName` string — Name of corresponding pass template
      - `nfc` string, nullable — If present, the NFC message to be conveyed when the pass is tapped
      - `barcode` object — If present, the barcode type and value
        - `enabled` boolean — Barcode enabled
        - `type` 'qr' | 'code128' | 'aztec' | 'pdf417' — Barcode type
        - `source` 'uuid' | 'extId' | 'custom' — Barcode source
        - `value` string — Barcode value
        - `displayText` boolean — If true, display the barcode value as text on the pass
      - `latestMessage` string, nullable — If present, the last push message sent to the pass
      - `passContent` object
      - `passDesign` object — Pass design values, present if pass template has been overridden for this pass, or if 'includePassDesign' query param is set to true
        - `backgroundColor` string — Pass background color in hex format
        - `labelColor` string — Pass label color in hex format. Only valid for iphone passes
        - `textColor` string — Pass text color in hex format. Only valid for iphone passes
        - `bannerImageUrl` string — URL of pass banner image
        - `logoImageUrl` string — URL of pass logo image
        - `thumbnailImageUrl` string — URL of pass thumbnail image. Only present for generic passes.
        - `artworkImageUrl` string — URL of pass artwork image. Only present for event ticket passes with enhanced event ticket enabled.
        - `secondaryLogoImageUrl` string — URL of pass secondary logo image. Only present for event ticket passes with enhanced event ticket enabled.
        - `venueMapImageUrl` string — URL of pass venue map image. Only present for event ticket passes with enhanced event ticket enabled.
      - `locations` SerializedLocation[] — Locations, present if 'includeLocations' query param is set to true
        - `name` string — Name of the location, used for display purposes only
        - `latitude` number, double — Latitude of the location
        - `longitude` number, double — Longitude of the location
        - `radius` integer — Effective geofence radius of the location in meters. Maximum is 1000 for eventTicket passes, 100 for other pass types. Currently only available on Apple devices, due to Android device restrictions.
        - `message` string — Message to display when user enters geofence. Currently only available on Apple devices, due to Android device restrictions.
        - `address` string — Geocoded address of the location. Used for display purposes only. This is calculated automatically from the latitude and longitude values
      - `beacons` SerializedBeacon[] — Beacons, present if 'includeBeacons' query param is set to true
        - `proximityUuid` string — Unique identifier of the beacon
        - `major` integer — Major Value, provides additional identification for a beacon
        - `minor` integer — Minor Value, provides additional identification for a beacon
        - `message` string, nullable — Message to display on lock screen when the user is in range of the beacon
        - `name` string — Name of the beacon, used for display purposes only
      - `enhancedEventData` object — Enhanced event data for poster event ticket. Only present on event ticket passes with enhanced event ticket enabled on their template. ***Note**: This feature is in **closed beta**. The API structure may change and you may encounter bugs. Please contact PassEntry for access.*
        - `event` object
          - `name` string
          - `startDateTime` string
          - `endDateTime` string
        - `venue` object
          - `name` string
          - `region` string
          - `location` object
            - `latitude` number
            - `longitude` number
          - `contactPhoneNumber` string
          - `contactEmailAddress` string
          - `websiteUrl` string
        - `seat` object
          - `number` string
          - `row` string
          - `section` string
          - `gate` string
        - `eventGuide` object
          - `venueOpenDateTime` string
          - `venueCloseDateTime` string
          - `bagPolicyUrl` string
          - `orderFoodUrl` string
          - `transitInformationUrl` string
          - `parkingInformationUrl` string
          - `directionsInformationUrl` string
          - `merchandiseUrl` string
          - `accessibilityUrl` string
          - `addOnUrl` string
      - `passSource` object — Pass source, present if 'includePassDesign' query param is present, one of Apple/Google and current pass status is not 'active'.
        - `oneOf` object
          - `appleBase64` string — Apple Wallet Pass Base64 string, to generate the pass, decode the string and save as a .pkpass file. Will prompt the user to download the pass to their Apple Wallet when opened on an iPhone.
          - `googleDownloadUrl` string — Google Wallet Pass download URL. Will prompt the user to download the pass to their Google Wallet when opened on an Android device.
      - `binding` object, nullable — 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.
        - `platform` 'apple' | 'google' | 'null', nullable — The wallet platform this pass is bound to. Null when the pass has been created with binding but not yet downloaded.
        - `bound` boolean — Whether the pass binding has been finalised. True after the pass has been successfully downloaded and the binding verified.
        - `bindingEmail` string, nullable — 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` string — URL shown to the user explaining account binding.

## Other responses

- `400` — Error: Bad Request
- `401` — Error: Unauthorized
- `404` — Error: Not Found

---

[API](https://skmtc.net/passentry/apis/passentry-api.md) · [All operations](https://skmtc.net/passentry/apis/passentry-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/passentry/passentry-api/versions/2c7dc0306b04/schema)