API Documentation
Rest API
WalletKit SDK for Python, Java and Ruby is live!

Creating a Pass model

A Pass template is a one time creation for defining looks and default values of a pass. A Pass template can be created by sending a http POST request to https://api.walletkit.com/v1/passes

Headers

The request headers are content-type, brand-id and api-key. Content-Type should be set as application/json. Your brand-id and api-key can be found at settings page.


        -H "brand-id: <Your brand-id>"  \
        -H "api-key:  <Your api-key> "  \
        -H "Content-Type: application/json"  \
    		

json POST data

The json key and value to be sent with the POST request is documented in the table below.

json data
Keys Value Description Type Required
description Description of the pass Hidden value String YES
pass_type boardingPass
coupon
eventTicket
storeCard
generic
Passes of each pass type has specific number of fields,layout of fields and nature of images allowed.

The visual design and layout changes for each pass type.
String YES
transittype PKTransitTypeAir
PKTransitTypeTrain
PKTransitTypeBus
PKTransitTypeBoat
PKTransitTypeGeneric
Type of transit String Required for boarding passes; otherwise not allowed
icon, background, logo, thumbnail,icon Image URL You just need to send the public URL of the image. We download the image and store it in our server String icon image is Required.
Other images are optional
icon2x, background2x, logo2x, thumbnail2x,strip2x Image URL Retina ready images String Optional
logotext Brand name Text near the logo indicating brand name String Optional
username Organization name which shows in the iOS 6 mail UI when users see the pass if not present, the username given when signing up will be used String Optional
relevant_date Date and time when the pass becomes relevant For example, the start time of a movie ISO 8601 date, as a string
You can generate an ISO 8601 date here
Optional
foreground_color, background_color, label_color The color which sets the visual design of the pass The foreground_color sets the color of values displayed on the pass.
Likewise background_color and label_color sets the background color and label color respectively
RGB value as string. Eg: rgb(218,212,212) Optional
barcode json dictionary with keys format, message, messageEncoding , alttext format - Barcode format. Must be one of the following values: PKBarcodeFormatQR, PKBarcodeFormatPDF417, PKBarcodeFormatAztec, PKBarcodeFormatText.

message - Message or payload to be displayed as a barcode

messageEncoding - Text encoding that is used to convert the message from the string representation to a data representation to render the barcode. The value is typically iso-8859-1, but you may use another encoding that is supported by your barcode scanner and software.

alttext - Text displayed near the barcode. For example, a human-readable version of the barcode data in case the barcode doesn't scan
String(for messageEncoding, IANA character set name as String) Optional. but if barcode is present format, message, messageEncoding is required
location Array of json dictionaries with values for keys latitude, longitude, altitude , relevanttext latitude, longitude, altitude - latitude, longitude and altitude of the location

relevanttext - Description of the location. Eg: first shop on the fourth street
double(latitude, longitude, altitude) String(relevanttext) Optional. But if location is present: latitude, longitude are required
headerFields, primaryFields, secondaryFields, auxiliaryFields , backFields Array of json dictionaries with values for keys label, key, value , textalignment ,changemessage key - The key must be unique within the scope of the entire pass. For example, "departure-gate"

label - Label text for the field

value - Default value of the field. Values can be substituted when sending individual passes

textalignment - Alignment for the field's contents. Must be one of the following values: PKTextAlignmentLeft, PKTextAlignmentCenter, PKTextAlignmentRight, PKTextAlignmentJustified, PKTextAlignment- Natural

changemessage- Optional. Format string for the alert text that is displayed when the pass is updated. The format string may contain the escape %@, which is replaced with the field's new value. For example, "Gate changed to %@."If you don't specify a change message, the user isn't notified when the field changes
String(localizable string, ISO 8601 date as a string, or number for value) Optional. but if present: key, value are required
f

