Logo Passcreator

Pass Management V1

The API V1 Pass endpoints allow you to create, update, delete and manage passes in the system.

POST/api/pass

Create a Pass

Creates a new pass instance from a specified template.

There's a new generation of API Endpoints that support the system's highly flexible Query Language. If you're starting a new project, we recommend to use the V3 endpoint to create passes.

To add personalized data to your passes, please read how personalization with additional properties works in the system!

URL Parameters

  • Name
    passtemplate
    Type
    string
    (mandatory)
    Description

    Pass-template UID as URL parameter with the parameter name passtemplate.

  • Name
    zapierStyle
    Type
    boolean
    (optional)
    Description

    Default: false
    Recommended: true - Should be set to true. Use the keys that have been returned by the pass-template endpoint that describes the required fields of a pass-template.

    Legacy templates did support a nested structure to set personalised fields. This is no longer possible with new templates.

Example URL

Request URL

https://app.passcreator.com/api/pass?passtemplate={pass-template-uid}&zapierStyle=true


Authorization

  • Name
    Authorization
    Type
    string
    (mandatory)
    Description

    HTTP Authorization Header that contains your API key.

Example HTTP Header

HTTP header with authorization

POST /api/pass?passtemplate=abc123&zapierStyle=true HTTP/1.1
Host: app.passcreator.com
Authorization: yourApiKeyHere
Content-Type: application/json


Request Body - Additional Properties

You can add your additional properties to the request body directly. Use property names or property IDs as keys.

  • Name
    {PropertyName}
    Type
    string
    (optional)
    Description

    The additional property defined in the template. For example: firstname - use the property name directly as key.

  • Name
    {PropertyID}
    Type
    string
    (optional)
    Description

    Alternatively, use the property ID directly (e.g., 5b3f2f9f66a228.52093670).

To get a list of expected and valid parameters, use the endpoint to get information about a template or the endpoint listing fields only (used for zapierStyle).

Additional Properties Usage

Property examples

{
  "firstname": "John",
  "5b3f2f9f66a228.52093670": "Zurich"
}


Optional Parameters

The following parameters are optional and will vary based on your pass template:

  • Name
    userProvidedId
    Type
    string
    (optional)
    Description

    This is an ID you can specify - it can be used as URL parameter to access the created pass. The URL to access the pass via this ID is always https://app.passcreator.com/passinstance/show/customer-id/userProvidedId. You can find the fixed part of the URL including your customer ID in your account settings.

  • Name
    barcodeValue
    Type
    string
    (optional)
    Description

    Sets the barcode value if no auto generated ID should be used.

  • Name
    barcodeAlternativeText
    Type
    string
    (optional)
    Description

    Sets the alternative barcode text.

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

  • 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
    validAsOfDate
    Type
    string
    (optional)
    Description

    If set the pass is only valid from this date onwards.

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

  • 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 the system 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 the system will automatically send the pass via SMS to the number you've specified.

  • Name
    locations
    Type
    array<object>
    (optional)
    Description

    An array of valid coordinates. latitude and longitude must contain valid values. relevantText is an optional description for the push notification that is shown. 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 float 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

    Array of strings 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.

  • 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. Submit an array with elements that use the language code as key and the URL to the image as the value.

    If you want to know the activated languages for the template, call the endpoint that returns details about a template.

Example Request Body

Request body (zapierStyle=true)

{
  "Customerno": "382716",
  "barcodeValue": "3897897988979823497234",
  "5b3f2f9f66a228.52093670": "Zurich",
  "5b3f2f9f66a228.52093671": "Example street 1",
  "urlToBackground": "https://www.example.com/default-language.png",
  "localizedBackgroundImages": {
    "de": "https://www.example.com/german.png",
    "nl": "https://www.example.com/dutch.png"
  },
  "locations": [{
    "latitude": 48.0933826,
    "longitude": 11.6286617,
    "relevantText": "Welcome to the show!",
    "altitude": 200,
    "maxDistance": 300
  }],
  "eligibleValidationPlaces": ["room1"],
  "userProvidedId": "CUSTOMER-12345",
  "enforceUniqueUserProvidedId": true,
  "emailRecipient": "john.doe@example.com",
  "phoneRecipient": "+49123456789",
  "downloadPin": "1234",
  "storedValue": 25.50,
  "expirationDate": "2025-12-31 23:59",
  "relevantDate": "2025-01-15 09:00",
  "validAsOfDate": "2025-01-01 00:00",
  "labelColor": "000000",
  "foregroundColor": "FFFFFF",
  "backgroundColor": "FF0000"
}


Returned Values

JSON-Array containing the following information:

  • Name
    identifier
    Type
    string
    (mandatory)
    Description

    The unique identifier of the created pass. You should store it in your application if you want to update or delete the pass later.

  • Name
    uri
    Type
    string
    (mandatory)
    Description

    The URI of the pass that can be used to update or delete it.

  • Name
    linkToPassFile
    Type
    string
    (mandatory)
    Description

    The link where the pkpass-file can be downloaded. The pkpass-file is the actual pass that can be opened on iPhones directly.

    Don't use this link to provide the pass to your users in general. It should only be used e.g. if you want to send the Wallet pass to your customers via email after creating a pass. This file is subject to change if you send push notifications which means it might become outdated pretty soon.

  • Name
    linkToPassPage
    Type
    string
    (mandatory)
    Description

    Link to the download page for this pass that detects the operating system of the Smartphone that is used and provides device specific help. You are encouraged to always use this link when providing the pass to users because it provides the best user experience on all devices.

    This link also works with the identifier and your userProvidedId. If you want to set a default language you can pass the language (e.g. en) in the url: https://app.passcreator.com/({language/})p/{identifier|userProvidedId}

  • Name
    barcodeValue
    Type
    string
    (mandatory)
    Description

    The value that is encoded in the barcode of the pass.

  • Name
    genericProperties
    Type
    object
    (mandatory)
    Description

    An array containing the values that you can specify in the extended properties of a pass template.

  • Name
    ErrorMessage
    Type
    string
    (mandatory)
    Description

    If an error occurs we'll include the error message here.

Example Response

Success Response (201)

{
  "identifier": "f4379715-7a69-1742-38ae-836554724306",
  "uri": "https://app.passcreator.com/api/pass/f4379715-7a69-1742-38ae-836554724306",
  "linkToPassFile": "https://app.passcreator.com/_Resources/Persistent/fcef30ff61c575173f32984178796f5e3fde5541/pass.pkpass",
  "linkToPassPage": "https://app.passcreator.com/p/1234567",
  "barcodeValue": "3897897988979823497234",
  "genericProperties": {
    "my-id": "12345678",
    "second-field": "Example value"
  },
  "ErrorMessage": ""
}


Status Codes

  • Name
    201
    Type
    Created
    (mandatory)
    Description

    Pass was successfully created.

  • Name
    400
    Type
    Bad Request
    (mandatory)
    Description

    Invalid request data or validation error. Check the ErrorMessage field for details.

  • Name
    401
    Type
    Unauthorized
    (mandatory)
    Description

    Invalid or missing API key, or attempting to access a template from another customer.

  • Name
    404
    Type
    Not Found
    (mandatory)
    Description

    The specified pass template does not exist.

Common Error Messages

  • Maximum number of passes for this pass template has been reached
  • The given userProvidedId was not unique but the template enforces uniqueness
  • The given additional property value was not unique but the template enforces uniqueness
  • No custom number from the defined range of custom numbers is available
  • Thumbnail could not be imported from given URL
  • Background could not be imported from given URL
  • Logo could not be imported from given URL
  • Expiration date was provided in the wrong format
GET/api/pass/list/{pass-template-uid}

Get All Passes of a Template

Returns a list of all passes for the given pass template ordered by created on date starting at the given index (start parameter). The pageSize defines how many results you'll get with one request.

