Create, Update a Pass - Passcreator API Documentation

POST/api/v3/pass

Bulk Update Passes

Updates multiple existing passes.

A POST request will replace existing data with the provided data.
Data not provided will get deleted from passes.

A PATCH request will update only the provided data.

Supported URL parameters

Example URLs

Request URL without parameter

https://app.passcreator.com/api/v3/pass/bulk

Authorization

For authorization you need to add a HTTP header to your request:

Name
Authorization
Type
string
(mandatory)
Description
HTTP Header that contains your API key.

Example HTTP Header

HTTP header with authorization

    PATCH /api/v3/pass/bulk HTTP/1.1
    Host: app.passcreator.com
    Authorization: yourApiKeyHere
    Content-Type: application/json
    ...

Request Body

The following properties of the data object can be submitted in the request body:

Name
userProvidedId
Type
string
(optional)
Description
Can be used as identifier (should be unique).
Name
enforceUniqueUserProvidedId
Type
boolean
(optional)
Description
If set to true, the endpoint will return status 400 if you specify a userProvidedId that is already used within your account.
Name
barcodeValue
Type
string
(optional)
Description
Will be used as barcode value.
Name
groupingIdentifier
Type
string
(optional)
Description
A value that is used to group passes. If a grouping identifier is specified, passes with the same style, pass type identifier, and grouping identifier are displayed as a group.
Only valid for event tickets and boarding passes.
Will be ignored when it is submitted for other passes.
In order to have this value respected, you need to enable the corresponding option on your pass template (tab general --> extended options --> ask for grouping identifier on pass creation (TODO: adapt for new UI)).
Name
urlToThumbnail
Type
string
(optional)
Description
If your template is using a different thumbnail per pass, you can pass a URL to a valid image here. It will then be used on the pass that is about to be created.
Name
urlToBackground
Type
string
(optional)
Description
If your template is using a different background image per pass you can pass a URL to a valid image here. It will then be used on the pass that is about to be created.
Name
urlToLogo
Type
string
(optional)
Description
If your template is using a different logo image per pass you can pass a URL to a valid image here. It will then be used on the pass that is about to be created.
Name
expirationDate
Type
string
(optional)
Description
If your template is using a different expiration date per pass you can specify this date here in the format Y-m-d H:i.
Name
relevantDate
Type
string
(optional)
Description
If your template is using a different relevant date per pass you can specify this date here in the format Y-m-d H:i. It's the date when the pass shows up on the lock screen.
Name
labelColor
Type
string
(optional)
Description
If your template is using a different label color per pass you can specify a valid hexadecimal color here. Invalid values will be dropped and the default color is used.
Name
foregroundColor
Type
string
(optional)
Description
If your template is using a different foreground color (the color that field values have) per pass you can specify a valid hexadecimal color here. Invalid values will be dropped and the default color is used.
Name
backgroundColor
Type
string
(optional)
Description
If your template is using a different background color per pass you can specify a valid hexadecimal color here. Invalid values will be dropped and the default color is used.
Name
emailRecipient
Type
string
(optional)
Description
If you've selected an email template in the sendout settings of your pass template, you can include an email address here and Passcreator will automatically send the pass via email to the address you've specified.
Name
phoneRecipient
Type
string
(optional)
Description
If you've specified an SMS text in the sendout settings of your pass template, you can include a phone number here and Passcreator will automatically send the pass via SMS to the number you've specified.
Name
locations
Type
array<object>
(optional)
Description
latitude and longitude must contain valid values. relevantText is an optional description for the push notification that is shown. If you want to localize the relevantText, specify a localizedRelevantText object with the language code as key and the text as value. You can also specify an altitude and the maxDistance which defines the number of meters around the coordinate where the notification will be shown.
Name
storedValue
Type
float
(optional)
Description
A value that reflects the pass value. This can e.g. be a monetary value of a gift card, the number of stamps of a stamp card or the number of points of a loyalty campaign. If you have configured a pass functionality for the template of the pass, additional actions like a change of the loyalty tier might be triggered by increasing or decreasing the stored value.
Name
eligibleValidationPlaces
Type
array<string>
(optional)
Description
Places where this ticket is valid. This is applied when an app scan is used and an app configuration ID is given when requesting info about a pass. The given values have to be part of the validValidationPlaces array of the template. Otherwise, HTTP status 400 will be returned.
Name
downloadPin
Type
string
(optional)
Description
A PIN that users have to enter before being able to download a pass. Please note that you need to enable the PIN feature on a template level before the PIN verification will be shown.
Name
bundleId
Type
string
(optional)
Description
Passes with the same bundleId will be bundled together and can be downloaded with one download link.
Name
localizedBackgroundImages
Type
object
(optional)
Description
If you have enabled different background images for each pass for your template and are using translations for the template, you can specify different images per language. Use the language code as key and the URL to the image as the value.