Example curl request :


    curl -X POST  \
        -H "<Your brand-id>"  \
        -H "<Your api-key>" \
        -H "Content-Type: application/json"  \
        -d '{
            "logotext" : "Brand name" , 
            "background" : "http://www.example.com/yourBackground.png", 
            "description" : "Description of the pass" , 
            "icon" : "http://www.example.com/yourIcon.png" , 
            "icon2x" : "http://www.example.com/iconx.png" ,
            "barcode" : { 
                    "message" : "123456789" ,
                    "format" : "PKBarcodeFormatPDF417" ,
                    "messageEncoding" : "iso-8859-1" ,
            "alttext" : "test"
            } ,
            "pass_type" : "coupon" ,
            "username" : "testbrand" ,
            "relevant_date" : "2012-07-22T14:25-08:00" ,
            "foreground_color" : "rgb(0,0,0)" ,
            "background_color" : "rgb(218,212,212)" ,
            "label_color" : "rgb(254,254,255)" ,
            "primaryFields" : [
                        { 
                        "key" : "key1" ,
                        "value" : "values" ,
                        "label" : "label" 
                        }
                        ] 
            }' \
    https://api.walletkit.com/v1/passes

    

Response :

Returns response with status 200 and json data with id of the template. You should store this id for delivering individual passes


    
        {
            "id" : "<pass temaplate id >" , 
            "description" : "Description of the pass" , 
        } 
         
	

Listing all Passes

You may want to retrieve the id of the pass templates you have created. You can list the pass templates created by sending a http GET request to https://api.walletkit.com/v1/passes.

Headers

The request headers are Content-Type, brand-id and api-key. Your brand-id and api-key can be found at accounts page.


        -H "brand-id: <Your brand-id>"  \
        -H "api-key:  <Your api-key> "  \
    

Example curl request :


    curl -X GET  \
        -H "brand-id: <Your brand-id>"  \
        -H "api-key: <Your api-key>" \
    https://api.walletkit.com/v1/passes

    

Response

Returns response with status 200 and json array containing id and description of all the Pass templates you have created


    
        [
        {
            "id" : "<pass temaplate id >" , 
            "description" : "Description of the pass" , 
        }.
        {
            "id" : "<pass temaplate id >" , 
            "description" : "Description of the pass" , 
        }
        ] 
         

    

Creating an individual pass

An individual Pass for your users (based on a Pass template you have created) can be sent or generated by sending a http POST request to https://api.walletkit.com/v1/passes/<template_id>. template_id is the id for the template pass you create manually or through our API. You can send values for the template pass by sending the key and value to be changed for the field.

Headers

The request headers are Content-Type, brand-id and api-key. Content-Type should be set as application/json. Your brand-id and api-key can be found at accounts page.


        -H "brand-id: <Your brand-id>"  \
        -H "api-key:  <Your api-key> "  \
        -H "Content-Type: application/json"  \
    

json POST data

The json key and value to be send with the POST request is documented in the table below.

json data
Keys Value Description Type Required
keys Key named 'keys' with array of json dictionaries containing attributes: key, value You just need to provide the key and value pair so that a pass will be created by finding the key from the template and replacing the value for it
String for key and value can be String or Numeric Optional
location Key named 'location' with array of json dictionaries containing attributes: latitude, latitude, altitude , relevanttext latitude, longitude, altitude - latitude, longitude and altitude of the location. Each has a key in all the json dictionary of the Array

relevanttext - Description of the location. Eg: first street on the fourth street

Note: Max only 10 locations are allowed per Pass.The numebr of locations you send combined with the locations for this pass tempalte should not exceed 10. if it does, the API will return an error message
double(latitude, longitude, altitude) String(relevanttext) Optional. but if location is present: latitude, latitude are required
barcode_message Message to be included in the barcode Barcode message for pass String Optional.Works only if the barcode format and message encoding is set in the template
barcode_alttext Text displayed near the barcode. For example, a human-readable version of the barcode data in case the barcode doesn't scan String Optional.Works only if the barcode format and message encoding is set in the template
sms Valid mobile phone number to deliver the pass with country code. Eg:+16505555555 The link to download the pass is sent to the provided mobile number String Optional
email Valid email address to deliver the pass The link to download the pass is sent to the provided email address String Optional
emailsubject Subject of the email Works only if email is provided String Optional.If not specified, a default subject is used
emailbody Body of the email Works only if email is provided String Optional.If not specified, a default emailbody is used
emailname Name of the user receiving the email Works only if email is provided String Optional.If not specified, name is not used
icon, background, logo, thumbnail,strip,icon2x, background2x, logo2x, thumbnail2x,strip2x Image URL If specified, it will replace the image from the template for this particular pass String Optional.If not specified, it will use the default images from the template