You can optionally use the createdSince or modifiedSince parameters to only return passes that have been created or modified since the given date.

Path Parameters

  • Name
    pass-template-uid
    Type
    string
    (mandatory)
    Description

    The ID of the template you want to get passes for. This is part of the URL path.

Example Path Usage

URL with path parameter

https://app.passcreator.com/api/pass/list/ddc38a8b-7b2d-4c5e-8318-879230e42f1e


Optional Query Parameters

  • Name
    start
    Type
    integer
    (optional)
    Description

    Default: 0
    The offset where the query should start.

  • Name
    pageSize
    Type
    integer
    (optional)
    Description

    Default: 100, maximum: 100
    The number of results per query.

  • Name
    lastIdOfPriorPage
    Type
    string
    (optional)
    Description

    Recommended
    The UUID of the last entry of the prior page. This will be added to the URL automatically that is returned in the next or self keys.

  • Name
    lastCreatedOnOfPriorPage
    Type
    string
    (optional)
    Description

    Recommended
    The timestamp of the last entry of the createdOn field of the prior page. This will be added to the URL automatically that is returned in the next or self keys.

  • Name
    createdSince
    Type
    string
    (optional)
    Description

    A date in the format Y-m-d H:i (e.g., 2021-07-01 15:30). If set, the result set will only include passes that have been created at or after that date and time.

  • Name
    modifiedSince
    Type
    string
    (optional)
    Description

    A date in the format Y-m-d H:i (e.g., 2021-07-01 15:30). If set, the result set will only include passes that have been modified at or after that date and time.

start and pageSize define the pagination, e.g. the first page is start=0 and pageSize=100, the second page is start=100 and pageSize=100.

You can either use a createdSince or modifiedSince date. If you specify both, the modifiedSince parameter will be ignored.

Example URLs with Query Parameters

URLs with query parameters

https://app.passcreator.com/api/pass/list/ddc38a8b-7b2d-4c5e-8318-879230e42f1e?start=0&pageSize=100
https://app.passcreator.com/api/pass/list/ddc38a8b-7b2d-4c5e-8318-879230e42f1e?start=0&pageSize=100&lastIdOfPriorPage=identifier&lastCreatedOnOfPriorPage=1656500068
https://app.passcreator.com/api/pass/list/ddc38a8b-7b2d-4c5e-8318-879230e42f1e?createdSince=2021-07-01%2015:30
https://app.passcreator.com/api/pass/list/ddc38a8b-7b2d-4c5e-8318-879230e42f1e?modifiedSince=2021-07-01%2015:30


Authorization

  • Name
    Authorization
    Type
    string
    (mandatory)
    Description

    HTTP Authorization Header that contains your API key.

Example HTTP Header

HTTP header

GET /api/pass/list/ddc38a8b-7b2d-4c5e-8318-879230e42f1e?start=0&pageSize=100 HTTP/1.1
Host: app.passcreator.com
Authorization: yourApiKeyHere


Returned Values

JSON-Array containing an information about the query and the results (these are the actual passes):

  • Name
    query
    Type
    object
    (mandatory)
    Description

    Information about the current query including start, pageSize, self URL, and next URL (if available).

  • Name
    query.start
    Type
    integer
    (mandatory)
    Description

    Default: 0
    The start parameter you've specified.

  • Name
    query.pageSize
    Type
    integer
    (mandatory)
    Description

    Default: 100
    The pageSize you've specified.

  • Name
    query.self
    Type
    string
    (mandatory)
    Description

    The URL of the current request.

  • Name
    query.next
    Type
    string
    (optional)
    Description

    The URL of the next page. If no next parameter is returned this means you've reached the end of the list.

  • Name
    total
    Type
    integer
    (mandatory)
    Description

    The total number of results for your query.

  • Name
    results
    Type
    array<object>
    (mandatory)
    Description

    An array of passes. Each pass object contains the same fields as returned by the Read a Pass endpoint, including all standard pass fields and any additional properties specific to the pass type (e.g., boarding pass fields).

Example Response

Success Response (200)

{
  "query": {
    "start": 0,
    "pageSize": 1,
    "self": "https://app.passcreator.com/api/pass/list/ddc38a8b-7b2d-4c5e-8318-879230e42f1e?start=0&pageSize=2&lastIdOfPriorPage=123413c6-714e-4640-b4ee-b94c8061620c&lastCreatedOnOfPriorPage=1656500068",
    "next": "https://app.passcreator.com/api/pass/list/ddc38a8b-7b2d-4c5e-8318-879230e42f1e?start=2&pageSize=2&lastIdOfPriorPage=f36a13c6-714e-4640-b4ee-b94c8061620c&lastCreatedOnOfPriorPage=1656500213"
  },
  "total": 136,
  "results": [
    {
      "identifier": "f36a13c6-714e-4640-b4ee-b94c8061620c",
      "uri": "https://app.passcreator.com/api/pass/f36a13c6-714e-4640-b4ee-b94c8061620c",
      "generatedId": "we179wavopfw4zpnae5f7ea7464f4a3",
      "searchString": "|https://app.passcreator.com/en/p/nr9pod8myjbv65f7ea7464f436||||Sepp|SMSTEST|||we179wavopfw4zpnae5f7ea7464f4a3|987654321||Sepp|Kryptonit|hello@example.com|",
      "passData": "",
      "voided": false,
      "redeemed": false,
      "createdOn": "2020-10-08 07:44:38",
      "modifiedOn": "2020-10-08 13:43:59",
      "expirationDate": "2080-10-08 13:42:00",
      "userProvidedId": "",
      "passTemplateGuid": "1068b515-7fcb-456f-9abc-0b508b428301",
      "passTemplateName": "NFC Pass",
      "linkToPassPage": "https://app.passcreator.com/en/p/nr9pod8myjbv65f7ea7464f436",
      "thumbnail": null,
      "qrCodeImage": "https://app.passcreator.com/qr/987654321",
      "barcodeValue": "987654321",
      "numberOfActive": 1,
      "numberOfInactive": 0,
      "numberOfPrinted": 0,
      "passFieldData": {
        "5cb1a40ac68f80.15012600": "",
        "5e2721b93da442.17595709": "",
        "5e552028e62805.33020425": "SMSTEST",
        "5e5e0adfc1b6e4.84503451": "Sepp",
        "5f7216b0297200.36897838": "",
        "5f7216b02972e2.34068785": ""
      }
    }
  ]
}


Status Codes

  • Name
    200
    Type
    OK
    (mandatory)
    Description

    Passes successfully retrieved.

  • Name
    400
    Type
    Bad Request
    (mandatory)
    Description

    Invalid request parameters (e.g., pageSize > 100).

  • Name
    401
    Type
    Unauthorized
    (mandatory)
    Description

    Invalid or missing API key.

  • Name
    404
    Type
    Not Found
    (mandatory)
    Description

    The specified pass template does not exist or you don't have access to it.

Usage Notes

  • Use the lastIdOfPriorPage and lastCreatedOnOfPriorPage parameters for efficient pagination
  • The next URL in the response includes these pagination parameters automatically
  • When there's no next URL, you've reached the end of the results
  • Maximum pageSize is 100 to ensure good performance
  • Filter by creation or modification date using createdSince or modifiedSince
GET/api/pass/{pass-uid}

Read a Pass

Get information about a specific pass instance. If the given pass UID is known, information about the pass is returned.

Path Parameters

  • Name
    pass-uid
    Type
    string
    (mandatory)
    Description

    UID, userProvidedId, or barcode value of the pass you want information about. This is part of the URL path.

Example Path Usage

URL with path parameter

https://app.passcreator.com/api/pass/f4379715-7a69-1742-38ae-836554724306
https://app.passcreator.com/api/pass/CUSTOMER-12345
https://app.passcreator.com/api/pass/3897897988979823497234