In addition to the data property object you can specify a filter property that the request should apply to. You can either use an array of identifiers, a segment identifier or a query (see Query Language)

Name
identifiers
Type
array<string>
(optional)
Description
You can specify a list of identifiers of passes you want to update.
Name
segmentId
Type
string
(optional)
Description
If you saved a segment in Passcreator, you can use the segment identifier to update all passes of this segment.
Name
query
Type
object
(optional)
Description
You can specify a segment using the Passcreator Query Language.

Example Request

Request body

{
    "data": {
        "expirationDate": "2055-12-31 00:00"
    },
    "filter": {
      "query": {
        "templateId": "2d1b5f7f-26df-41c6-980f-ed0709f1170d",
        "groups": [
          [
            {
              "field": "firstname",
              "operator": "contains",
              "value": ["David", "Ray", "Timo"]
            },
            {
              "field": "country",
              "operator": "equals",
              "value": ["Germany"]
            },
            {
              "field": "age",
              "operator": "greaterThan",
              "value": [60]
            }
          ],
          [
            {
              "field": "firstname",
              "operator": "contains",
              "value": ["Alex", "Marc"]
            },
            {
              "field": "country",
              "operator": "equals",
              "value": ["Spain"]
            }
          ]
        ]
      }
    }
}

Returned values

This endpoint will return a 202 success status code. Processing will be asynchronously. To review the process you can use the returned process url (Authorization through API key needed).

The following values will be returned in the data object:

Name
process
Type
string
(mandatory)
Description
URL to the process endpoint where you can track the progress of this bulk operation. See Process Tracking for details on how to poll this endpoint and interpret the results.

Example Response

Response

{
    "success": true,
    "description": "Queued successfully",
    "errors": [],
    "data": {
        "process": "https://app.passcreator.com/api/v3/process/627d21f7-e1a0-4085-84cb-130906cd097c"
    },
    "statusCode": 202,
    "count": 12
}

GET/api/v3/pass

List / Search Passes

Lists passes in chunks defined by pageSize.
If a query is provided, a search filter will be applied.

You can specify a filter that the request should apply to. You can either use an array of identifiers, a segment identifier or a query (see Query Language) If no filter is provided all passes will be returned. If the number of results exceeds the defined pageSize a link to the next page is provided in the page object under the next key.

Supported URL parameters

Name
pageSize
Type
integer
(optional)
Description
Default: 1000
Specify the number of returned items per page.
Name
formatKeyAdditionalProperties
Type
enum<“id“, ”name”>
(optional)
Description
Default: "id"
Specify if you want to return additional property keys as id or name.

Some API clients do not support sending a body in a GET request. The following URL parameters can be used to work around that.

Name
segmentId
Type
string
(optional)
Description
If you saved a segment in Passcreator you can use the segment identifier to update all passes of this segment.
Name
query
Type
Query Language
(optional)
Description
Needs to be base64 url-safe encoded. See Query Language documentation for details on how to construct queries.
Name
fields
Type
string
(optional)
Description
You can specify a comma separated list of fields to be returned in the response if you don’t need all fields of the pass.

