--- title: "Create the Apple Wallet template" method: POST path: "/companies/{company_key}/campaigns/wallet/{token}/passbook_template" tags: ["iOS Wallet Templates API"] --- # Create the Apple Wallet template `POST /companies/{company_key}/campaigns/wallet/{token}/passbook_template` ## Request - Base URL: `https://public-api.vibescm.com` - URL: `https://public-api.vibescm.com/companies/{company_key}/campaigns/wallet/{token}/passbook_template` - Auth: HTTP basic Create the Apple Wallet (iOS) pass template for a wallet campaign. Field semantics follow Apple Wallet Passes (https://developer.apple.com/documentation/WalletPasses). Many text fields accept Liquid personalization tags that are replaced per recipient. ## Path parameters - `company_key` string, required - `token` string, required ## Headers - `X-API-Version` string - `Content-Type` string, required ## Request body - IosTemplateRequest - `passbook_template` AppleWalletTemplateBody, required: Design and content of an Apple Wallet (iOS) pass — a card with a front and a back whose fields map to fixed regions on the card. Field semantics follow Apple Wallet Passes (https://developer.apple.com/documentation/WalletPasses). Many text fields accept Liquid personalization tags that are replaced per recipient. - `organization_name` string: Organization name shown next to the lock-screen notification. Falls back to the signing certificate's value if not set. - `pass_description` string: Short accessibility (VoiceOver) description of the pass. Required by Apple Wallet; defaults to the card type if left blank. - `logo_text` string: Text rendered beside the logo at the top of the pass. - `nfc_message` string: Payload delivered when the pass is tapped on an NFC terminal (tap-to-interact). - `app_id` string: Optional iOS App Store identifier (for example `id123456` or `123456`). When set, the pass links to the associated app and surfaces an open-app affordance. - `thank_you_url` string: Optional URL opened after the pass is installed. - `thank_you_message` string: Optional message shown after the pass is installed. Ignored when `thank_you_url` is set. - `sharing_prohibited` boolean: When `true`, hides the pass's share button. - `colors` object: Pass colors as hex values, for example `#ff0000`. All three are required. - `background` string: Card fill color. - `foreground` string: Color of the field values. - `label` string: Color of the field labels. - `barcode` object: The scannable code shown on the pass. - `type` string: Barcode format — one of `PKBarcodeFormatQR`, `PKBarcodeFormatPDF417`, `PKBarcodeFormatAztec`, or `PKBarcodeFormatCode128` (Apple's format identifiers). - `code` string: Barcode content (ASCII only). - `description` string: Human-readable text shown alongside the barcode. - `images` object: Images shown on the pass, keyed by role. Each role occupies a fixed slot on the card. `logo` and `icon` are required; the others are optional. - `logo` object: Brand logo, shown at the top-left of the pass. Required. - `url` string: Public URL of the logo image. - `icon` object: Small icon used on the lock screen and in notifications. Required. - `url` string: Public URL of the icon image. - `strip` object: Wide banner image shown behind the primary fields. - `url` string: Public URL of the strip image. - `preview_strip` object: Strip image shown in the "Add to Wallet" preview before the pass is installed. - `url` string: Public URL of the preview strip image. - `background_image` object: Full-card background image. Event ticket passes only. - `url` string: Public URL of the background image. - `thumbnail` object: Small square image shown to the right of the primary fields. Event ticket passes only. - `url` string: Public URL of the thumbnail image. - `strip_images` object[]: Per-recipient alternates of the strip banner. They share the single strip slot — only one is shown per pass, chosen at issue time by matching the recipient's `IMAGE_CODE` personalization token against `image_code`. If none matches, the default `strip` image is shown. Each `image_code` must be unique within the array. - `image_code` string: Unique code used to select this image for a recipient. - `url` string: Public URL of the strip image. - `fields` object: The pass's text content, grouped into Apple Wallet's five fixed regions. Each region holds an array of label/value entries. - `header` PassbookField[]: Top edge of the pass, beside the logo. Stays visible when the pass is stacked/collapsed in Wallet — best for the one value seen at a glance (balance, gate, points). - `label` string: Small caption shown above the value (rendered in the label color). - `value` string: Field content (rendered in the foreground color). - `change_message` string: Notification text shown when this field changes on an installed pass. Must contain the `%@` placeholder for the new value. - `primary` PassbookField[]: The largest, most prominent text on the front, over the strip image — the headline value (the offer, the seat, the reward). - `label` string: Small caption shown above the value (rendered in the label color). - `value` string: Field content (rendered in the foreground color). - `change_message` string: Notification text shown when this field changes on an installed pass. Must contain the `%@` placeholder for the new value. - `secondary` PassbookField[]: A smaller row beneath the primary fields — supporting details such as expiration or cardholder name. - `label` string: Small caption shown above the value (rendered in the label color). - `value` string: Field content (rendered in the foreground color). - `change_message` string: Notification text shown when this field changes on an installed pass. Must contain the `%@` placeholder for the new value. - `auxiliary` PassbookField[]: A further, smallest row beneath the secondary fields — extra details such as member level or location. - `label` string: Small caption shown above the value (rendered in the label color). - `value` string: Field content (rendered in the foreground color). - `change_message` string: Notification text shown when this field changes on an installed pass. Must contain the `%@` placeholder for the new value. - `back` PassbookField[]: The reverse side, reached by tapping the info button on the pass — long-form content such as terms, contact info, and fine print. - `label` string: Small caption shown above the value (rendered in the label color). - `value` string: Field content (rendered in the foreground color). - `change_message` string: Notification text shown when this field changes on an installed pass. Must contain the `%@` placeholder for the new value. - `trackers` object[]: Tracking-pixel definitions. Each renders a 1x1 image beacon that fires on a pass lifecycle event for analytics. - `action` string: Lifecycle event that fires the tracker. One of `view`, `add`, or `remove`. - `tag` string: Beacon URL requested when the action occurs. - `personalization_options` object: Configures the Apple Wallet sign-up form a user fills in when adding the pass, to enrol them in a rewards program. Applies to loyalty (store-card) passes only. Returned only when configured; the `api` username and password are masked in responses. - `description` string: Text shown on the enrollment screen. - `terms_and_conditions` string: Terms the user must accept to enroll. - `required_personalization_fields` string[]: Personal details collected during enrollment, for example `given_name`, `family_name`, `full_name`, `email_address`, `phone_number`, `postal_code`. - `api` object: Loyalty backend the enrollment form is submitted to. - `base_url` string: Base URL of the loyalty backend. - `username` string: Username for the loyalty backend (HTTP Basic). Masked in responses. - `password` string: Password for the loyalty backend (HTTP Basic). Masked in responses. ## Response `201` The Apple Wallet template was created. - IosTemplateResponse: Design and content of an Apple Wallet (iOS) pass — a card with a front and a back whose fields map to fixed regions on the card. Field semantics follow Apple Wallet Passes (https://developer.apple.com/documentation/WalletPasses). Many text fields accept Liquid personalization tags that are replaced per recipient. - `id` string: Unique identifier of the Apple Wallet template. - `active` boolean: Whether the template is active. - `created_at` string: When the template was created, in ISO-8601 format. - `updated_at` string: When the template was last updated, in ISO-8601 format. - `organization_name` string: Organization name shown next to the lock-screen notification. Falls back to the signing certificate's value if not set. - `pass_description` string: Short accessibility (VoiceOver) description of the pass. Required by Apple Wallet; defaults to the card type if left blank. - `logo_text` string: Text rendered beside the logo at the top of the pass. - `nfc_message` string: Payload delivered when the pass is tapped on an NFC terminal (tap-to-interact). - `app_id` string: Optional iOS App Store identifier (for example `id123456` or `123456`). When set, the pass links to the associated app and surfaces an open-app affordance. - `thank_you_url` string: Optional URL opened after the pass is installed. - `thank_you_message` string: Optional message shown after the pass is installed. Ignored when `thank_you_url` is set. - `sharing_prohibited` boolean: When `true`, hides the pass's share button. - `colors` object: Pass colors as hex values, for example `#ff0000`. All three are required. - `background` string: Card fill color. - `foreground` string: Color of the field values. - `label` string: Color of the field labels. - `barcode` object: The scannable code shown on the pass. - `type` string: Barcode format — one of `PKBarcodeFormatQR`, `PKBarcodeFormatPDF417`, `PKBarcodeFormatAztec`, or `PKBarcodeFormatCode128` (Apple's format identifiers). - `code` string: Barcode content (ASCII only). - `description` string: Human-readable text shown alongside the barcode. - `images` object: Images shown on the pass, keyed by role. Each role occupies a fixed slot on the card. `logo` and `icon` are required; the others are optional. - `logo` object: Brand logo, shown at the top-left of the pass. Required. - `url` string: Public URL of the logo image. - `icon` object: Small icon used on the lock screen and in notifications. Required. - `url` string: Public URL of the icon image. - `strip` object: Wide banner image shown behind the primary fields. - `url` string: Public URL of the strip image. - `preview_strip` object: Strip image shown in the "Add to Wallet" preview before the pass is installed. - `url` string: Public URL of the preview strip image. - `background_image` object: Full-card background image. Event ticket passes only. - `url` string: Public URL of the background image. - `thumbnail` object: Small square image shown to the right of the primary fields. Event ticket passes only. - `url` string: Public URL of the thumbnail image. - `strip_images` object[]: Per-recipient alternates of the strip banner. They share the single strip slot — only one is shown per pass, chosen at issue time by matching the recipient's `IMAGE_CODE` personalization token against `image_code`. If none matches, the default `strip` image is shown. Each `image_code` must be unique within the array. - `image_code` string: Unique code used to select this image for a recipient. - `url` string: Public URL of the strip image. - `fields` object: The pass's text content, grouped into Apple Wallet's five fixed regions. Each region holds an array of label/value entries. - `header` PassbookField[]: Top edge of the pass, beside the logo. Stays visible when the pass is stacked/collapsed in Wallet — best for the one value seen at a glance (balance, gate, points). - `label` string: Small caption shown above the value (rendered in the label color). - `value` string: Field content (rendered in the foreground color). - `change_message` string: Notification text shown when this field changes on an installed pass. Must contain the `%@` placeholder for the new value. - `primary` PassbookField[]: The largest, most prominent text on the front, over the strip image — the headline value (the offer, the seat, the reward). - `label` string: Small caption shown above the value (rendered in the label color). - `value` string: Field content (rendered in the foreground color). - `change_message` string: Notification text shown when this field changes on an installed pass. Must contain the `%@` placeholder for the new value. - `secondary` PassbookField[]: A smaller row beneath the primary fields — supporting details such as expiration or cardholder name. - `label` string: Small caption shown above the value (rendered in the label color). - `value` string: Field content (rendered in the foreground color). - `change_message` string: Notification text shown when this field changes on an installed pass. Must contain the `%@` placeholder for the new value. - `auxiliary` PassbookField[]: A further, smallest row beneath the secondary fields — extra details such as member level or location. - `label` string: Small caption shown above the value (rendered in the label color). - `value` string: Field content (rendered in the foreground color). - `change_message` string: Notification text shown when this field changes on an installed pass. Must contain the `%@` placeholder for the new value. - `back` PassbookField[]: The reverse side, reached by tapping the info button on the pass — long-form content such as terms, contact info, and fine print. - `label` string: Small caption shown above the value (rendered in the label color). - `value` string: Field content (rendered in the foreground color). - `change_message` string: Notification text shown when this field changes on an installed pass. Must contain the `%@` placeholder for the new value. - `trackers` object[]: Tracking-pixel definitions. Each renders a 1x1 image beacon that fires on a pass lifecycle event for analytics. - `action` string: Lifecycle event that fires the tracker. One of `view`, `add`, or `remove`. - `tag` string: Beacon URL requested when the action occurs. - `personalization_options` object: Configures the Apple Wallet sign-up form a user fills in when adding the pass, to enrol them in a rewards program. Applies to loyalty (store-card) passes only. Returned only when configured; the `api` username and password are masked in responses. - `description` string: Text shown on the enrollment screen. - `terms_and_conditions` string: Terms the user must accept to enroll. - `required_personalization_fields` string[]: Personal details collected during enrollment, for example `given_name`, `family_name`, `full_name`, `email_address`, `phone_number`, `postal_code`. - `api` object: Loyalty backend the enrollment form is submitted to. - `base_url` string: Base URL of the loyalty backend. - `username` string: Username for the loyalty backend (HTTP Basic). Masked in responses. - `password` string: Password for the loyalty backend (HTTP Basic). Masked in responses. --- [API](https://skmtc.dev/vibes/apis/vibes-platform-api.md) - [All operations](https://skmtc.dev/vibes/apis/vibes-platform-api/llms.txt) - [OpenAPI document](https://skmtc.dev/vibes/apis/vibes-platform-api/revisions/e235838f2e50?raw)