Optional Query Parameters

  • Name
    includeFieldMapping
    Type
    boolean
    (optional)
    Description

    Default: false
    Set this GET parameter to true if you want to get an array called fieldMapping that contains the name of the additional property as key and the ID as value.

  • Name
    appConfigurationId
    Type
    string
    (optional)
    Description

    If you specify the ID of an app configuration, the system will check if the pass is eligible at the location that is defined for the app configuration. If the pass is not eligible or was used there already, the voided and redeemed fields will be displayed as true, indicating that the pass should not be accepted.

Example URLs with Query Parameters

URLs with query parameters

https://app.passcreator.com/api/pass/f4379715-7a69-1742-38ae-836554724306?includeFieldMapping=true
https://app.passcreator.com/api/pass/f4379715-7a69-1742-38ae-836554724306?appConfigurationId=abc123
https://app.passcreator.com/api/pass/CUSTOMER-12345?includeFieldMapping=true&appConfigurationId=abc123


Authorization

  • Name
    Authorization
    Type
    string
    (mandatory)
    Description

    HTTP Authorization Header that contains your API key.

Example HTTP Header

HTTP header

GET /api/pass/f4379715-7a69-1742-38ae-836554724306 HTTP/1.1
Host: app.passcreator.com
Authorization: yourApiKeyHere


Returned Values