Example curl request :


    curl -X POST  \
        -H "<Your brand-id>"  \
        -H "<Your api-key>" \
        -H "Content-Type: application/json"  \
        -d '{
             "keys" :[{ 
                        "key" : "Destination" ,
                        "value" : "SFO" ,
                        },
                        {
                        "key" : "Departure" ,
                        "value" : "Chennai,India" ,
                        }],
            "sms"  : "+16505555555",
            "location" :[{ 
                        "latittude" : 90 ,
                        "longitude" : 90
                        }
                        ]
                }' \
    https://api.walletkit.com/v1/passes/<template id>
	

Response :

Returns response with status 200 and json data with details of the sent pass. You can attach the .pkpass file from the url and email to your users or send the link to them


    
        {
            "url" : htps://s3.amazonaws.com/passes.pkpass/"<serial no>".pkpass , 
            "description" : "Description of the pass" , 
             "sent_pass" :{ 
                        "authentication_token" : "<secure auth token>" ,
                        "serial_no" : "<serial no>" ,
                        "createddate" : "",
                          "short_url"  : "<short url to download the pass>",
                          "email_info" : "<Boolean>"
                         }
         } 
         

    

Listing Pass template

You may want to retrieve all the fields of the pass template you have created. You can list a pass template created by sending a http GET request to https://api.walletkit.com/v1/passes/<template_id>.

Headers

The request headers are brand-id and api-keyYour brand-id and api-key can be found at accounts page.


        -H "brand-id: <Your brand-id>"  \
        -H "api-key:  <Your api-key> "  \
    

Example curl request :


    curl -X GET  \
        -H "brand-id: <Your brand-id>"  \
        -H "api-key: <Your api-key>" \
    https://api.walletkit.com/v1/passes/<template_id>

    

Response

Returns response with status 200 and json array containing details of the Pass template you have requested for. it returns all the fields and data associated with the Pass template

Deleting a Pass template

You can delete a pass template by sending a delete http DELETE request to https://api.walletkit.com/v1/passes/<template_id>

Headers

The request headers are brand-id and api-keyYour brand-id and api-key can be found at accounts page.


        -H "brand-id: <Your brand-id>"  \
        -H "api-key:  <Your api-key> "  \
    

Example curl request :


    curl -X DELETE  \
        -H "brand-id: <Your brand-id>"  \
        -H "api-key: <Your api-key>" \
    https://api.walletkit.com/v1/passes/<template_id>
	

Updating a Pass

You can filter list of individual active passes you have sent by its key and values. You can send the key and value of the pass template to be filtered by by making a http PUT request to https://api.walletkit.com/v1/passes/<template_id> . template_id is the id for the template pass you create manually or through our API.

Headers

The request headers are Content-Type, brand-id and api-key. Content-Type should be set as application/json. Your brand-id and api-key can be found at accounts page.


        -H "brand-id: <Your brand-id>"  \
        -H "api-key:  <Your api-key> "  \
        -H "Content-Type: application/json"  \
    

json POST data

The json key and value to be send with the POST request is documented in the table below.

json data
Keys Value Description Type Required
keys Key named 'keys' with array of json dictionaries containing attributes: key, value and Key named 'updatekeys' with array of json dictionaries containing attributes: key, value.updatekey will update the value mentioned for the keys in updatekeys You need to provide the key and value pair so that passes will be filtered based on the key and value. eg:filtering all the passes for key flight no with a value and updating the gate no key.

See example below the table to make sense of it
String for key and value can be String or Numeric Optional
updatekeys Array of json dictionaries containing attributes: key, value.It will update the value mentioned for the keys Ex:filter passes with flight-no:1367 and update key boarding-gate to 42 String for key and value can be String or Numeric Optional