Example URLs

Request URL without parameter

https://app.passcreator.com/api/v3/pass

Request URL with parameter pageSize

https://app.passcreator.com/api/v3/pass?pageSize=10

Authorization

For authorization you need to add a HTTP header to your request:

Name
Authorization
Type
string
(mandatory)
Description
HTTP Header that contains your API key.

Example HTTP Header

HTTP header with authorization

    GET /api/v3/pass HTTP/1.1
    Host: app.passcreator.com
    Authorization: yourApiKeyHere
    Content-Type: application/json
    ...

Returned values

This endpoint will return a 200 success status code if the request was successful even if no passes were found.

The optional property page will appear as part of the response object only if pagination applies and if there is a next page with results available. This happens if the number of total search results is greater than the pageSize.
It contains an object with the property:

Name
next
Type
string
(optional)
Description
An endpoint URI to get the next set of search results for this search.

The resulting pass objects returned in the data array will have the following properties with values:

Name
identifier
Type
string
(mandatory)
Description
The identifier of the pass.
Name
autoGeneratedId
Type
string
(mandatory)
Description
Self explainatory
Name
voided
Type
boolean
(mandatory)
Description
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. A pass can also be voided because it is expired.
Name
createdOn
Type
string
(mandatory)
Description
The date and time when the pass was created.
Name
modifiedOn
Type
string
(mandatory)
Description
The date and time when the pass was modified the last time.
Name
expirationDate
Type
string
(mandatory)
Description
The date and time when the pass expires (if an expiration date is set).
Name
userProvidedId
Type
string
(mandatory)
Description
If you've specified a userProvidedId, it will be returned here.
Name
templateId
Type
string
(mandatory)
Description
The ID of the pass-template that was used to create the pass.
Name
templateName
Type
string
(mandatory)
Description
The name of the pass-template that was used to create the pass.
Name
barcodeValue
Type
string | null
(mandatory)
Description
The value of the barcode of this pass. Please note that this doesn't mean that the barcode is actually shown. A pass can have a value for this field but the template can be configured so the barcode isn't shown.
Name
numberOfActive
Type
integer
(mandatory)
Description
The number of active registrations for this pass.
Name
numberOfInactive
Type
integer
(mandatory)
Description
The number of inactive registrations for this pass.
Name
numberOfPrinted
Type
integer
(mandatory)
Description
How many times the print version of this pass has been printed/downloaded.
Name
lastUsage
Type
string
(mandatory)
Description
Self explainatory
Name
storedValue
Type
float | null
(mandatory)
Description
The value of a pass, e.g. the amount of points of a loyalty program.
Name
bundleId
Type
string | null
(mandatory)
Description
Self explainatory
Name
carrierCode
Type
string
(optional)
Description
Only for Boarding Passes
Self explainatory
Name
flightNumber
Type
string
(optional)
Description
Only for Boarding Passes
Self explainatory
Name
passengerName
Type
string
(optional)
Description
Only for Boarding Passes
Self explainatory
Name
localBoardingDateTime
Type
string
(optional)
Description
Only for Boarding Passes
Self explainatory
Name
localScheduledArrivalDateTime
Type
string
(optional)
Description
Only for Boarding Passes
Self explainatory
Name
localEstimatedOrActualArrivalDateTime
Type
string
(optional)
Description
Only for Boarding Passes
Self explainatory
Name
localScheduledDepartureTime
Type
string
(optional)
Description
Only for Boarding Passes
Self explainatory
Name
localEstimatedOrActualDepartureDateTime
Type
string
(optional)
Description
Only for Boarding Passes
Self explainatory
Name
boardingGroup
Type
string
(optional)
Description
Only for Boarding Passes
Self explainatory
Name
boardingPosition
Type
string
(optional)
Description
Only for Boarding Passes
Self explainatory
Name
confirmationCode
Type
string
(optional)
Description
Only for Boarding Passes
Self explainatory
Name
seatClass
Type
string
(optional)
Description
Only for Boarding Passes
Self explainatory
Name
seatNumber
Type
string
(optional)
Description
Only for Boarding Passes
Self explainatory
Name
sequenceNumber
Type
string
(optional)
Description
Only for Boarding Passes
Self explainatory
Name
destinationAirportGate
Type
string
(optional)
Description
Only for Boarding Passes
Self explainatory
Name
destinationAirportTerminal
Type
string
(optional)
Description
Only for Boarding Passes
Self explainatory
Name
destinationAirportCode
Type
string
(optional)
Description
Only for Boarding Passes
Self explainatory
Name
originAirportTerminal
Type
string
(optional)
Description
Only for Boarding Passes
Self explainatory
Name
originAirportGate
Type
string
(optional)
Description
Only for Boarding Passes
Self explainatory
Name
originAirportCode
Type
string
(optional)
Description
Only for Boarding Passes
Self explainatory
Name
barcodeAltText
Type
string | null
(mandatory)
Description
Alternative barcode text.
Name
bulkCreationJobId
Type
string | null
(mandatory)
Description
Self explainatory
Name
downloadEnabledUntil
Type
string | null
(mandatory)
Description
A date and time until the download should be possible. If you did not specify that parameter, the download will be enabled for ten minutes.
Name
noOfRegistrations
Type
integer
(mandatory)
Description
Self explainatory
Name
noOfActiveRegistrationsAppleWallet
Type
integer
(mandatory)
Description
Self explainatory
Name
noOfInactiveRegistrationsAppleWallet
Type
integer
(mandatory)
Description
Self explainatory
Name
noOfActiveRegistrationsGoogleWallet
Type
integer
(mandatory)
Description
Self explainatory
Name
noOfInactiveRegistrationsGoogleWallet
Type
integer
(mandatory)
Description
Self explainatory
Name
noOfActiveRegistrationsPassWallet
Type
integer
(mandatory)
Description
Self explainatory
Name
noOfInactiveRegistrationsPassWallet
Type
integer
(mandatory)
Description
Self explainatory
Name
noOfActiveRegistrationsYourWallet
Type
integer
(mandatory)
Description
Self explainatory
Name
noOfInactiveRegistrationsYourWallet
Type
integer
(mandatory)
Description
Self explainatory
Name
noOfActiveRegistrationsWalletPasses
Type
integer
(mandatory)
Description
Self explainatory
Name
noOfInactiveRegistrationsWalletPasses
Type
integer
(mandatory)
Description
Self explainatory
Name
noOfActiveRegistrationsAndroidOther
Type
integer
(mandatory)
Description
Self explainatory
Name
noOfInactiveRegistrationsAndroidOther
Type
integer
(mandatory)
Description
Self explainatory
Name
firstDownloadedAt
Type
string | null
(mandatory)
Description
Self explainatory
Name
projectId
Type
string | null
(mandatory)
Description
Self explainatory
Name
relevantDate
Type
string
(mandatory)
Description
It's the date when the pass shows up on the lockscreen, if your template is using a different relevant date per pass and you specified this date in the format Y-m-d H:i.
Name
validAsOfDate
Type
string
(mandatory)
Description
The pass is only valid from this date onwards.