JSON-Array containing an array for the pass that has been found. All endpoints that return data of passes use this common data format:

  • Name
    identifier
    Type
    string
    (mandatory)
    Description

    The UID of the pass that has the given ID.

  • Name
    uri
    Type
    string
    (mandatory)
    Description

    The URI of the pass that can be used to update or delete the pass.

  • Name
    generatedId
    Type
    string
    (mandatory)
    Description

    The ID (this is the one that was given in the request).

  • Name
    searchString
    Type
    string
    (mandatory)
    Description

    Contains all data on the pass separated by pipe symbols |.

  • Name
    voided
    Type
    boolean
    (mandatory)
    Description

    false if the pass is not voided (has not been used). true if the pass is voided (has been used already). A pass can also be voided because it is expired.

  • Name
    redeemed
    Type
    boolean
    (mandatory)
    Description

    false if the pass hasn't been used, true if it was used. This value stays the same, no matter if a pass is expired or not.

  • 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 | null
    (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
    passTemplateGuid
    Type
    string
    (mandatory)
    Description

    The GUID of the pass-template that was used to create the pass.

  • Name
    passTemplateName
    Type
    string
    (mandatory)
    Description

    The name of the pass-template that was used to create the pass.

  • Name
    linkToPassPage
    Type
    string
    (mandatory)
    Description

    The URL to the page where your users can download the pass.

  • Name
    thumbnail
    Type
    string | null
    (mandatory)
    Description

    If this pass contains a thumbnail (possible for event tickets and membership cards), the URL to the thumbnail image will be returned here. Otherwise null.

  • Name
    qrCodeImage
    Type
    string
    (mandatory)
    Description

    The URL to the QR Code that is shown on the pass.

  • Name
    barcodeValue
    Type
    string
    (mandatory)
    Description

    The value of the barcode of this pass. 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
    passFieldData
    Type
    object
    (mandatory)
    Description

    All personalised fields of this pass including additional properties as an array.

  • Name
    lastUsage
    Type
    string | null
    (mandatory)
    Description

    The date and time when the pass was last used (e.g., scanned at the point of sale). Returns null if the pass has never been used.

  • Name
    storedValue
    Type
    float
    (mandatory)
    Description

    The value of a pass, e.g. the amount of points of a loyalty program.

  • Name
    eligiblePlaces
    Type
    array<string>
    (mandatory)
    Description

    A list of places where this pass may be used.

  • Name
    placesUsedAt
    Type
    object
    (mandatory)
    Description

    An object where the key is the timestamp of the usage date and the value the room. Note that a pass can be used multiple times at a location if it was scanned multiple times. Only the first usage was valid in such cases.

  • Name
    downloadPin
    Type
    string
    (mandatory)
    Description

    A PIN that users have to enter before being able to download the pass. Returns empty string if no PIN is set.

  • Name
    bundleId
    Type
    string | null
    (mandatory)
    Description

    The bundle identifier used to group passes together. Returns null if no bundle ID is set.

  • Name
    passData
    Type
    string
    (mandatory)
    Description

    If you've specified a custom data format how you want to show data of your pass, this will be returned here.

  • Name
    fieldMapping
    Type
    object
    (optional)
    Description

    Only included when includeFieldMapping=true
    An object containing the mapping of additional property names to their IDs.

Dates are converted to the timezone that is set in your company settings.

Example Response

Success Response (200)

{
  "identifier": "f36a13c6-714e-4640-b4ee-b94c8061620c",
  "uri": "https://app.passcreator.com/api/pass/f36a13c6-714e-4640-b4ee-b94c8061620c",
  "generatedId": "we179wavopfw4zpnae5f7ea7464f4a3",
  "searchString": "|https://app.passcreator.com/en/p/nr9pod8myjbv65f7ea7464f436||||Sepp|SMSTEST|||we179wavopfw4zpnae5f7ea7464f4a3|987654321||Sepp|Kryptonit|hello@example.com|",
  "voided": false,
  "redeemed": false,
  "createdOn": "2020-10-08 07:44:38",
  "modifiedOn": "2020-10-08 13:43:59",
  "expirationDate": "2080-10-08 13:42:00",
  "userProvidedId": "",
  "passTemplateGuid": "1068b515-7fcb-456f-9abc-0b508b428301",
  "passTemplateName": "NFC Pass",
  "linkToPassPage": "https://app.passcreator.com/en/p/nr9pod8myjbv65f7ea7464f436",
  "thumbnail": null,
  "qrCodeImage": "https://app.passcreator.com/qr/987654321",
  "barcodeValue": "987654321",
  "numberOfActive": 1,
  "numberOfInactive": 0,
  "numberOfPrinted": 0,
  "passFieldData": {
    "5cb1a40ac68f80.15012600": "",
    "5e2721b93da442.17595709": "",
    "5e552028e62805.33020425": "SMSTEST",
    "5e5e0adfc1b6e4.84503451": "Sepp",
    "5f7216b0297200.36897838": "",
    "5f7216b02972e2.34068785": ""
  },
  "lastUsage": "2022-02-23 14:28:51",
  "storedValue": 7,
  "eligiblePlaces": [
    "room1",
    "room2"
  ],
  "placesUsedAt": {
    "1645625299": "room1",
    "1645625531": "room1"
  },
  "downloadPin": "",
  "bundleId": null,
  "passData": ""
}


Status Codes

  • Name
    200
    Type
    OK
    (mandatory)
    Description

    Pass information successfully retrieved.

  • Name
    401
    Type
    Unauthorized
    (mandatory)
    Description

    Invalid or missing API key.

  • Name
    404
    Type
    Not Found
    (mandatory)
    Description

    The specified pass does not exist or the app configuration is invalid.

Usage Notes

  • You can use the pass identifier, userProvidedId, or barcode value as the path parameter
  • When using appConfigurationId, the system validates pass eligibility at the specified location
  • Include includeFieldMapping=true to get the mapping between property names and IDs
  • The response format follows the common data format used throughout the API
GET/api/pass/geturis/{pass-uid}

Get URIs to resources for a pass

Retrieve direct URIs to the actual pass resources for Android and iOS platforms. This allows you to build a completely customized way of delivering passes.

Path Parameters

  • Name
    pass-uid
    Type
    string
    (mandatory)
    Description

    UID of the pass you want the URLs for. This is part of the URL path.

Example Path Usage

URL with path parameter

https://app.passcreator.com/api/pass/geturis/712b34b6-c56a-4a84-a08d-3500237eef08


Authorization

  • Name
    Authorization
    Type
    string
    (mandatory)
    Description

    HTTP Authorization Header that contains your API key.

Example HTTP Header

HTTP header

GET /api/pass/geturis/712b34b6-c56a-4a84-a08d-3500237eef08 HTTP/1.1
Host: app.passcreator.com
Authorization: yourApiKeyHere


Returned Values

JSON object containing the pass URIs:

  • Name
    iPhoneUri
    Type
    string
    (mandatory)
    Description

    The URL that returns the actual pkpass file for Apple Wallet.

  • Name
    AndroidUri
    Type
    string
    (mandatory)
    Description

    Depending on your template, this is either a URL that triggers the save dialog of Google Pay or a deeplink that opens the pass in PassWallet.

We suggest always using the pass download pages or integrations that Passcreator offers, but this allows you to build your own, completely customized way of delivering passes. Keep in mind that you need to do the device and browser recognition on your own if you go that route.

Example Response

Success Response (200)

{
  "iPhoneUri": "https://app.passcreator.com/passinstance/pkpass?passInstance%5B__identity%5D=712b34b6-c56a-4a84-a08d-3500237eef08",
  "AndroidUri": "https://passwallet.page.link/?apn=com.attidomobile.passwallet&link=https%3A%2F%2Fapp.passcreator.com%2Fpassinstance%2Fpkpass%3FpassInstance%255B__identity%255D%3D712b34b6-c56a-4a84-a08d-3500237eef08"
}


Status Codes

  • Name
    200
    Type
    OK
    (mandatory)
    Description

    Pass URIs successfully retrieved.

  • Name
    401
    Type
    Unauthorized
    (mandatory)
    Description

    Invalid or missing API key.

  • Name
    404
    Type
    Not Found
    (mandatory)
    Description

    The specified pass does not exist.

Usage Notes

  • The iPhoneUri provides a direct link to the .pkpass file for Apple Wallet
  • The AndroidUri behavior depends on your pass template configuration
  • You are responsible for device and browser detection when using these URIs directly
  • Consider using Passcreator's built-in pass download pages for automatic device handling
GET/api/pass/search/{pass-template-uid}/{searchString}

Search a pass based on its content

Search for passes using a keyword contained in their content. This endpoint allows you to search for information like names or email addresses that are not being used in a barcode.

Path Parameters

  • Name
    pass-template-uid
    Type
    string
    (mandatory)
    Description

    UID of the pass-template you want to search passes for. This is part of the URL path.

  • Name
    searchString
    Type
    string
    (mandatory)
    Description

    The keyword you want to search for. This is part of the URL path.

Example Path Usage

URL with path parameters

https://app.passcreator.com/api/pass/search/{pass-template-uid}/johnny


Authorization

  • Name
    Authorization
    Type
    string
    (mandatory)
    Description

    HTTP Authorization Header that contains your API key.

Example HTTP Header

HTTP header

GET /api/pass/search/{pass-template-uid}/johnny HTTP/1.1
Host: app.passcreator.com
Authorization: yourApiKeyHere


Returned Values

JSON array containing an object for each pass that has been found. See the Read a Pass endpoint for details about the format that passes use and included fields. For boarding passes, additional fields are documented in the Manage Flight Boarding Passes section.

This endpoint may also take into account passes that contain a similar word than your search phrase. E.g. if you search for ID 12345 you may also receive results for passes containing 1234. Or it may return results for Johnny and John, when you search for Johnny.

Example Response

When passes are found, a JSON array is returned:

Success Response (200)

[
  {
    "identifier": "cd95f105-ce5a-47d1-adaf-ac1996b3c1b4",
    "uri": "https://app.passcreator.com/api/pass/cd95f105-ce5a-47d1-adaf-ac1996b3c1b4",
    "generatedId": "i76maqci3r7nb0yz9268b82f8f32746",
    "searchString": "",
    "voided": false,
    "redeemed": false,
    "createdOn": "2025-09-03 08:07:43",
    "modifiedOn": "2025-09-03 08:07:43",
    "expirationDate": null,
    "userProvidedId": "",
    "passTemplateGuid": "eaf794bc-6bf1-4801-bd08-05e4eb97e236",
    "passTemplateName": "Documentation",
    "linkToPassPage": "https://app.passcreator.com/p/haklg0razi6zd68b82f8f32717",
    "thumbnail": null,
    "qrCodeImage": "https://app.passcreator.com/qr/i76maqci3r7nb0yz9268b82f8f32746",
    "barcodeValue": "i76maqci3r7nb0yz9268b82f8f32746",
    "numberOfActive": 0,
    "numberOfInactive": 0,
    "numberOfPrinted": 0,
    "passFieldData": {
      "68ad9520a8eb28.52872334": "Johnny",
      "68b82f47940da5.86040945": "Doe"
    },
    "lastUsage": null,
    "storedValue": 0,
    "eligiblePlaces": [],
    "placesUsedAt": [],
    "downloadPin": "",
    "bundleId": null,
    "passData": "Firstname: Johnny\nLastname: Doe\n"
  },
  {
    "identifier": "ef3f87a1-1d6a-4516-9b1b-91806032f9d6",
    "uri": "https://app.passcreator.com/api/pass/ef3f87a1-1d6a-4516-9b1b-91806032f9d6",
    "generatedId": "lwx37u74eglzfoce4a68b82f6f55a1c",
    "searchString": "",
    "voided": false,
    "redeemed": false,
    "createdOn": "2025-09-03 08:07:11",
    "modifiedOn": "2025-09-03 08:07:11",
    "expirationDate": null,
    "userProvidedId": "",
    "passTemplateGuid": "eaf794bc-6bf1-4801-bd08-05e4eb97e236",
    "passTemplateName": "Documentation",
    "linkToPassPage": "https://app.passcreator.com/p/5sl6idcdxbas568b82f6f559e2",
    "thumbnail": null,
    "qrCodeImage": "https://app.passcreator.com/qr/lwx37u74eglzfoce4a68b82f6f55a1c",
    "barcodeValue": "lwx37u74eglzfoce4a68b82f6f55a1c",
    "numberOfActive": 0,
    "numberOfInactive": 0,
    "numberOfPrinted": 0,
    "passFieldData": {
      "68ad9520a8eb28.52872334": "John",
      "68b82f47940da5.86040945": "Doe"
    },
    "lastUsage": null,
    "storedValue": 0,
    "eligiblePlaces": [],
    "placesUsedAt": [],
    "downloadPin": "",
    "bundleId": null,
    "passData": "Firstname: John\nLastname: Doe\n"
  }
]

When no passes match:

Empty Result (200)

[]


Status Codes

  • Name
    200
    Type
    OK
    (mandatory)
    Description

    Search completed successfully. Returns a JSON array (may be empty).

  • Name
    401
    Type
    Unauthorized
    (mandatory)
    Description

    Invalid or missing API key.

  • Name
    404
    Type
    Not Found
    (mandatory)
    Description

    The specified pass template does not exist.

Usage Notes

  • Returns a JSON array
  • Each pass follows the format documented in the Read a Pass endpoint
  • For boarding passes, see additional fields in the Manage Flight Boarding Passes section
  • The search may return partial matches and results for similar terms
GET/api/pass/statistics/{pass-template-uid}

Get Statistics About Incremental Changes of Pass Usage

Get detailed statistics about passes of a template. This returns timelines for the requested time frame and shows when and how many passes have been created, updated, deleted (deactivated) or saved as well as the operating systems that have been used.

Path Parameters

  • Name
    pass-template-uid
    Type
    string
    (mandatory)
    Description

    The UID of the pass template for whose passes you want to get statistics for. This is part of the URL path.

Example Path Usage

URL with path parameter

https://app.passcreator.com/api/pass/statistics/eaf794bc-6bf1-4801-bd08-05e4eb97e236


Required Query Parameters

  • Name
    timeFrame
    Type
    enum<'day', 'week', 'month', 'year'>
    (mandatory)
    Description

    The time frame you want to get statistics for. Supported values are day, week, month and year. year is only supported for templates with less than 10,000 passes.

  • Name
    day
    Type
    string
    (mandatory)
    Description

    The day that determines what time you'll receive statistics for. Supported are either the string today or a day in the format Y-m-d (e.g., 2025-01-15).

Example URLs with Query Parameters

URLs with query parameters

https://app.passcreator.com/api/pass/statistics/eaf794bc-6bf1-4801-bd08-05e4eb97e236?timeFrame=day&day=today
https://app.passcreator.com/api/pass/statistics/eaf794bc-6bf1-4801-bd08-05e4eb97e236?timeFrame=week&day=2025-01-15
https://app.passcreator.com/api/pass/statistics/eaf794bc-6bf1-4801-bd08-05e4eb97e236?timeFrame=month&day=2025-01-15


Authorization

  • Name
    Authorization
    Type
    string
    (mandatory)
    Description

    HTTP Authorization Header that contains your API key.

Example HTTP Header

HTTP header

GET /api/pass/statistics/eaf794bc-6bf1-4801-bd08-05e4eb97e236?timeFrame=day&day=today HTTP/1.1
Host: app.passcreator.com
Authorization: yourApiKeyHere


Returned Values

JSON object containing the following sub-arrays:

  • Name
    activeRegistrationsTimeline
    Type
    array<object>
    (mandatory)
    Description

    Shows how many passes have been activated (means saved on a smartphone) per day. Each object contains date and noOfPasses fields.

  • Name
    inactiveRegistrationsTimeline
    Type
    array<object>
    (mandatory)
    Description

    Shows how many passes have been deactivated (removed from a phone or push notifications have been deactivated) per day. Each object contains date and noOfPasses fields.

  • Name
    createdPassesTimeline
    Type
    array<object>
    (mandatory)
    Description

    Shows how many passes have been created per day. Each object contains date and noOfPasses fields.

  • Name
    updatedPassesTimeline
    Type
    array<object>
    (mandatory)
    Description

    Shows how many passes have been updated per day. Each object contains date and noOfPasses fields.

  • Name
    sentPushNotificationsTimeline
    Type
    array<object>
    (mandatory)
    Description

    The number of times a push notification has been triggered (which means we've informed the phone that there's something new). Each object contains date and noOfPasses fields.

  • Name
    receivedPushNotificationsTimeline
    Type
    array<object>
    (mandatory)
    Description

    The number of times the phone has actually downloaded the new version of a pass. Each object contains date and noOfPasses fields.

  • Name
    passesPerOperatingSystem
    Type
    object
    (mandatory)
    Description

    Contains three key value pairs: iOS, Android, WindowsPhone. Each key contains the number of passes that are active right now or have been active per operating system.

Example Response

Success Response (200)

{
  "activeRegistrationsTimeline": [
    {
      "date": "2019-03-10",
      "noOfPasses": "268"
    }
  ],
  "inactiveRegistrationsTimeline": [
    {
      "date": "2019-03-10",
      "noOfPasses": "9"
    }
  ],
  "createdPassesTimeline": [
    {
      "date": "2019-03-10",
      "noOfPasses": "24"
    }
  ],
  "updatedPassesTimeline": [
    {
      "date": "2019-03-10",
      "noOfPasses": "541"
    }
  ],
  "sentPushNotificationsTimeline": [
    {
      "date": "2019-03-10",
      "noOfPasses": "359"
    }
  ],
  "receivedPushNotificationsTimeline": [
    {
      "date": "2019-03-10",
      "noOfPasses": "348"
    }
  ],
  "passesPerOperatingSystem": {
    "iOS": 143,
    "Android": 125,
    "WindowsPhone": 0
  }
}


Status Codes

  • Name
    200
    Type
    OK
    (mandatory)
    Description

    Statistics successfully retrieved.

  • Name
    400
    Type
    Bad Request
    (mandatory)
    Description

    Invalid timeFrame parameter or this endpoint is not designed to do data analytics on a larger scale (for templates with more than 10,000 passes using timeFrame other than day or month).

  • Name
    401
    Type
    Unauthorized
    (mandatory)
    Description

    Invalid or missing API key, or attempting to access a template from another customer.

  • Name
    404
    Type
    Not Found
    (mandatory)
    Description

    The specified pass template does not exist.

Usage Notes

  • Year timeFrame is only supported for templates with less than 10,000 passes
  • For larger templates, use day or month timeFrame to ensure good performance
  • The day parameter accepts either today or a date in Y-m-d format
  • All timeline arrays contain objects with date and noOfPasses fields
GET/api/pass/statistics/{pass-template-uid}/activehistory/{startingday}

Get History of Active and Inactive Passes for a Timeframe

Get the history of the total number of active and inactive passes for a template. This starts at the given day until today.

Please note that the system does not keep statistical data for deleted passes. If you remove a pass it will also be removed from this timeline.

Path Parameters

  • Name
    pass-template-uid
    Type
    string
    (mandatory)
    Description

    The UID of the pass template for whose passes you want to get statistics for. This is part of the URL path.

  • Name
    startingday
    Type
    string
    (optional)
    Description

    The day in the format Y-m-d (e.g., 2020-10-01) from when onwards the system should return data. If you don't specify this parameter you'll get data for the last seven days.

Example Path Usage

URL with path parameters

https://app.passcreator.com/api/pass/statistics/eaf794bc-6bf1-4801-bd08-05e4eb97e236/activehistory/2020-10-01
https://app.passcreator.com/api/pass/statistics/eaf794bc-6bf1-4801-bd08-05e4eb97e236/activehistory


Authorization

  • Name
    Authorization
    Type
    string
    (mandatory)
    Description

    HTTP Authorization Header that contains your API key.

Example HTTP Header

HTTP header

GET /api/pass/statistics/eaf794bc-6bf1-4801-bd08-05e4eb97e236/activehistory/2020-10-01 HTTP/1.1
Host: app.passcreator.com
Authorization: yourApiKeyHere


Returned Values

JSON-Array containing the following sub-arrays:

  • Name
    date
    Type
    string
    (mandatory)
    Description

    The date in the format Y-m-d.

  • Name
    active
    Type
    integer
    (mandatory)
    Description

    The total number of active passes at that day.

  • Name
    inactive
    Type
    integer
    (mandatory)
    Description

    The total number of inactive passes at that day.

Example Response

Success Response (200)

[
  {
    "date": "2020-10-01",
    "active": 7,
    "inactive": 4
  },
  {
    "date": "2020-10-02",
    "active": 7,
    "inactive": 4
  },
  {
    "date": "2020-10-03",
    "active": 7,
    "inactive": 4
  },
  {
    "date": "2020-10-04",
    "active": 7,
    "inactive": 4
  },
  {
    "date": "2020-10-05",
    "active": 7,
    "inactive": 4
  },
  {
    "date": "2020-10-06",
    "active": 7,
    "inactive": 4
  },
  {
    "date": "2020-10-07",
    "active": 7,
    "inactive": 4
  },
  {
    "date": "2020-10-08",
    "active": 8,
    "inactive": 5
  }
]


Status Codes

  • Name
    200
    Type
    OK
    (mandatory)
    Description

    History successfully retrieved.

  • Name
    401
    Type
    Unauthorized
    (mandatory)
    Description

    Invalid or missing API key, or attempting to access a template from another customer.

  • Name
    404
    Type
    Not Found
    (mandatory)
    Description

    The specified pass template does not exist.

Usage Notes

  • Returns data from the specified starting day until today
  • If no starting day is provided, returns data for the last seven days
  • Deleted passes are not included in the historical data
  • Each array entry represents one day with active and inactive pass counts
POST/api/pass/{pass-uid}

Update a Pass

Updates an existing pass instance with new data.

There's a new generation of API Endpoints that support the system's highly flexible Query Language. If you're starting a new project, we recommend to use the V3 endpoint to update passes.

Path Parameters

  • Name
    pass-uid
    Type
    string
    (mandatory)
    Description

    ID or userProvidedId of the pass that must be updated. This is part of the URL path.

Example Path Usage

URL with path parameter

https://app.passcreator.com/api/pass/f4379715-7a69-1742-38ae-836554724306?zapierStyle=true
https://app.passcreator.com/api/pass/CUSTOMER-12345?zapierStyle=true


Required Query Parameters

  • Name
    zapierStyle
    Type
    boolean
    (mandatory)
    Description

    Must be set to true. Use the keys that have been returned by the pass-template endpoint that describes the required fields of a pass-template.

    Legacy templates did support a nested structure to set personalised fields. This is no longer possible with new templates.

Example URL with Required Parameters

Request URL

https://app.passcreator.com/api/pass/f4379715-7a69-1742-38ae-836554724306?zapierStyle=true


Authorization

  • Name
    Authorization
    Type
    string
    (mandatory)
    Description

    HTTP Authorization Header that contains your API key.

Example HTTP Header

HTTP header with authorization

POST /api/pass/f4379715-7a69-1742-38ae-836554724306?zapierStyle=true HTTP/1.1
Host: app.passcreator.com
Authorization: yourApiKeyHere
Content-Type: application/json


Request Body - Additional Properties

You can add your additional properties to the request body directly. Use property names or property IDs as keys.

  • Name
    {PropertyName}
    Type
    string
    (optional)
    Description

    The additional property defined in the template. For example: firstname - use the property name directly as key.

  • Name
    {PropertyID}
    Type
    string
    (optional)
    Description

    Alternatively, use the property ID directly (e.g., 5b3f2f9f66a228.52093670).

To get a list of expected and valid parameters, use the endpoint to get information about a template or the endpoint listing fields only (used for zapierStyle).

Additional Properties Usage

Property examples

{
  "firstname": "John",
  "5b3f2f9f66a228.52093670": "Zurich"
}


Optional Parameters

The following parameters are optional and will vary based on your pass template:

  • Name
    voided
    Type
    boolean
    (optional)
    Description

    A boolean that indicates if the pass is voided or not. Voided means the QR-Code will be greyed out and the pass can't be used any longer. Submit true if the pass should be voided, false if it shouldn't be voided. If omitted, the current value remains unchanged.

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

  • Name
    barcodeValue
    Type
    string
    (optional)
    Description

    Sets the barcode value if no auto generated ID should be used.

  • Name
    barcodeAlternativeText
    Type
    string
    (optional)
    Description

    Sets the alternative barcode text.

  • 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 updated on the pass.

  • 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 updated on the pass.

  • 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 updated on the pass.

  • Name
    validAsOfDate
    Type
    string
    (optional)
    Description

    If set the pass is only valid from this date onwards.

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

  • 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 the system 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 the system will automatically send the pass via SMS to the number you've specified.

  • Name
    locations
    Type
    array<object>
    (optional)
    Description

    An array of valid coordinates. latitude and longitude must contain valid values. relevantText is an optional description for the push notification that is shown. 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 float 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

    Array of strings 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.

  • 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. Submit an array with elements that use the language code as key and the URL to the image as the value.

    If you want to know the activated languages for the template, call the endpoint that returns details about a template.

Example Request Body

Request body (zapierStyle=true)

{
  "Customerno": "382716",
  "barcodeValue": "3897897988979823497234",
  "5b3f2f9f66a228.52093670": "Zurich",
  "5b3f2f9f66a228.52093671": "Example street 1",
  "urlToBackground": "https://www.example.com/default-language.png",
  "localizedBackgroundImages": {
    "de": "https://www.example.com/german.png",
    "nl": "https://www.example.com/dutch.png"
  },
  "locations": [{
    "latitude": 48.0933826,
    "longitude": 11.6286617,
    "relevantText": "Welcome to the updated event!",
    "altitude": 200,
    "maxDistance": 300
  }],
  "eligibleValidationPlaces": ["room1"],
  "emailRecipient": "john.doe@example.com",
  "phoneRecipient": "+49123456789",
  "downloadPin": "1234",
  "storedValue": 200,
  "expirationDate": "2025-12-31 23:59",
  "relevantDate": "2025-01-15 09:00",
  "validAsOfDate": "2025-01-01 00:00",
  "labelColor": "000000",
  "foregroundColor": "FFFFFF",
  "backgroundColor": "FF0000",
  "voided": false
}


Returned Values

If the pass has been updated successfully, HTTP status 204 (No Content) is returned with no response body.

Example Response

Success Response (204)

HTTP/1.1 204 No Content


Status Codes

  • Name
    204
    Type
    No Content
    (mandatory)
    Description

    Pass was successfully updated.

  • Name
    400
    Type
    Bad Request
    (mandatory)
    Description

    Invalid request data or validation error. Check the ErrorMessage field for details.

  • Name
    401
    Type
    Unauthorized
    (mandatory)
    Description

    Invalid or missing API key, or attempting to access a pass from another customer.

  • Name
    404
    Type
    Not Found
    (mandatory)
    Description

    The specified pass does not exist.

Common Error Messages

  • The given additional property value was not unique but the template enforces uniqueness
  • Thumbnail could not be imported from given URL
  • Background could not be imported from given URL
  • Logo could not be imported from given URL
  • Expiration date was provided in the wrong format
  • The given values have to be part of the validValidationPlaces array of the template
PUT/api/pass/{pass-uid}

Mark a Pass Voided

Mark a pass as voided or not voided. This is useful for event tickets that have been used. When a pass is voided, the barcode shown on the pass will be greyed out on the user's device.

Path Parameters

  • Name
    pass-uid
    Type
    string
    (mandatory)
    Description

    The unique identifier of the pass. Can be either:

    • Pass UID (e.g., f4379715-7a69-1742-38ae-836554724306)
    • User provided ID
    • Barcode value

Example URL

Request URL

https://app.passcreator.com/api/pass/f4379715-7a69-1742-38ae-836554724306


Authorization

  • Name
    Authorization
    Type
    string
    (mandatory)
    Description

    HTTP Authorization Header that contains your API key.

Example HTTP Header

HTTP header with authorization

PUT /api/pass/f4379715-7a69-1742-38ae-836554724306 HTTP/1.1
Host: app.passcreator.com
Authorization: yourApiKeyHere
Content-Type: application/json


Request Body

  • Name
    voided
    Type
    boolean
    (mandatory)
    Description

    Indicates if a pass is voided/invalid (true) or not (false). When true, the QR code will be greyed out and the pass can't be used any longer.

Example Request Body

Mark as voided

{
  "voided": true
}

Mark as not voided

{
  "voided": false
}


Returned Values

If the pass has been updated successfully, HTTP status 204 (No Content) is returned.

Example Response

Success Response (204)

HTTP/1.1 204 No Content


Status Codes

  • Name
    204
    Type
    No Content
    (mandatory)
    Description

    Pass was successfully marked as voided/not voided.

  • Name
    401
    Type
    Unauthorized
    (mandatory)
    Description

    Invalid or missing API key, or attempting to access a pass from another customer.

  • Name
    404
    Type
    Not Found
    (mandatory)
    Description

    The specified pass does not exist.

Usage Example

This endpoint is particularly useful for event tickets. When an attendee enters the venue and their ticket is scanned, you can mark the pass as voided to prevent reuse.

Manage Flight Boarding Passes

When creating or updating flight boarding passes, specific flight-related fields are required in addition to the standard pass creation parameters.

Template Requirements:

  • Pass template must have passType set to boardingPass
  • Transit type must be set to PKTransitTypeAir for flight boarding passes
  • These fields are specifically for airline/flight boarding passes only

How to Use

See documentation of create or update pass endpoints above. This section explains the additional fields required for flight boarding passes.

Required Fields for Flight Boarding Pass

  • Name
    originAirportCode
    Type
    string
    (mandatory)
    Description

    A valid IATA code of the origin airport.

  • Name
    destinationAirportCode
    Type
    string
    (mandatory)
    Description

    A valid IATA code of the destination airport.

  • Name
    localScheduledDepartureTime
    Type
    string
    (mandatory)
    Description

    The local scheduled departure time in the format Y-m-dTH:i (e.g., 2023-07-01T15:00).

  • Name
    localBoardingDateTime
    Type
    string
    (mandatory)
    Description

    The local boarding date and time in the format Y-m-dTH:i.

  • Name
    passengerName
    Type
    string
    (mandatory)
    Description

    The name of the passenger.

  • Name
    carrierCode
    Type
    string
    (mandatory)
    Description

    A valid IATA code of the carrier.

  • Name
    confirmationCode
    Type
    string
    (mandatory)
    Description

    The confirmation code for this boarding pass.

  • Name
    flightNumber
    Type
    integer
    (mandatory)
    Description

    The flight number.

Example Required Fields

Required boarding pass fields

{
  "originAirportCode": "MUC",
  "destinationAirportCode": "LAX",
  "localScheduledDepartureTime": "2023-07-01T15:13",
  "localBoardingDateTime": "2023-07-01T17:19",
  "passengerName": "Jane Doe",
  "carrierCode": "LH",
  "confirmationCode": "ABC",
  "flightNumber": 738
}


Optional Fields for Flight Boarding Pass

  • Name
    originAirportGate
    Type
    string
    (optional)
    Description

    The gate at the origin airport (e.g., B16).

  • Name
    originAirportTerminal
    Type
    string
    (optional)
    Description

    The terminal at the origin airport (e.g., 2).

  • Name
    destinationAirportGate
    Type
    string
    (optional)
    Description

    The gate at the destination airport (e.g., A2).

  • Name
    destinationAirportTerminal
    Type
    string
    (optional)
    Description

    The terminal at the destination airport (e.g., E).

  • Name
    localEstimatedOrActualDepartureDateTime
    Type
    string
    (optional)
    Description

    The local estimated or actual departure date and time in the format Y-m-dTH:i.

  • Name
    localScheduledArrivalDateTime
    Type
    string
    (optional)
    Description

    The local scheduled arrival date and time in the format Y-m-dTH:i.

  • Name
    localEstimatedOrActualArrivalDateTime
    Type
    string
    (optional)
    Description

    The local estimated or actual arrival date and time in the format Y-m-dTH:i.

  • Name
    seatClass
    Type
    string
    (optional)
    Description

    The class of service (e.g., Business or Economy).

  • Name
    seatNumber
    Type
    string
    (optional)
    Description

    The seat number (e.g., 26A).

  • Name
    sequenceNumber
    Type
    string
    (optional)
    Description

    The sequence number for the passenger (e.g., 066).

  • Name
    boardingGroup
    Type
    string
    (optional)
    Description

    The boarding group (e.g., B).

  • Name
    boardingPosition
    Type
    string
    (optional)
    Description

    The boarding position (e.g., A13).

Complete Boarding Pass Example

Complete boarding pass request including all supported parameters

{
  "originAirportCode": "MUC",
  "originAirportGate": "B16",
  "originAirportTerminal": "2",
  "destinationAirportCode": "LAX",
  "destinationAirportGate": "A2",
  "destinationAirportTerminal": "E",
  "localScheduledDepartureTime": "2023-07-01T15:13",
  "localEstimatedOrActualDepartureDateTime": "2023-07-01T18:13",
  "localBoardingDateTime": "2023-07-01T17:19",
  "localScheduledArrivalDateTime": "2023-07-02T16:14",
  "localEstimatedOrActualArrivalDateTime": "2023-07-02T18:15",
  "passengerName": "Jane Doe",
  "seatClass": "Business",
  "seatNumber": "36C",
  "sequenceNumber": "066",
  "boardingGroup": "B",
  "boardingPosition": "A13",
  "carrierCode": "LH",
  "confirmationCode": "ABC",
  "flightNumber": 738
}


Usage Examples

Creating a Flight Boarding Pass

Use the standard create pass endpoint with the flight boarding pass fields included in the request body along with any standard pass parameters.

Remember to include zapierStyle=true parameter in the URL and all required flight boarding pass fields in the request body.

Updating a Flight Boarding Pass

To update a flight boarding pass, use the standard update pass endpoint with the boarding pass fields you want to update included in the request body.

You only need to include the fields you want to update. Unchanged fields will retain their existing values.

Example Requests

Create boarding pass (cURL)

curl -X POST "https://app.passcreator.com/api/pass?passtemplate={template-uid}&zapierStyle=true" \
  -H "Authorization: yourApiKeyHere" \
  -H "Content-Type: application/json" \
  -d '{
    "originAirportCode": "MUC",
    "destinationAirportCode": "LAX",
    "localScheduledDepartureTime": "2023-07-01T15:13",
    "passengerName": "Jane Doe",
    "carrierCode": "LH",
    "confirmationCode": "ABC",
    "flightNumber": 738,
    "seatNumber": "36C",
    "boardingGroup": "B",
    "userProvidedId": "BOARDING-001",
    "emailRecipient": "jane.doe@example.com"
  }'

