Passbook Web Service Reference

A REST-style web service protocol is used to communicate with your server about changes to passes, and to fetch the latest version of a pass when it has changed. The endpoints always begin with the web service URL, as specified in the pass, followed by the protocol version number. For example, a request for the latest version of the pass of type com.apple.pass.example and serial number ABC123 might look like the following:

Art/web_service_url_2x.png

All of the endpoints, including the logging endpoint, are required.

For all endpoints, specify the application/json MIME type for responses that contain JSON data, and the application/vnd.apple.pkpass for responses that contain a Passbook pass.

If a request fails—for example, due to a network connectivity issue—Passbook tries again several times after waiting a period of time. Each time it tries again, it waits longer. If the request continues to fail, it eventually gives up.

Registering a Device to Receive Push Notifications for a Pass

POST request to webServiceURL/version/devices/deviceLibraryIdentifier/registrations/passTypeIdentifier/serialNumber

Parameters

webServiceURL

The URL to your web service, as specified in the pass.

version

The protocol version. Currently, v1.

deviceLibraryIdentifier

A unique identifier that is used to identify and authenticate this device in future requests.

passTypeIdentifier

The pass’s type, as specified in the pass.

serialNumber

The pass’s serial number, as specified in the pass.

Header

The Authorization header is supplied; its value is the word “ApplePass”, followed by a space, followed by the pass’s authorization token as specified in the pass.

Payload

The POST payload is a JSON dictionary, containing a single key and value:

pushToken

The push token that the server can use to send push notifications to this device.

Response

Discussion

Any time the pass is updated, your server sends a push notification with an empty JSON dictionary as the payload to the device using the given push notification token. This continues until the device is explicitly unregistered (as described in “Unregistering a Device”).

Getting the Serial Numbers for Passes Associated with a Device

GET request to webServiceURL/version/devices/deviceLibraryIdentifier/registrations/passTypeIdentifier?passesUpdatedSince=tag

Parameters

webServiceURL

The URL to your web service, as specified in the pass.

version

The protocol version. Currently, v1.

deviceLibraryIdentifier

A unique identifier that is used to identify and authenticate the device.

passTypeIdentifier

The pass’s type, as specified in the pass.

tag

A tag from a previous request. (optional)

If the passesUpdatedSince parameter is present, return only the passes that have been updated since the time indicated by tag. Otherwise, return all passes.

Response

Discussion

The modification tag is used to give a name to a point in time. It is typically convenient to use a timestamp, but the server is free to use another approach. The tag is treated as an opaque value by the system.

Getting the Latest Version of a Pass

GET request to webServiceURL/version/passes/passTypeIdentifier/serialNumber

Parameters

webServiceURL

The URL to your web service, as specified in the pass.

version

The protocol version. Currently, v1.

passTypeIdentifier

The pass’s type, as specified in the pass.

serialNumber

The unique pass identifier, as specified in the pass.

Header

The Authorization header is supplied; its value is the word “ApplePass”, followed by a space, followed by the pass’s authorization token as specified in the pass.

Response

Discussion

Support standard HTTP caching on this endpoint: check for the If-Modified-Since header and return HTTP status code 304 if the pass has not changed.

Unregistering a Device

DELETE request to webServiceURL/version/devices/deviceLibraryIdentifier/registrations/passTypeIdentifier/serialNumber

Parameters

webServiceURL

The URL to your web service, as specified in the pass.

version

The protocol version. Currently, v1.

deviceLibraryIdentifier

A unique identifier that is used to identify and authenticate the device.

passTypeIdentifier

The pass’s type, as specified in the pass.

serialNumber

The unique pass identifier, as specified in the pass.

Header

The Authorization header is supplied; its value is the word “ApplePass”, followed by a space, followed by the pass’s authorization token as specified in the pass.

Response

Discussion

The server disassociates the specified device from the pass, and no longer send push notifications to this device when the pass changes.

Logging Errors

POST request to webServiceURL/version/log

Parameters

webServiceURL

The URL to your web service, as specified in the pass.

version

The protocol version. Currently, v1.

Payload

The POST payload is a JSON dictionary, containing a single key and value:

logs (string)

An array of log messages as strings.

Response

Return HTTP status 200.

Discussion

This endpoint is intended to help you debug your web service implementation. Log messages contain a description of the error in a human-readable format.