Methods

Echeyde Cubillo edited this page May 3, 2013 · 48 revisions

###Contents

We list our API methods by revision. Current are 1.0, 1.1. All APIs below support 1.0, unless otherwise noted.

Authentication

All of our API calls, except "system status" require authentication. In order to get an api private key, please contact us at help@passtools.com and we will set you up as part of the early access program.

The private key is then passed as api_key as a query string parameters for GET or a form field for PUT/POST. For instance https://api.passtools.com/v1/template/headers?api_key=yourKey where yourKey is UTF8 encoded.

API Revisioning

You can access new revisions of the API through the Api-Revision http header passed in to API calls. Its format is of type x.y where x is the API url version and y a sub-revision. For instance 1.1 is for the /v1 API and revision 1.

Revision 1.0 Changes

This represents the start of our platform and basically enables you to create, update passes as well as add locations.

Revision 1.1 Changes
  • New revision scheme whereby api revisions can be served per end point with user level passing http header.
  • New asynchronous updates for improved performance from the API client caller and better delivery.
  • Ticketing service to check on the status of asynchronous requests.
  • Updates now automatically does push as well.
  • New tags functionality whereby tags can be associated to tags and updates can be done for a given tag and and update change fields set.
  • Ability to pass an external Id during the create pass flow and look up those passes by external Id. This is based on customer requests wanting to pass us their own pass UUID in order to avoid managing the book-keeping of our passId on the client side.
  • New input JSON model for create/update passes whereby header fields are now moved into a headers json object , and accommodate for new input such as tags objects. We are starting to model a wallet more generically to soon support cross platform digital wallets.

HTTP Response Codes

  • 400 - Invalid Request Parameters : This error happens when basic input parameters check fail (such as data types mismatch..)
  • 401 - Unauthorized: The authentication check failed.
  • 406 - Not Acceptable Request: This error happens on higher level validation checks, such as required input field is missing... and a list of field level error are then returned on the JSON response as a JSONArray (see example below).
  • 429 - Too Many Requests: We throttle requests to a limited amount of API calls/sec per account in order to prevent system overloads. If you encounter this error, please reduce the concurrency. We will soon expose your account quota to let you know how many requests remain per account within a time interval.
  • 500 - Internal Server Error : Our servers encountered an error not necessarily caused by the API call.

The http response body on error code has the following JSON format:

{
  "code": 406 
  "description": "Not Acceptable Request"
  "details": "field errors"
  "fieldErrors": [ {"fieldName":"coupon_price", "message": " required field missing!"}]

}

The code is the http response code and the fieldErrors is optional.

##System Methods ###Confirm Communication /v1/system/status

URL Structure

https://api.passtools.com/v1/system/status

  • Versions 1.0
  • Method GET

###Parameters

Parameter Description
n/a No parameters required

###Returns (Sample JSON Response)

200 http response code .

{
  "Hello": "World"
}

###Return Value Definitions

Field Description
Hello Hello:World response available solely for communication/status checks

##Template Methods

The creation/editing of a template is done through the PassTools UI and with the exception of delete the Template API is read only.

  • GET /v1/template/headers to list your templates.
  • GET /v1/template/{templateId} to get the template details ( header + model ).
  • DELETE /v1/template/{templateId} delete the specified template.

###List headers of templates created by owner of API-key /v1/template/headers

URL Structure

https://api.passtools.com/v1/template/headers https://api.passtools.com/v1/template/headers?page=1&pageSize=10&order=Name&direction=ASC Get the first 10 templates sorted by template name ascending

  • Versions 1.0
  • Method GET

###Parameters

Parameter Description
page (optional) The page number you want returned. Default 1.
pageSize (optional) The number of entries per page. Default value is 10, maximum value is 100.
order (optional) The field you want the return values sorted by.
Possible Values are:
  • ID: Sort by Template ID
  • Name: Sort by Template Name
  • Created: Sort by Date that Template was Created
  • Updated: Sort by Date that Template was Last Updated
direction (optional) The Direction you want sorted values to be returned in.
Possible Values are:
  • ASC: Ascending
  • DESC: Descending