Update boarding pass (cURL)

curl -X POST "https://app.passcreator.com/api/pass/{pass-uid}?zapierStyle=true" \
  -H "Authorization: yourApiKeyHere" \
  -H "Content-Type: application/json" \
  -d '{
    "originAirportGate": "B22",
    "localEstimatedOrActualDepartureDateTime": "2023-07-01T16:30",
    "seatNumber": "38A"
  }'


Important Notes for Flight Boarding Passes

  • Template Requirements: The pass template MUST be configured with passType: boardingPass and transitType: PKTransitTypeAir
  • All date/time fields should use the format Y-m-dTH:i (e.g., 2023-07-01T15:00)
  • Airport codes must be valid IATA codes
  • Carrier codes must be valid IATA airline codes
  • These flight boarding pass fields are in addition to all standard pass creation and update parameters
  • The boarding pass fields are added directly to the request body, not nested in a separate object
  • Grouping identifier is supported for flight boarding passes to group related tickets together
POST/api/pass/{pass-uid}/enabledownload

Enable Download of a Pass

If you have enabled the option on pass templates that prevents the download if a pass is already active, you can enable the download of the pass temporarily, even if the given pass is active already.

Path Parameters

  • Name
    pass-uid
    Type
    string
    (mandatory)
    Description

    UID of the pass you want to enable download for. This is part of the URL path.