Example curl request :


    curl -X PUT  \
        -H "<Your brand-id>"  \
        -H "<Your api-key>" \
        -H "Content-Type: application/json"  \
        -d '{
             "id" : "<pass temaplate id >" , 
            "description" : "Description of the pass" , 
             "keys" :[{ 
                        "key" : "Destination" ,
                        "value" : "SFO" ,
                        },
                        {
                        "key" : "Departure" ,
                        "value" : "Chennai,India" ,
                        }]
             "updatekeys" :[
                        {
                        "key" : "Departure" ,
                        "value" : "Mumbai,India" ,
                        }]
                
            }' \
    https://api.walletkit.com/v1/passes/<template id>

    

Response

Returns response with status 200 and json data with details of the sent pass. You can attach the .pkpass file from the url and email to your users or send the link to them


    
        {
            "url" : htps://s3.amazonaws.com/passes.pkpass/"<serial no>".pkpass , 
            "description" : "Description of the pass" , 
             "sent_pass" :{ 
                        "authentication_token" : "<secure auth token>" ,
                        "serial_no" : "<serial no>" ,
                        "createddate" : ""
                         }
         } 
         
	

Update Location of an Individual Pass

You can update an individual pass by sending a http POST request to https://api.walletkit.com/v1/passes/<template id>?sno=<serial no> along with the serial number of the pass to be updated. Serial number is returned when a pass is created. You have to store the serial number in order to make this call.

Example curl request :


    curl -X POST  \
        -H "<Your brand-id>"  \
        -H "<Your api-key>" \
        -H "Content-Type: application/json"  \
        -d '{
            "location_reset" : <Boolean> , 
            "location" : [
                        { 
                        "latitude" : 80 ,
                        "longitude" : 80 
                        },
                        { 
                        "latitude" : 70 ,
                        "longitude" : 70 
                        }
                        ] 
            }' \
    https://api.walletkit.com/v1/passes/<Template id>?sno=<Serial No>

    

If location_reset is true, previous locations in the pass is removed and the pass is updated with the new locations given. if it is false, new locations are added to the existing locations.

The following layout describes how a boarding pass will be displayed.

Boarding Pass

The following layout describes how a boarding pass will be displayed.

Supported Images

logo, icon and footer

Fields

Header Fields - upto 3 fields allowed

Primary Fields - upto 2 fields allowed

Secondary Fields - upto 4 fields allowed

Auxiliary Fields - upto 5 fields allowed

Layout

Event Tickets

The following layout describes how an event ticket pass will be displayed.

Supported Images

logo, icon, strip, background, thumbnail. If you specify a strip image, do not specify a background image or a thumbnail.

Fields

Header Fields - upto 3 fields allowed

Primary Fields - only 1 field allowed

Secondary Fields - upto 4 fields allowed

Auxiliary Fields - upto 4 fields allowed

Layout Type 1

Layout Type 2

Store Card

The following layout describes how a store card pass will be displayed.

Supported Images

logo, icon, strip

Fields

Header Fields - upto 3 fields allowed

Primary Fields - only 1 field allowed

Secondary Fields and Auxiliary Fields - upto a total of up to four secondary and auxiliary fields, combined.

Coupon

The following layout describes how a coupon pass will be displayed. Maximum four secodaryField/auxiliaryField combined.

Supported Images

logo, icon, strip

Fields

Header Fields - upto 3 fields allowed

Primary Fields - only 1 field allowed

Secondary Fields and Auxiliary Fields - upto a total of up to four secondary and auxiliary fields, combined.

Generic

The following layout describes how a generic pass will be displayed.

Supported Images

logo, icon, thumbnail

Fields

Header Fields - upto 3 fields allowed

Primary Fields - only 1 field allowed

Secondary Fields and Auxiliary Fields - upto a total of up to four secondary and auxiliary fields, combined.

Layout Type 1

Layout Type 2

Images

Specifications for images in the pass.

Background

Size - 180x220.The image is cropped slightly on all sides and blurred.

Icon

Size- 58 x 58 . The icon is displayed when a pass is shown on the lock screen and by apps such as Mail when showing a pass attached to an email.

Logo

Size- 160x50 points. The logo image is displayed in the top left corner of the pass, next to the logo text.

Strip

The allotted space is 312x84 points for event tickets, 312x110 points for other pass styles with a square barcode, and 312x123 in all other cases

Thumbnail

Size - 90x90 points. The aspect ratio should be in the range of 2:3 to 3:2, otherwise the image is cropped.