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 |
| 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.