Example Path Usage

URL with path parameter

https://app.passcreator.com/api/pass/f4379715-7a69-1742-38ae-836554724306/enabledownload


Authorization

  • Name
    Authorization
    Type
    string
    (mandatory)
    Description

    HTTP Authorization Header that contains your API key.

Example HTTP Header

HTTP header

POST /api/pass/f4379715-7a69-1742-38ae-836554724306/enabledownload HTTP/1.1
Host: app.passcreator.com
Authorization: yourApiKeyHere
Content-Type: application/json


Request Body

  • Name
    enableDownloadUntil
    Type
    string
    (optional)
    Description

    Default: 10 minutes from request time
    A date and time until the download should be possible. If you don't specify this parameter, the download will be enabled for ten minutes. Format: Y-m-d H:i (e.g., 2019-05-20 10:09).

Example Request

Request body

{
  "enableDownloadUntil": "2019-05-20 10:09"
}


Returned Values

If the pass has been found and the download is enabled successfully, HTTP status 204 (No Content) is returned with no response body.

Example Response

Success Response (204)

HTTP/1.1 204 No Content


Status Codes

  • Name
    204
    Type
    No Content
    (mandatory)
    Description

    Pass was found and download is enabled again.

  • Name
    401
    Type
    Unauthorized
    (mandatory)
    Description

    Invalid or missing API key.

  • Name
    404
    Type
    Not Found
    (mandatory)
    Description

    The specified pass does not exist.