###Returns (Sample JSON Response)

{
  "Count": 9, 
  "OrderField": "ID",
  "OrderDirection": "DESC", 
  "Page": 1,
  "PageSize" : 10, 
  "templateHeaders": [
    {
      "createdAt": "2012-10-12 20:42:12.0", 
      "deleted": "False", 
      "description": "YouFit Membership Clubs", 
      "disabled": "False", 
      "id": "208", 
      "name": "TestGen", 
      "type": "Generic", 
      "updatedAt": "2012-10-12 20:42:12.0"
    }, 
    {
      "createdAt": "2012-10-12 20:41:56.0", 
      "deleted": "False", 
      "description": "YouFit Membership Clubs", 
      "disabled": "False", 
      "id": "207", 
      "name": "TestGen", 
      "type": "Generic", 
      "updatedAt": "2012-10-12 20:41:56.0"
    },
    ... 
}

###Return Value Definitions

Field Description
Count Count of Templates returned in this call
OrderField Field returned values are sorted by
OrderDirection The direction that the values are sorted in, either Ascending or Descending
page Page index
PageSize The number of entries that are included in each page
templateHeaders List of template header data dictionaries

###Get Template by ID /v1/template/{templateId}

URL Structure

https://api.passtools.com/v1/template/{templateId}

  • Versions 1.0
  • Method GET

###Parameters

Parameter Description
templateId Integer ID of desired template

###Returns (Sample JSON Response) JSON representation of requested Template

Please note that the fields Model being returned is detailed. However, the changeable fields for writes are only changeMessage, label, and value.

{
  "fieldsModel": {
    "auxiliary1": {
      "changeMessage": null, 
      "fieldType": "AUXILIARY", 
      "label": "", 
      "required": false, 
      "value": ""
    }, 
    "auxiliary2": {
      "changeMessage": null, 
      "fieldType": "AUXILIARY", 
      "label": "Seating", 
      "required": false, 
      "value": ""
    }, 
    "header1": {
      "changeMessage": null, 
      "fieldType": "HEADER", 
      "label": "Admit ", 
      "required": false, 
      "value": ""
    }, 
    "logo_text": {
      "changeMessage": null, 
      "fieldType": "TOP_LEVEL", 
      "label": "logo_text", 
      "required": false, 
      "value": "WOODSTOCK"
    }, 
    "primary1": {
      "changeMessage": null, 
      "fieldType": "PRIMARY", 
      "label": "An aquarian exposition", 
      "required": false, 
      "value": ""
    }, 
    "secondary1": {
      "changeMessage": null, 
      "fieldType": "SECONDARY", 
      "label": "", 
      "required": false, 
      "value": ""
    }, 
    "secondary2": {
      "changeMessage": null, 
      "fieldType": "SECONDARY", 
      "label": "", 
      "required": false, 
      "value": ""
    }
  }, 
  "templateHeader": {
    "createdAt": "2012-09-16 21:51:56.0", 
    "deleted": "False", 
    "description": "Woodstock", 
    "disabled": "False", 
    "id": "102", 
    "name": "Woodstock", 
    "type": "Event Ticket", 
    "updatedAt": "2012-09-16 21:51:56.0"
  }
}

###Return Value Definitions

Field Description
fieldsModel Collection of fields defined by the user as variable in the Template
templateHeader High-level descriptive data about Template

###Delete Template /v1/template/{templateId}

URL Structure

https://api.passtools.com/v1/template/888 , for example to delete templateId:888

  • Versions 1.0
  • Method DELETE

###Returns ###Return Value Definitions

templateId ID of template that was deleted
Status OK if the template was deleted

##Pass Methods

  • GET /v1/pass to list all of your passes or list by template Id.
  • GET /v1/pass/{passId} to return the details for a given pass Id.
  • GET /v1/pass/{passId}/download to return the pass as pkpass file ready for distribution.
  • GET /v1/pass/{passId}/viewJSONPass to view pass.json as per the Apple's Passbook spec. This is a utility API to help debug your passes.
  • POST /v1/pass/{templateId} to create a pass from a template
  • PUT /v1/pass/{passId} to update a pass.
  • `PUT /v1/pass/{passId}/push to push the pass updates to phones that have the pass installed.
  • DELETE /v1/pass/{passId} delete the pass specified by the pass Id parameter.
  • POST /v1/pass/{passId}/locations adds locations at the pass level
  • DELETE /v1/pass/{passId}/location deletes a location at the pass level

###List existing passes created by owner of API-key /v1/pass

URL Structure

https://api.passtools.com/v1/pass

  • Versions 1.0
  • Method GET

###Parameters

Parameter Description
page (optional) The page number you want returned. Default 1.
pageSize (optional) The number of entries per page. Default value is 10, maximum value is 100.
order (optional) The field you want the return values sorted by.
Possible Values are:
  • ID: Sort by Pass ID
  • Name: Sort by Pass Name
  • Created: Sort by Date that Pass was Created
  • Updated: Sort by Date that Pass was Last Updated
direction (optional) The Direction you want sorted values to be returned in.
Possible Values are:
  • ASC: Ascending
  • DESC: Descending
templateId (optional) Only return passes for this template id

###Returns (Sample JSON Response) List of passes

{
  "Count": 9, 
  "OrderField": "ID",
  "OrderDirection": "ASC", 
  "Page": 1,
  "PageSize": 10, 
  "Passes": [
    {
      "createdAt": "2012-10-29 14:21:19.0", 
      "id": "888", 
      "templateId": "102", 
      "url": "https://passtools-localhost.s3.amazonaws.com/a2e89eb2-7456-4037-93b8-d67557b3f00b.pkpass?Expires=1354141279&AWSAccessKeyId=AKIAIY5HQYPSTJ3DGSWQ&Signature=CzjWTclRv64YaMcQ8dDff9oIyhA%3D"
    }, 
    {
      "createdAt": "2012-10-26 15:59:53.0", 
      "id": "887", 
      "templateId": "102", 
      "url": "https://api.passtools.com/v1/pass/888/download"
    }, 
    ...
}

###Return Value Definitions

Field Description
Count Count of Passes returned in this call
OrderField Field returned values are sorted by
OrderDirection The direction that the values are sorted in, either Ascending or Descending
page Page index
PageSize The number of entries that are included in each page
Passes List of passes
  • Versions 1.1
  • Method GET

###Parameters : Same as 1.0

###Return Values : Same as 1.0


###Get Pass by ID /v1/pass/{passId}

URL Structure

https://api.passtools.com/v1/pass/{passId}
https://api.passtools.com/v1/pass/id/{id} in the event you created a pass with an external Id.

  • Versions 1.0
  • Method GET

###Parameters

Parameter Description
passId Integer ID of pass to be retrieved

###Returns (Sample JSON Response) Pass information and URL from which pkpass file can be retrieved

The representation is mostly decomposed into the pass fields , which represent the (name,value) meta-data inherited from the template, as well as the location fields, some of whom are defaulted from the template level and others are specific to the pass level, added through the location api end points.

{
   "id":"214",
   "templateId":"69",
   "passFields":{
      "header1":{
         "changeMessage":"",
         "fieldType":"HEADER",
         "value":"signature regression test",
         "label":"",
         "required":false
      }
   },
  "passLocationFields":{
      "passLevel":[
         {
            "id":67,
            "relevantText":"Hello loc 0!",
            "longitude":-122.33,
            "latitude":37.618
         }
      ],
    "templateLevel":[
         {
            "relevantText":"Hello loc 1!",
            "longitude":-124.5,
            "latitude":37.618
         }
      ]

   }


   "createdAt":"2012-10-20 18:28:11.0",
   "url":"https://api.passtools.com/v1/pass/214/download"
}
  • Versions 1.1
  • Method GET

###Parameters : same as 1.0

###Returns (Sample JSON Response)

{
   "tags":[
      {
         "id":1,
         "createdAt":2013-03-28 22:47:19.0,
         "name":"tag1"
      },
      {
         "id":2,
         "createdAt":2013-03-28 22:47:19.0,
         "name":"tag2"
      }
   ],
   "headers":{
      "barcodeAltText":{
         "changeMessage":null,
         "fieldType":"BARCODE",
         "value":"asdgfdsafhgdsh34",
         "label":"barcodeAltText",
         "required":false
      },
      "logo_color":{
         "changeMessage":null,
         "fieldType":"TOP_LEVEL",
         "value":"rgb(36,72,150)",
         "label":"logo_color",
         "required":false
      },
      "icon_image":{
         "changeMessage":null,
         "fieldType":"IMAGE",
         "value":"https:\/\/s3.amazonaws.com\/passtools_prod\/1\/images\/ad7584afb511246f71de68eb98cd5adba106f1b4_icon.png",
         "label":"icon_image",
         "required":false
      },
      "transitType":{
         "changeMessage":null,
         "fieldType":"PASS_TOP",
         "value":"PKTransitTypeAir",
         "label":"transitType",
         "required":false
      },
      "barcode_value":{
         "changeMessage":null,
         "fieldType":"BARCODE",
         "value":"asdgfdsafhgdsh34",
         "label":"barcode_value",
         "required":false
      },
      "logo_text":{
         "changeMessage":null,
         "fieldType":"TOP_LEVEL",
         "value":"Oceanic Airlines",
         "label":"logo_text",
         "required":false
      },
      "barcode_encoding":{
         "changeMessage":null,
         "fieldType":"BARCODE",
         "value":"iso-8859-1",
         "label":"barcode_encoding",
         "required":false
      },
      "logo_image":{
         "changeMessage":null,
         "fieldType":"IMAGE",
         "value":"https:\/\/s3.amazonaws.com\/passtools_prod\/1\/images\/18607511ad9245f25578977be2919c6ffd29dcb8_logo.png",
         "label":"logo_image",
         "required":false
      },
      "barcode_type":{
         "changeMessage":null,
         "fieldType":"BARCODE",
         "value":"PKBarcodeFormatPDF417",
         "label":"barcode_type",
         "required":false
      },
      "foreground_color":{
         "changeMessage":null,
         "fieldType":"TOP_LEVEL",
         "value":"rgb(19,52,105)",
         "label":"foreground_color",
         "required":false
      },
      "background_color":{
         "changeMessage":null,
         "fieldType":"TOP_LEVEL",
         "value":"rgb(61,113,204)",
         "label":"background_color",
         "required":false
      }
   },
   "id":"43",
   "templateId":"1",
   "createdAt":"2013-03-29T23:12:23.000Z",
   "serialNumber":"a74a0a35-cad5-43d9-980c-b3faa1f47b91",
   "externalId":"XYZ11111",
   "url":"https:\/\/api.passtools.com\/v1\/pass\/43\/download",
   "fields":{
      "auxiliary2":{
         "changeMessage":null,
         "fieldType":"AUXILIARY",
         "textAlignment":"PKTextAlignmentLeft",
         "value":"888",
         "label":"Flight",
         "required":false
      },
      "auxiliary3":{
         "changeMessage":null,
         "fieldType":"AUXILIARY",
         "textAlignment":"PKTextAlignmentLeft",
         "value":"First",
         "label":"Class",
         "required":false
      },
      "secondary1":{
         "changeMessage":null,
         "fieldType":"SECONDARY",
         "textAlignment":"PKTextAlignmentLeft",
         "value":"Secondary1",
         "label":"Passenger",
         "required":false
      },
      "auxiliary4":{
         "changeMessage":null,
         "fieldType":"AUXILIARY",
         "textAlignment":"PKTextAlignmentLeft",
         "value":"3\/27\/13",
         "label":"Date",
         "required":false
      },
      "secondary2":{
         "changeMessage":null,
         "fieldType":"SECONDARY",
         "textAlignment":"PKTextAlignmentLeft",
         "value":"A13",
         "label":"Seat",
         "required":false
      },
      "primary1":{
         "changeMessage":null,
         "fieldType":"PRIMARY",
         "textAlignment":"PKTextAlignmentLeft",
         "value":"Mystery",
         "label":"Sydney",
         "required":false
      },
      "auxiliary1":{
         "changeMessage":null,
         "fieldType":"AUXILIARY",
         "textAlignment":"PKTextAlignmentLeft",
         "value":"5:30PM",
         "label":"Depart",
         "required":false
      },
      "primary2":{
         "changeMessage":null,
         "fieldType":"PRIMARY",
         "textAlignment":"PKTextAlignmentLeft",
         "value":"LAX",
         "label":"Los Angeles",
         "required":false
      },
      "header1":{
         "changeMessage":null,
         "fieldType":"HEADER",
         "textAlignment":"PKTextAlignmentLeft",
         "value":"A18",
         "label":"Gate",
         "required":false
      }
   }
}

###Return Value Definitions

 <tr>
    <td>locations</td>
    <td>(JSON Array) Json Array containing locations information</td>
</tr>

<tr>
    <td>url</td>
    <td>Location from which pkpass file can be retrieved</td>
</tr>
Field Description
createAt Pass-creation date/time
id Integer pass ID
templateId Integer ID of template which was used to create pass
fields (field.key,JSON) list of field details
headers (field.key,JSON) list of header details (i.e logo_image, logo_text etc
tags (JSON Array) array of tags for the pass

###Create a new pass based on specified template

Also, you will need to set your Accept http header to be application/json. The form field for the JSON passed in object will be called json .

This critical API is supported for 1.0 and 1.1. In 1.1, tags + external Id can be added.

/v1/pass/{templateId} ###URL Structure https://api.passtools.com/v1/pass/{templateId}

  • Versions 1.0
  • Method POST

###Parameters

Parameter Description
templateId Integer ID of template to be used as basis of new pass

###Post Parameters (optional Note: parameters must be selected during template creation i.e logo_text and primary1 for following json)

{ "logo_text": { "value": "Test Value"},   "primary1":{"value":"Welcome"}}

###Returns (Sample JSON Response) ID of new pass, and URL for new pkpass file

{
  "passId": 888, 
  "templateId": 64,
  "createdAt":"2012-11-01 12:37:07.0"
  "url": "https://api.passtools.com/v1/pass/888/download"
  "passFields":{
      "header1":{
         "changeMessage":"",
         "fieldType":"HEADER",
         "value":"signature regression test",
         "label":"my value",
         "required":false
      },
      "logo_text":{
         "changeMessage":null,
         "fieldType":"TOP_LEVEL",
         "value":"Test Value",
         "label":"",
         "required":false
      },
      "primary1" {
          "changeMessage":"",
         "fieldType":"PRIMARY",
         "value":"Welcome",
         "label":"",
         "required":false

      }
}
  • Versions 1.1
  • Method POST

###URL Structure https://api.passtools.com/v1/pass/{templateId}/id/{externalId}

###Parameters

Parameter Description
templateId Integer ID of template to be used as basis of new pass
external external pass Id as string, max size of 128

###Post Parameters (optional Note: parameters must be selected during template)

 { "fields" :  { "primary1":{"value":"Welcome"}}, "headers" : { "logo_text": { "value": "Test Value"}}}

###Return Value Definitions (Same as get pass /v1/pass/{passed})

passId ID of pass
templateId Template ID of pass
createdAt Pass creation time stamp
url Location from which pkpass file can be retrieved
passFields Location from which pkpass file can be retrieved

###Returns (Sample JSON Response)

{
   "tags":[
      
   ],
   "headers":{
      "logo_color":{
         "changeMessage":null,
         "fieldType":"TOP_LEVEL",
         "value":"rgb(40,75,152)",
         "label":"logo_color",
         "required":false
      },
      "background_color":{
         "changeMessage":null,
         "fieldType":"TOP_LEVEL",
         "value":"rgb(60,100,200)",
         "label":"background_color",
         "required":false
      }
   },
   "fields":{
      "secondary1":{
         "changeMessage":null,
         "fieldType":"SECONDARY",
         "textAlignment":"PKTextAlignmentLeft",
         "value":"Secondary1",
         "label":"Passenger",
         "required":false     
   }
}

###Update an existing pass /pass/update ###URL Structure https://api.passtools.com/v1/pass/{templateId}

  • Versions 1.0
  • Method PUT

###Parameters

Parameter Description
Partial or complete pass specification record Include only parameters you wish to update in target pass. See the notes above for more information about pass specifications.

Also, you will need to set your Accept http header to be application/json. The form field for the JSON passed in object will be called json .

###Sample JSON pass update specification

{
  "backgroundColor": "rgb(31, 245, 31)", 
  "eventTicket": {
    "auxiliaryFields": [
      {
        "key": "NEW_xA_auxAkey", 
        "label": "NEW_xA_auxAlabel", 
        "value": "NEW_xA_auxAvalue"
      }, 
      {
        "key": "xB_auxBkey", 
        "label": "xB_auxBlabel", 
        "value": "xB_auxBvalue"
      } 
    ], 
    "primaryFields": [
      {
        "key": "primaryAkey", 
        "value": "primaryAValue"
      }
    ], 
    "secondaryFields": [
      {
        "key": "2A_secondaryAkey", 
        "label": "2A_secondaryAlabel", 
        "value": "2A_secondaryAvalue"
      }, 
      {
        "key": "2B_secondaryBkey", 
        "label": "NEW_2B_secondaryBlabel", 
        "value": "NEW_2B_secondaryBvalue"
      } 
    ], 
  }, 
  
}

###Returns (Sample JSON Response) Edited pass ID record

{
  "passId": 1200,
  "url":"https:\/\/localhost\/v1\/pass\/1200\/download" 
}

###Return Value Definitions

ticketId ticket id for update which will trigger Async update
  • Versions 1.1
  • Method PUT

###Parameters

Parameter Description
Partial or complete pass specification record Include only parameters you wish to update in target pass. See the notes above for more information about pass specifications.

###Sample JSON pass update specification

{
 "headers" : {"logo_text": { "value" : "Walgreen"}},
"fields" : {"secondary1" : {"value" : "Dollors Off"}},
}

###Sample JSON Return

{
   "ticketId":8029
}

###Download Pass /v1/pass/{passId}/download

URL Structure

https://api.passtools.com/v1/pass/214/download , for example to download passId:214

  • Versions 1.0, 1.1
  • Method GET

###Returns

The byte stream that can be converted into a file. Please see the SDKs for more examples.


###Delete Pass /v1/pass/{passId}

URL Structure

https://api.passtools.com/v1/pass/888 , for example to delete passId:888

  • Versions 1.0, 1.1
  • Method DELETE

###Returns ###Return Value Definitions

passId ID of pass that was deleted
Status OK if the pass was deleted

###Push to Pass /v1/pass/{passId}/push

URL Structure

https://api.passtools.com/v1/pass/888/push , for example to push pass changes to all devices that have the pass 888 installed.

  • Versions 1.0
  • Method PUT

The response will tell you how many devices the push succeeded to and how many devices could not be sent a push notification.

{
  "numberOfDevicesPushWasSentTo": 5 
  "numberOfDevicesPushFailed": 0
}

###Add Locations to Pass /v1/pass/{passId}/locations

URL Structure

https://api.passtools.com/v1/pass/888/locations , for example adds an array of new locations to the pass with ID 888.

  • Versions 1.0
  • Method POST

Please pass a JSON array in with the following data type ( we assume you will URL encode the data):

json=["
{
 "longitude":-122.374,
 "latitude":37.618,
 "relevantText":"Hello loc0",
 "streetAddress1":"address line #1",
 "streetAddress2":"address line #2",
  "city":"Palo Alto",
  "region":"CA",
  "regionCode":"94404",
   "country":"US"}
","{....}"
]

We require that

  • The (latitude,longitude) pair be set else the API will return a validation error. Other location fields are optional.
  • We limit the number of locations per pass to 10, a current limitation imposed by Apple.
  • Please note that if the pass template had locations defined from the web interface, they will be inherited to the pass at creation time as default pass locations. However, pass entered locations will take precedence over the template based locations. In other words, if you enter 10 pass locations and you had 2 template locations, the 10 pass locations will be honored.
  • We will de-duplicate your entered locations based (latitude,longitude) equality.

The response will be a JSON array returning the pass location Id(s) in which can be used to delete locations.

[
   {
      "passLocationId":65,
      "value":{
         "region":"CA",
         "regionCode":"94404",
         "relevantText":"Hello loc0!",
         "streetAddress1":"add11",
         "streetAddress2":"add22",
         "longitude":-122.3742
         "latitude":37.618,
         "city":"FC"
      }
   },
   {
      "passLocationId":66,
      "value":{
         "region":"CA",
         "regionCode":"94404",
         "relevantText":"Hello loc1!",
         "streetAddress1":"add12",
         "streetAddress2":"add23",
         "longitude":-123.374,
         "latitude":38.618,
         "city":"FC"
      }
   }
]
  • Versions 1.1
  • Method POST Please pass a JSON array in with the following data type ( we assume you will URL encode the data):
json={
 "locations" : 
  {
   [
   {
     "longitude":-122.374,
      "latitude":37.618,
      "relevantText":"Hello loc0",
      "streetAddress1":"address line #1",
      "streetAddress2":"address line #2",
      "city":"Palo Alto",
      "region":"CA",
      "regionCode":"94404",
      "country":"US"
    }
 ]
}

###Delete Location from Pass /v1/pass/{passId}/location/{locationId}

URL Structure

https://api.passtools.com/v1/pass/888/location , for example deletes a given location from the pass with ID 888.

  • Versions 1.0,1.1
  • Method DELETE

The input parameters are in the REST url structure with the passId and the locationId, returned from the POST /v1/pass/{passId}/locations endpoint.

The API will return a 200 error code is succesfull.

##Tags Methods

  • GET /v1/tag List the tags created by this API user
  • GET /v1/tag/{tag}/passes List the passes on a tag
  • PUT /v1/tag/{tag}/passes Update all passes on the tag
  • DELETE /v1/tag/{tag} Delete the specified tag and untag all passes
  • DELETE /v1/tag/{tag}/passes Untag all passes from this tag
  • DELETE /v1/tag/{tag}/pass/{passId} Untag the specified pass

###List existing tags created by owner of API-key /v1/tag

URL Structure

https://api.passtools.com/v1/tag

  • Versions 1.1
  • Method GET

###Parameters

Parameter Description
page (optional) The page number you want returned. Default 1.
pageSize (optional) The number of entries per page. Default value is 10, maximum value is 100.
order (optional) The field you want the return values sorted by.
Possible Values are:
  • ID: Sort by Tag ID
  • Name: Sort by Tag Name
  • Created: Sort by Date that Tag was Created
direction (optional) The Direction you want sorted values to be returned in.
Possible Values are:
  • ASC: Ascending
  • DESC: Descending

###Returns (Sample JSON Response) List of tags

{
   "tags":[
      {
         "id":2,
         "tag":"Gold"
      },
      {
         "id":3,
         "tag":"Silver"
      },
      {
         "id":4,
         "tag":"Platinum"
      },
      {
         "id":5,
         "tag":"Enterprise"
      }
   ],
   "Pagination":{
      "order":"ID",
      "page":1,
      "start":0,
      "direction":"DESC",
      "pageSize":10
   },
   "count":4
}

###Return Value Definitions

Field Description
Count Count of Tags returned in this call
OrderField Field returned values are sorted by
OrderDirection The direction that the values are sorted in, either Ascending or Descending
page Page index
PageSize The number of entries that are included in each page
Tags List of Tags

###List Passes Associated to the Specified Tag /v1/tag/{tag}/passes

URL Structure

https://api.passtools.com/v1/tag/GOLD/passes

  • Versions 1.1
  • Method GET

###Parameters

Parameter Description
tag The tag you want the passes on.
page (optional) The page number you want returned. Default 1.
pageSize (optional) The number of entries per page. Default value is 10, maximum value is 100.
order (optional) The field you want the return values sorted by.
Possible Values are:
  • ID: Sort by Tag ID
  • Name: Sort by Tag Name
  • Created: Sort by Date that Tag was Created
direction (optional) The Direction you want sorted values to be returned in.
Possible Values are:
  • ASC: Ascending
  • DESC: Descending

###Returns (Sample JSON Response) List of passes

{
   "count":3,
   "Pagination":{
      "order":"ID",
      "page":1,
      "start":0,
      "direction":"DESC",
      "pageSize":10
   },
   "passes":[
      {
         "id":2827
      },
      {
         "id":2828
      },
      {
         "id":2829
      }
   ]
}

###Return Value Definitions

Field Description
Count Count of Tags returned in this call
OrderField Field returned values are sorted by
OrderDirection The direction that the values are sorted in, either Ascending or Descending
page Page index
PageSize The number of entries that are included in each page
passes List of Pass Ids associated with this tag.

###Update the Passes on the Specified Tag /v1/tag/{tag}/passes

URL Structure

https://api.passtools.com/v1/tag/GOLD/passes

  • Versions 1.1
  • Method PUT

###Parameters

Parameter Description
tag The tag you want to update the passes on.

###Input (Sample JSON Input) List of tags

{
    "fields":{
        "secondary1":{
            "value":"12/31/2013"
        },
        "primary1":{
            "value":"$2 Off"
        }
    }
}

###Returns (Sample JSON Response) List of tags

{
   "ticketId":732
}

###Return Value Definitions

Field Description
ticketId Ticket ID that can be used to poll the status of the update

###Delete the Specified Tag /v1/tag/{tag}

URL Structure

https://api.passtools.com/v1/tag/GOLD

  • Versions 1.1
  • Method DELETE

###Parameters

Parameter Description
tag The tag you want to delete.

###Returns (Sample JSON Response)

{
    "status":"success",
    "tagId":5,
    "count":93
}

###Return Value Definitions

Field Description
status the status of the operation.
tagId ID of the tag that was deleted.
count The number of passes that were removed from the tag.

###Remove all passes from a tag /v1/tag/{tag}/passes

URL Structure

https://api.passtools.com/v1/tag/GOLD/passes

  • Versions 1.1
  • Method DELETE

###Parameters

Parameter Description
tag The tag you want to remove the passes from.

###Returns (Sample JSON Response)

{
    "status":"success",
    "tagId":5
}

###Return Value Definitions

Field Description
status the status of the operation.
tagId ID of the tag that the passes were removed from.

###Remove a pass from a tag /v1/tag/{tag}/pass/{passId}

URL Structure

https://api.passtools.com/v1/tag/GOLD/pass/123

  • Versions 1.1
  • Method DELETE

###Parameters

Parameter Description
tag The tag you want to remove the pass from.
passId pass you want to remove from the tag.

###Returns (Sample JSON Response)

{
    "status":"success",
    "tagId":5
}

###Return Value Definitions

Field Description
status the status of the operation.
tagId ID of the tag that the passes were removed from.

##Ticketing Methods


###Get the status of a ticket /v1/ticket/{ticketId}

URL Structure

https://api.passtools.com/v1/ticket/123

  • Versions 1.1
  • Method GET

###Parameters

Parameter Description
ticketId The ticket you want the status of.

###Returns (Sample JSON Response)

{
    "Status":"COMPLETED",
    "createdAt":2013-03-28 18:18:36.0,
    "ID":123,
    "children":{
        ...
    }
}

###Return Value Definitions

Field Description
status the status of the ticket.
createdAt The time that the ticket was created.
ID ID of the ticket.
children Children that were spawned to support this ticket and their status.

##Debug Methods

###Displays the pass.json content created by owner of API-key

URL Structure

https://api.passtools.com/v1/pass/{passId}/viewJSONPass

  • Versions 1.0
  • Method GET

This will return the content of what you would see inside the pass.json if you were to unzip your Passbook pkpass file.

Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.