Developer Documentation (API)

Create a new Pass

POST Request
Endpoint URL https://veski.leikbreytir.is/api/pass?passtemplate={pass-template-uid}&zapierStyle=false
Purpose
Creates a new pass using the given pass template.

Required input parameters

  • HTTP Authorization Header that contains your API key
  • pass-template UID as parameter with the parameter name passtemplate
  • boolean zapierStyle is optional. If it is true you don’t have to submit the nested array structure but can use the keys that have been returned by the pass-template endpoint that describes the required fields of a pass-template.
  • the required keys or if you omit or set zapierStyle to false the array that is specified in the endpoint that describes a pass must be submitted as JSON-Payload. See the examples below.

The following parameters are optional and will vary based on your pass template.

To get a list of expected and valid parameters, use the endpoint to get information about a template or the endpoint listing fields only (used for zapierStyle).

  • (optional) userProvidedId – this is a ID you can specify – it can be used as URL parameter to access the created pass. The URL to access the pass via this ID is always https://veski.leikbreytir.is/passinstance/show/customer-id/userProvidedId.  You can find the fixed part of the URL including your customer ID in your Gift to Wallet account settings.
  • (optional) enforceUniqueUserProvidedId – if set to true, the endpoint will return status 400 if you specify a userProvidedId that is already used within your account.
  • (optional) groupingIdentifier – a value that is used to group passes. If a grouping identifier is specified, passes with the same style, pass type identifier, and grouping identifier are displayed as a group.Only valid for event tickets and boarding passes. Will be ignored when it is submitted for other passes. In order to have this value respected, you need to enable the correspondig option on your pass template (tab general –> extended options –> ask for grouping identifier on pass creation)
  • (optional) additionalProperties – if you’re using additional properties in your template, provide the ID of the additional property together with its value in an array called additional properties.
  • (optional) urlToThumbnail – if you’re template is using a different thumbnail per pass, you can pass a URL to a valid image here. It will then be used on the pass that is about to be created.
  • (optional) urlToBackground – if you’re template is using a different background image per pass you can pass a URL to a valid image here. It will then be used on the pass that is about to be created.
  • (optional) urlToLogo – if you’re template is using a different logo image per pass you can pass a URL to a valid image here. It will then be used on the pass that is about to be created.
  • (optional) expirationDate – if your template is using a different expiration date per pass you can specify this date here in the format Y-m-d H:i.
  • (optional) relevantDate – if your template is using a different relevant date per pass you can specify this date here in the format Y-m-d H:i. It’s the date when the pass shows up on the lockscreen.
  • (optional) labelColor – if your template is using a different label color per pass you can specify a valid hexadecimal color here. Invalid values will be dropped and the default color is used.
  • (optional) foregroundColor – if your template is using a different foreground color (the color that field values have) per pass you can specify a valid hexadecimal color here. Invalid values will be dropped and the default color is used.
  • (optional) backgroundColor – if your template is using a different background color per pass you can specify a valid hexadecimal color here. Invalid values will be dropped and the default color is used.
  • (optional) emailRecipient – if you’ve selected an email template in the sendout settings of your pass template, you can include an email address here and Gift to Wallet will automatically send the pass via email to the address you’ve specified.
  • (optional) phoneRecipient – if you’ve specified an SMS text in the sendout settings of your pass template, you can include a phone number here and Gift to Wallet will automatically send the pass via SMS to the number you’ve specified.
  • (optional) locations – an array of valid coordinates. latitude and longitude must contain valid values. relevantText is an optional description for the push notification that is shown. You can also specify an altitude and the maxDistance which defines the number of meters around the coordinate where the notification will be shown.
  • (optional) storedValue – a float value that reflects the pass’ value. This can e.g. be a monetary value of a gift card, the number of stamps of a stamp card or the number of points of a loyalty campaign. If you have configured a pass functionality for the template of the pass, additional actions like a change of the loyalty tier might be triggered by increasing or decreasing the stored value.
  • (optional) eligibleValidationPlaces – array of strings where this ticket is valid. This is applied when an app scan is used and and app configuration ID is given when requesting info about a pass. The given values have to be part of the validValidationPlaces array of the template. Otherwise, HTTP status 400 will be returned.
  • (optional) downloadPin – a PIN that users have to enter before being able to download a pass. Please note that you need to enable the PIN feature on a template level before the PIN verification will be shown.