Usage Notes

  • This endpoint is only useful if your pass template has download prevention enabled for active passes
  • The download will be temporarily enabled for the specified duration
  • If no duration is specified, download is enabled for 10 minutes from the request time
POST/api/pass/{pass-uid}/sendpushnotification

Push Notification to a Pass

Sends a push notification to an active pass.

Path Parameters

  • Name
    pass-uid
    Type
    string
    (mandatory)
    Description

    UID, userProvidedId, or barcode value of the pass that should receive the notification. This is part of the URL path.

Example Path Usage

URL with path parameter

https://app.passcreator.com/api/pass/f4379715-7a69-1742-38ae-836554724306/sendpushnotification


Authorization

  • Name
    Authorization
    Type
    string
    (mandatory)
    Description

    HTTP Header containing your API key.

Example HTTP Header

HTTP header

POST /api/pass/{pass-uid}/sendpushnotification HTTP/1.1
Host: app.passcreator.com
Authorization: yourApiKeyHere
Content-Type: application/json


Request Body

  • Name
    pushNotificationText
    Type
    string
    (mandatory)
    Description

    The text for the push notification. This may include placeholders of additional properties to personalise the message with existing data (e.g., {Firstname}).

Example Request

Request body

{
  "pushNotificationText": "Hi {Firstname}, how are you?"
}