Additional Properties are listed either with the identifier or the name as key. This can be specified through the formatKeyAdditionalProperties URL parameter.

Example Response

Response

{
  "statusCode": 200,
  "success": true,
  "description": "Success",
  "errors": [],
  "count": 10,
  "responseMetaData": {
    "resultsTotal": 36,
    "resultsThisPage": 10
  },
  "page": {
    "next": "https://app.passcreator.com/link-to-page-with-the-next-resultset"
  },
  "data": [
    {
      "identifier": "a0f629e6-6533-40cb-90b8-ef9093bfbb26",
      "autoGeneratedId": "r38extwgahfu30z3og667ea1a6ed76c",
      "voided": false,
      "createdOn": "2024-06-28 11:42:30",
      "modifiedOn": "2024-06-28 11:42:30",
      "expirationDate": "",
      "userProvidedId": "",
      "templateId": "1233456-12345-45646",
      "templateName": "1",
      "linkToPassPage": "https://app.passcreator.com/en/p/123456789123456789",
      "barcodeValue": null,
      "numberOfActive": 0,
      "numberOfInactive": 0,
      "numberOfPrinted": 0,
      "lastUsage": "",
      "storedValue": null,
      "bundleId": null,
      "barcodeAltText": null,
      "bulkCreationJobId": null,
      "downloadEnabledUntil": null,
      "noOfRegistrations": 1,
      "noOfActiveRegistrationsAppleWallet": 0,
      "noOfInactiveRegistrationsAppleWallet": 0,
      "noOfActiveRegistrationsGoogleWallet": 0,
      "noOfInactiveRegistrationsGoogleWallet": 0,
      "noOfActiveRegistrationsPassWallet": 0,
      "noOfInactiveRegistrationsPassWallet": 0,
      "noOfActiveRegistrationsYourWallet": 0,
      "noOfInactiveRegistrationsYourWallet": 0,
      "noOfActiveRegistrationsWalletPasses": 0,
      "noOfInactiveRegistrationsWalletPasses": 0,
      "noOfActiveRegistrationsAndroidOther": 1,
      "noOfInactiveRegistrationsAndroidOther": 0,
      "firstDownloadedAt": null,
      "projectId": null,
      "relevantDate": "",
      "validAsOfDate": ""
    },
    {
      ...
    }
  ]
}