If you have enabled different background images for each pass for your template and are using translations for the template, you can specify different images per language using the API. To do this submit an array called localizedBackgroundImages with elements that use the language code as key and the URL to the image as the value. An example is included in the code snippet below. If you want to know the activated languages for the template, call the endpoint that returns details about a template.

Returned values

JSON-Array containing the UID and the name of your pass-templates.

  • identifier – the unique identifier of the created pass. You should store it in your application if you want to update or delete the pass later.
  • uri – the URI of the pass that can be used to update or delete it
  • linkToPassFile – the link where the pkpass-file can be downloaded. The pkpass-file is the actual pass that can be opened on iPhones directly. Attention: Don’t use this link to provide the pass to your users in general. It should only be used e.g. if you want to send the Wallet pass to your customers via email after creating a pass. This file is subject to change if you send push notifications which means it might become outdated pretty soon.
  • linkToPassPage – link to the download page for this pass that detects the operating system of the Smartphone that is used and provides device specific help. You are encouraged to always use this link when providing the pass to users because it provides the best user experience on all devices.
  • genericProperties – an array containing the values that you can specify in the extended properties of a pass template
  • ErrorMessage – if an error occurs we’ll include the error message here

Example input (zapierStyle=false or omitted)

{
	"passFrontFields": {
		"headerFields": [{
				"value": "Valid to"
			},
			{
				"value": "Second value"
			}
		],
		"primaryFields": [{
			"value": "Customer-No."
		}]
	},
	"passBackFields": [],
	"additionalProperties": {
		"5b3f2f9f66a228.52093670": "John",
		"5b3f2f9f66a228.52093671": "Doe"
	},
	"urlToBackground": "https://veski.leikbreytir.is/default-language.png",
	"localizedBackgroundImages": {
		"de": "https://veski.leikbreytir.is/german.png",
		"nl": "https://veski.leikbreytir.is/dutch.png"
	},
	"locations": [{
		"latitude": 48.0933826,
		"longitude": 11.6286617,
		"relevantText": "Welcome to the show!",
		"altitude": 200,
		"maxDistance": 300
	}],
	"eligibleValidationPlaces": ["room1"]
}

Example input (zapierStyle=true)

{
	"primaryFields_0_Customerno": "382716",
	"secondaryFields_0_FirstName": "John",
	"secondaryFields_1_LastName": "Doe",
	"barcodeValue": "3897897988979823497234",
	"5b3f2f9f66a228.52093670": "Zurich",
	"5b3f2f9f66a228.52093671": "Example street 1",
	"urlToBackground": "https://veski.leikbreytir.is/default-language.png",
	"localizedBackgroundImages": {
		"de": "https://veski.leikbreytir.is/german.png",
		"nl": "https://veski.leikbreytir.is/dutch.png"
	},
	"eligibleValidationPlaces": ["room1"]
}

Example output

{
    "identifier": "f4379715-7a69-1742-38ae-836554724306",
    "uri": "https://veski.leikbreytir.is/api/pass/f4379715-7a69-1742-38ae-836554724306",
    "linkToPassFile": "https://veski.leikbreytir.is/_Resources/Persistent/fcef30ff61c575173f32984178796f5e3fde5541/pass.pkpass",
    "linkToPassPage": "https://veski.leikbreytir.is/p/1234567",
    "genericProperties": {
        "my-id": "12345678",
        "second-field": "Example value"
    },
    "ErrorMessage": ""
}