Status Codes

  • Name
    204
    Type
    No Content
    (mandatory)
    Description

    The notification has been sent successfully.

  • Name
    304
    Type
    Not Modified
    (mandatory)
    Description

    The same notification text was already sent previously. The notification will not be sent again to avoid duplicate notifications.

  • Name
    400
    Type
    Bad Request
    (mandatory)
    Description

    The pass is not active, the pushNotificationText was empty, or is not set.

  • Name
    401
    Type
    Unauthorized
    (mandatory)
    Description

    Invalid or missing API key, or attempting to access a pass from another customer.

  • Name
    404
    Type
    Not Found
    (mandatory)
    Description

    The pass identifier is not known.

Usage Notes

  • The pass must be active (have at least one device registration) to receive push notifications
  • Property placeholders (e.g., {Firstname}) will be replaced with actual values from the pass data
  • The system prevents sending duplicate notifications with the same text to avoid spamming
POST/api/pass/sendpushnotifications

Push Notification to Multiple Passes

Sends a push notification to multiple passes at once. You can send notifications to up to 500 passes in a single request.

Authorization

  • Name
    Authorization
    Type
    string
    (mandatory)
    Description

    HTTP Authorization Header that contains your API key.

Example HTTP Header

HTTP header with authorization

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


Request Body

  • Name
    listOfPasses
    Type
    array<string>
    (mandatory)
    Description

    An array of pass identifiers that should receive the push notification. Each identifier can be a pass UID, userProvidedId, or barcode value. You can specify up to 500 identifiers in one request.

  • Name
    pushNotificationText
    Type
    string
    (mandatory)
    Description

    The text for the push notification. This may include placeholders of additional properties (e.g., {Firstname}) to personalise the message with existing data.

Example Request

Request body

{
  "listOfPasses": [
    "b1d972dc-eccf-4f87-ab21-25939d9213d8",
    "23443567-eccf-4f87-ab21-2435465789"
  ],
  "pushNotificationText": "Hi {Firstname}, how are you?"
}


Response Status Codes

  • Name
    202
    Type
    Accepted
    (mandatory)
    Description

    Push notifications have been scheduled successfully. Notifications are sent asynchronously.

  • Name
    400
    Type
    Bad Request
    (mandatory)
    Description

    The request is invalid. This occurs when:

    • More than 500 passes are specified
    • No passes are provided in the listOfPasses array
    • The listOfPasses array is empty
    • Required fields are missing
    • The pushNotificationText is empty
  • Name
    401
    Type
    Unauthorized
    (mandatory)
    Description

    Invalid or missing API key.

Usage Notes

  • Notifications are processed asynchronously
  • Maximum of 500 identifiers per request
  • Push notification text supports property placeholders for personalization
  • Invalid or non-existent identifiers are silently skipped (no error returned)
  • Duplicate notifications with the same text are automatically prevented
POST/api/pass/deliver/{identifier}/email/{recipientMail}

Send a Pass via Email

Sends an email with a pass to a specified recipient if an email template for ad hoc submission is configured for the pass template.

Path Parameters

  • Name
    identifier
    Type
    string
    (mandatory)
    Description

    The ID of an existing pass. This can be a pass UID, userProvidedId, or barcode value.

  • Name
    recipientMail
    Type
    string
    (mandatory)
    Description

    The email address of the recipient.

Example Path Usage

URL with path parameters

https://app.passcreator.com/api/pass/deliver/f4379715-7a69-1742-38ae-836554724306/email/john.doe@example.com
https://app.passcreator.com/api/pass/deliver/CUSTOMER-12345/email/jane@company.com


Authorization

  • Name
    Authorization
    Type
    string
    (mandatory)
    Description

    HTTP Authorization Header that contains your API key.

Example HTTP Header

HTTP header with authorization

POST /api/pass/deliver/f4379715-7a69-1742-38ae-836554724306/email/john.doe@example.com HTTP/1.1
Host: app.passcreator.com
Authorization: yourApiKeyHere


Response Status Codes

  • Name
    200
    Type
    OK
    (mandatory)
    Description

    The email has been sent successfully.

  • Name
    400
    Type
    Bad Request
    (mandatory)
    Description

    The request failed. This occurs when:

    • Email address is invalid
    • No email template for ad hoc submission is specified for the template of the pass
  • Name
    404
    Type
    Not Found
    (mandatory)
    Description

    No pass could be found with the specified identifier.

Usage Notes

  • An email template for ad hoc email submission must be defined for the pass template
  • The email will be sent using the configured template with the pass attached or linked
  • The recipient email address must be valid and properly formatted
DELETE/api/pass/{pass-uid}

Delete a Pass

Delete the pass with the given ID.

Path Parameters

  • Name
    pass-uid
    Type
    string
    (mandatory)
    Description

    UID, userProvidedId, or barcode value of the pass you want to delete. This is part of the URL path.

Example Path Usage

URL with path parameter

https://app.passcreator.com/api/pass/f4379715-7a69-1742-38ae-836554724306
https://app.passcreator.com/api/pass/CUSTOMER-12345
https://app.passcreator.com/api/pass/3897897988979823497234


Authorization

  • Name
    Authorization
    Type
    string
    (mandatory)
    Description

    HTTP Authorization Header that contains your API key.

Example HTTP Header

HTTP header

DELETE /api/pass/f4379715-7a69-1742-38ae-836554724306 HTTP/1.1
Host: app.passcreator.com
Authorization: yourApiKeyHere


Returned Values

If the pass has been deleted successfully, HTTP status 200 (OK) is returned.

Example Response

Success Response (200)

HTTP/1.1 200 OK


Status Codes

  • Name
    200
    Type
    OK
    (mandatory)
    Description

    Pass was successfully deleted.

  • Name
    401
    Type
    Unauthorized
    (mandatory)
    Description

    Invalid or missing API key, or attempting to access a pass from another customer.

  • Name
    404
    Type
    Not Found
    (mandatory)
    Description

    The specified pass does not exist.

Usage Notes

  • Deletion is permanent and cannot be undone