DELETE/api/v3/pass/{identifier}

Delete a Pass

Deletes an existing pass.

Supported input parameters

Name
{identifier}
Type
string
(mandatory)
Description
The identifier of the pass you want to delete.

Example URL

Request URL

https://app.passcreator.com/api/v3/pass/f3ac2137-db46-48e7-9a63-06b13acb18d6

Authorization

For authorization you need to add a HTTP header to your request:

Name
Authorization
Type
string
(mandatory)
Description
HTTP Header that contains your API key.

Example HTTP Header

HTTP header with authorization

    DELETE /api/v3/pass/f3ac2137-db46-48e7-9a63-06b13acb18d6 HTTP/1.1
    Host: app.passcreator.com
    Authorization: yourApiKeyHere
    Content-Type: application/json
    ...

Returned values

Example Responses

Pass was deleted successfully:

{
    "statusCode": 200,
    "success": true,
    "description": "Successfully deleted!",
    "errors": [],
    "count": 1,
    "data": {
        "identifier": "f3ac2137-db46-48e7-9a63-06b13acb18d6"
    }
}

Pass could not be found:

{
    "statusCode": 404,
    "success": false,
    "description": "",
    "errors": [
        "Object not found"
    ],
    "count": 0,
    "data": []
}

Create a Pass

Supported URL parameters

Example URLs

Request URL without parameter

Request URL with parameter

Authorization

Example HTTP Header

HTTP header with authorization

Request Body

Example Request

Request body

Returned values

Example Response

Response

Update a Pass

Supported URL parameters

Example URLs

Request URL without parameter

Request URL with parameter

Authorization

Example HTTP Header

HTTP header with authorization

Request Body

Example Request

Request body

Bulk Update Passes

Supported URL parameters

Example URLs

Request URL without parameter

Authorization

Example HTTP Header

HTTP header with authorization

Request Body

Example Request

Request body

Returned values

Example Response

Response

List / Search Passes

Supported URL parameters

Example URLs

Request URL without parameter

Request URL with parameter pageSize

Authorization

Example HTTP Header

HTTP header with authorization

Returned values

Example Response

Response

Delete a Pass

Supported input parameters

Example URL

Request URL

Authorization

Example HTTP Header

HTTP header with authorization

Returned values

Example Responses

Pass was deleted successfully:

Pass could not be found: