Passcreator API Documentation

(1)

Passcreator API

Documentation

(2)

About this Document

3 Obtaining an API key

3 Authentication 3

Testing 3

Get list of pass-templates

4 Get information about a pass-template 4

Get all passes of a pass-template 5

Check if a pass is known to a given ID 6

Get information about a specific pass

7 Create a new pass 7

Update a pass 8

Mark a pass as voided 9

(3)

About this Document

This document describes the REST API that can be used if you or one of your customers has a valid account for the online app that is available at www.passcreator.de.

In general a REST API means that you always have to provide a authentication token in the authorization header of every HTTP-Request.

The API provides functions to create, read, update and delete Passbook passes. Additionally there are functions to get a list of pass-templates and existing passes.

In order to use the API features a pass-template must be created using the Passcreator on-line app. Creating and updating pass-templates is currently not supported via the API. This documentation is provided as is without any warranty. If you notice that any of the func-tions or methods don’t work as expected or find something that is not described clearly en-ough please send us an e-mail to [email protected].

Also this document might be subject to change as we are constantly adding new features to Passcreator. If you want to get notified about changes to the API please also write us an E-Mail to [email protected] and we’ll add you to a recipient list that is notified as soon as a new version of the documentation is available.

Obtaining an API key

The API key must be submitted in the HTTP Authorization header on every request. It is used to check if the caller is authorized to execute the function.

To get the API key log in to Passcreator (https://portal.passcreator.de/login) and go to „Account Options“. You can find the API key at the bottom of the page.

Authentication

To authorize your request you must always submit the API key in the HTTP Authorization header.

Testing

If you want to test the API or learn how it works a good way to get used to it without having to code much is installing a browser plugin like Postman (http://www.getpostman.com/) for Google Chrome. It allows you to test all Passcreator API functions so you can get an idea of how it works.

If API functions need complex data this data must be submitted as JSON payload. Also the API functions will return information about the executed steps like IDs of created passes or error messages as JSON arrays.

In general the Passcreator API will always return the appropriate HTTP-statuses e.g.: • 200 - Request was valid and the results are being returned.

(4)

Get list of pass-templates

URL: https://portal.passcreator.de/api/pass-template

HTTP-Method: GET

Purpose: Returns a list of all pass-templates that have been created for your account. Required input parameters:

•

HTTP Authorization Header that contains your API key

Returned values: JSON-Array containing the UID and the name of your pass-templates. Example output:

Get information about a pass-template

URL: https://portal.passcreator.de/api/pass-template/<pass-uid>

HTTP-Method: GET

Purpose: Get information about the given pass-template. This information is e.g. needed if

you want to create passes for this pass-template.

Required input parameters:

•

UID of the pass-template that must be specified in the URI. If you don’t have a UID you can obtain it by using the function explained in the section „Get list of pass-tem-plates“.

Returned values: JSON-Array containing the following values: • identifier: the UID of the pass-template

• name: the name of the pass-template

• numberOfCreatedPasses: the number of created passes for this pass-template.

Pay attention that this is the overall number of passes that have been created, not the number of passes created this month.

• createPassUrl: the API url including the pass-template UID that must be used to

create new passes.

• dynamicFields: JSON-Array that specifies the array that must be submitted when

passes are created or updated. For more details see „Create a new pass“ in this do-cument.

(5)

Example output:

Get all passes of a pass-template

URL: https://portal.passcreator.de/api/pass/?passId=<pass-template-uid> HTTP-Method: GET

Purpose: Returns a list of all passes for the given pass-template. Required input parameters:

•

pass-template UID as GET parameter with the parameter name passId.

Returned values: JSON-Array containing an array for every pass. The array for the passes

contain these fields:

• identifier: the UID of the pass that can be used e.g. for updates. • uri: the URI of the pass that can be used to update or delete it.

• generatedId: the unique ID that is created for every pass and can e.g. be used for admittance tools to check if a given ID is valid. This ID is usually encoded in the Bar-code on the pass if you’re not using own IDs.

• voided: false, if the pass is not voided, means it has not been used. true, if the pass is voided, means it has been used already.

• searchString: contains all data on the pass separated by pipe symbols |

(6)

Check if a pass is known to a given ID

URL: https://portal.passcreator.de/api/pass/checkbyid/<id-to-check-for> HTTP-Method: GET

Purpose: Checks if a pass is found for the given ID. This function can e.g. be used to check

if a pass that is shown on admittance of a event is valid. To use this it is required that the ID is encoded in the passes’ barcode. Currently only IDs that are automatically generated by Passcreator can be checked.

•

ID that should be checked for

Returned values: JSON-Array containing the following information:

• error: if an error occurred it is specified here. If the field is empty, no error occurred. • identifier: the UID of the pass that has the given ID.

• uri: the URI you can use to update or delete the pass.

• generatedId: the ID (this is the one that was given in the request)

• searchString: all data that is shown on the pass’ front or back. Fields are separated

by pipe symbols.

• voided: if true, the pass is voided. This means it has already been used.

• passTemplateGuid: the GUID of the pass-template that was used to create the

pass.

Example output:

(7)

Get information about a specific pass

URL: https://portal.passcreator.de/api/pass/<pass-uid> HTTP-Method: GET

Purpose: If the given pass UID is known information about the pass is returned. Required input parameters:

•

UID of the pass you want information about

Returned values: JSON-Array containing the following information: • identifier: the UID of the pass that has the given ID.

• uri: the URI you can use to update or delete the pass.

• generatedId: the generated ID that is used e.g. in the barcode.

• searchString: all data that is shown on the pass’ front or back. Fields are separated

by pipe symbols.

• voided: if true, the pass is voided. This means it has already been used.

• passTemplateGuid: the GUID of the pass-template that was used to create the

pass.

Example output:

Create a new pass

URL: https://portal.passcreator.de/api/pass?passtemplate=<pass-template-guid> HTTP-Method: POST

Purpose: Create a new pass using the given pass template. Required input parameters:

•

(8)

•

An array containing the values that should be shown on the pass as specified by the method that describes a pass template. See „Get information about a pass-template“ in this document. The JSON-Array must be submitted as payload of the request. An example JSON array looks like this:

Returned values: JSON-Array containing the following information: • identifier: the unique identifier of the created pass

• uri: the URI that can be used to update or delete the pass

• linkToPassFile: the link where the pkpass-file can be downloaded. The pkpass-file is

the actual pass that can be opened on iPhones directly.

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

• ErrorMessage: if an error occurs it is shown here. Example output:

Update a pass

URL: https://portal.passcreator.de/api/pass/<pass-guid> HTTP-Method: PUT

Purpose: Update an existing pass. Required input parameters:

•

ID of the pass that must be updated in the URI.

•

An array containing the values that should be shown on the pass as specified by the method that describes a pass template. See „Get information about a pass-template“ in this document. The JSON-Array must be submitted as payload of the request. An example JSON array looks like this:

(9)

Returned values:

If the pass has been updated successfully HTTP Status 204 is returned.

Mark a pass as voided

URL: https://portal.passcreator.de/api/pass/<pass-guid>?passInstance[voided]=boolean HTTP-Method: PUT

Purpose: Mark a pass voided or not. This is e.g. useful, if an event ticket has been used. If a

pass is voided the barcode that is shown on the pass will be greyed out on the users’ device.

•

ID of the pass that must be voided in the URI.

•

Boolean (true or false) that indicates if the pass should be voided or not. If the pass should be voided, the boolean must be true, if it should not be voided the boolean parameter must be false. The passInstance[voided] parameter is also specified in the URI.

Returned values: