1. Home
  2. /Developer
  3. /REST APIs
  4. /Wallet API
  5. /Operations
  6. /Tags

Tags

Tags are plain-text identifiers for passes. Use tags to identify passes for segmentation purposes, or to target an audience of passes for updates.

Tags are limited to 15 per pass.

Add tags to pass

Add tags to a pass, limited to 15 tags per pass.

Jump to examples ↓

PUT /pass/{passId}/tags

Security:

Request headers:

  • Api-Revision stringREQUIRED
    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

Path parameters:

  • passId stringREQUIRED
    The ID of the pass you want to add tags to. For External IDs, format the {passId} as id/{externalId}.

Request body:

An array of tags that you want to associate with the pass.

  • Content-Type: application/json

    Add Tags to PassRequest

    An array of tags that you want to add to a pass.

    OBJECT PROPERTIES
    • tags array[string]REQUIRED

      An array of strings, each string representing a tag.

Responses

  • 200

    Lists the tags added to the pass.

    Response body:

    • Content-Type: application/json
      OBJECT PROPERTIES
      • mappings integer

        The number of tags added.

      • newTags array[string]

        A list of tags successfully added to the pass.

Examples

Example request

PUT /v1/pass/123/tags HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
Api-Revision: 1.2

{
    "tags": ["tag-name"]
}

Example request with external ID

PUT /v1/pass/id/mypass/tags HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
Api-Revision: 1.2

{
    "tags": ["tag-name"]
}

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "newTags": ["tag-name"],
  "mappings": 1
}

Delete tag

Delete the specified tag and remove it from all passes.

Jump to examples ↓

DELETE /tag/{tag}

Security:

Request headers:

  • Api-Revision stringREQUIRED
    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

Path parameters:

  • tag stringREQUIRED
    The tag you want to delete.

Responses

  • 200

    A successful operation returns a count of affected passes.

    Response body:

    • Content-Type: application/json
      OBJECT PROPERTIES
      • count integer

        The number of passes the tag was removed from.

      • status string

        The operation was successful.

        Possible values: success

      • tagId integer

        The ID of the deleted tag.

Examples

Example request

DELETE /v1/tag/tag-name HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2

Response

HTTP/1.1 200 OK
Content-Type: application/json

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

List all tags

List all tags.

Jump to examples ↓

GET /tag

Security:

Query parameters:

  • pageSize integer
    The number of tags per page. Defaults to 10.

    Default: 10

  • page integer
    The page of results you want to retrieve, starting at 1.

    Default: 1

  • order string
    The order you want tags returned in, defaulting to id.

    Possible values: id, createdAt

    Default: id

  • direction string
    Determines whether to return values in ascending or descending order. Defaults to DESC.

    Possible values: ASC, DESC

    Default: DESC

Request headers:

  • Api-Revision stringREQUIRED
    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

Responses

  • 200

    A paginated array of tags.

    Response body:

    • Content-Type: application/json
      OBJECT PROPERTIES
      • Pagination object<Pagination object>

        Contains information about pagination, according to your query parameters.

      • count integer

        The number of items returned.

      • tags array[object]

Examples

Example request

GET /v1/tag HTTP/1.1
Authorization: Basic <Base64 Key>
Api-Revision: 1.2

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "tags": [
    {
      "id": 2,
      "tag": "Gold",
      "createdAt": "2018-03-02T23:49:53Z"
    },
    {
      "id": 3,
      "tag": "Silver",
      "createdAt": "2018-03-02T23:49:53Z"
    },
    {
      "id": 4,
      "tag": "Platinum",
      "createdAt": "2018-03-02T23:49:53Z"
    },
    {
      "id": 5,
      "tag": "Enterprise",
      "createdAt": "2018-03-02T23:49:53Z"
    }
  ],
  "Pagination": {
    "order": "ID",
    "page": 1,
    "start": 0,
    "direction": "DESC",
    "pageSize": 10
  },
  "count": 4
}

List passes for a tag

List the passes associated with the specified tag.

Jump to examples ↓

GET /tag/{tag}/passes

Security:

Query parameters:

  • status string

    Find only passes matching the installation status.

    • installed — passes currently installed.
    • uninstalled — passes that have been uninstalled.
    • been_installed — passes that have been either installed or uninstalled.
    • not_been_installed — passes that have never been installed.

    Possible values: installed, uninstalled, been_installed, not_been_installed

  • pageSize integer
    The number of passes per page. Defaults to 10.

    Default: 10

  • page integer
    The page of results you want to retrieve, starting at 1.

    Default: 1

  • order string
    The order you want tags returned in, defaulting to id.

    Possible values: id, createdAt, updatedAt

    Default: id

  • direction string
    Determines whether to return values in ascending or descending order. Defaults to DESC.

    Possible values: ASC, DESC

    Default: DESC

Request headers:

  • Api-Revision stringREQUIRED
    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

Path parameters:

  • tag stringREQUIRED
    A tag id or name. The request returns a paginated list of passes associated with the specified tag.

Responses

  • 200

    A successful response returns a paginated array of passes.

    Response body:

    • Content-Type: application/json
      OBJECT PROPERTIES
      • count integer

        The total number of results.

      • pagination object<Pagination object>

        Contains information about pagination, according to your query parameters.

      • passes object

        Meta information about passes.

        OBJECT PROPERTIES
        • createdAt string

          The date and time when the item was last updated.

        • id integer

          The internal identifier for the pass. Use this ID to get or modify the pass in other calls.

        • installedAt string

          The date and time when pass was first installed on the device.

        • platform string

          Wallet platform.

          Possible values: iOS, Android

        • serialNumber string

          The serial number of the pass.

        • status string

          Recent on-device pass status.

          Possible values: installed, uninstalled, not_been_installed

        • templateId integer

          The identifier for the template. You can recall the template by ID in other operations.

        • uninstalledAt string

          The date and time when pass was uninstalled on the device. This value is only set if pass status is uninstalled.

        • updatedAt string

          The date and time when the item was created.

        • url string

          Pass download URL.

Examples

Example request

GET /v1/tag/tag-name/passes HTTP/1.1
Authorization: Basic <Base64 Key>
Api-Revision: 1.2

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
          "passes": [{
              "id": 61,
              "templateId": 1000057,
              "url": "https://d720-104-177-34-165.ngrok.io/v1/pass/61/download",
              "serialNumber": "aff7ffbf-04d7-4180-9da2-c790e08da012",
              "createdAt": "2023-04-19T06:15:01.000Z",
              "updatedAt": "2023-04-19T06:15:01.000Z",
              "status": "installed",
              "installedAt": "2023-04-19T06:17:02.000Z",
              "platform": "android"
            },
            {
              "id": 51,
              "templateId": 1000081,
              "url": "https://d720-104-177-34-165.ngrok.io/v1/pass/51/download",
              "serialNumber": "34b6f9de-3745-4107-99ae-3f952208e223",
              "createdAt": "2023-04-05T17:55:23.000Z",
              "updatedAt": "2023-04-05T17:55:23.000Z",
              "status": "installed",
              "installedAt": "2023-04-05T17:55:23.000Z",
              "platform": "ios"
            }
          ],
          "pagination": {
            "order": "id",
            "direction": "desc",
            "page": 1,
            "start": 0,
            "pageSize": 2
          }
}

List tags for pass

List tags assigned to the specified pass. See also List tags for pass with external ID.

Jump to examples ↓

GET /pass/{passId}/tags

Security:

Request headers:

  • Api-Revision stringREQUIRED
    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

Path parameters:

  • passId stringREQUIRED
    The ID of the pass you want to list tags for.

Responses

  • 200

    An array of tags belonging to the pass.

    Response body:

    • Content-Type: application/json
      OBJECT PROPERTIES
      • tags array[object]

        An array of tags associated with the pass.

Examples

Example request

GET /v1/pass/123/tags HTTP/1.1
Authorization: Basic <Base64 Key>
Api-Revision: 1.2

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "tags": [
    {
      "id": 72,
      "createdAt": "2013-07-10T11:38:06Z",
      "name": "tag-2971-4280-479"
    },
    {
      "id": 73,
      "createdAt": "2013-07-10 11:52:20Z",
      "name": "tag-1049-2951-9529"
    },
    {
      "id": 74,
      "createdAt": "2013-07-10 11:59:32Z",
      "name": "tag-385-9612-723"
    },
    {
      "id": 75,
      "createdAt": "2013-07-10 12:00:18Z",
      "name": "tag-5784-6282-8767"
    },
    {
      "id": 76,
      "createdAt": "2013-07-10 12:00:55Z",
      "name": "tag-1050-1982-8211"
    },
    {
      "id": 77,
      "createdAt": "2013-07-10 12:02:09Z",
      "name": "tag-5040-8715-7744"
    }
  ]
}

List tags for pass with external ID

List tags assigned to the specified pass. See also List tags for pass.

Jump to examples ↓

GET /pass/template/{templateId}/id/{passExternalId}/tags

Security:

Request headers:

  • Api-Revision stringREQUIRED
    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

Path parameters:

  • templateId stringREQUIRED
    The template of the pass that you want to get tags for.
  • passExternalId stringREQUIRED
    The external ID of the pass you want to list tags for.

Responses

  • 200

    An array of tags belonging to the pass.

    Response body:

    • Content-Type: application/json
      OBJECT PROPERTIES
      • tags array[object]

        An array of tags associated with the pass.

Examples

Example request

GET /v1/pass/template/123/id/mypass/tags HTTP/1.1
Authorization: Basic <Base64 Key>
Api-Revision: 1.2

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "tags": [
    {
      "id": 72,
      "createdAt": "2013-07-10T11:38:06Z",
      "name": "tag-2971-4280-479"
    },
    {
      "id": 73,
      "createdAt": "2013-07-10 11:52:20Z",
      "name": "tag-1049-2951-9529"
    },
    {
      "id": 74,
      "createdAt": "2013-07-10 11:59:32Z",
      "name": "tag-385-9612-723"
    },
    {
      "id": 75,
      "createdAt": "2013-07-10 12:00:18Z",
      "name": "tag-5784-6282-8767"
    },
    {
      "id": 76,
      "createdAt": "2013-07-10 12:00:55Z",
      "name": "tag-1050-1982-8211"
    },
    {
      "id": 77,
      "createdAt": "2013-07-10 12:02:09Z",
      "name": "tag-5040-8715-7744"
    }
  ]
}

Remove tag from a pass

Remove a tag from the specified pass.

Jump to examples ↓

DELETE /tag/{tag}/pass/{pass}

Security:

Request headers:

  • Api-Revision stringREQUIRED
    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

Path parameters:

  • tag stringREQUIRED
    The tag you want to remove from the pass.
  • pass stringREQUIRED
    The pass you want to remove the tag from. For External IDs, format the {pass} as id/{externalId}.

Responses

  • 200

    A successful response includes the ID of the removed tag and the ID of the pass it was removed from.

    Response body:

    • Content-Type: application/json
      OBJECT PROPERTIES
      • passId integer

        The ID of the pass that the tag was removed from.

      • status string

        The operation was successful.

        Possible values: success

      • tagId integer

        The ID of the removed tag.

Examples

Example request

DELETE /v1/tag/tag-name/pass/123 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2

Example request with external ID

DELETE /v1/tag/tag-name/pass/id/123 HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
   "passId": 123,
   "status": "success",
   "tagId": 70
}

Remove tag from all passes

Remove a tag from all of its passes.

Jump to examples ↓

DELETE /tag/{tag}/passes

Security:

Request headers:

  • Api-Revision stringREQUIRED
    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

Path parameters:

  • tag stringREQUIRED
    The tag you want to remove.

Responses

  • 200

    A successful response returns a count of the affected passes.

    Response body:

    • Content-Type: application/json
      OBJECT PROPERTIES
      • count integer

        The number of passes the tag was removed from.

      • status string

        The operation was successful.

        Possible values: success

      • tagId integer

        The ID of the deleted tag.

Examples

Example request

DELETE /v1/tag/tag-name/passes HTTP/1.1
Authorization: Basic <Base64 key>
Api-Revision: 1.2

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
   "count": 38,
   "status": "success",
   "tagId": 2
}

Update passes by tag

Update all of the passes that have a given tag.

Jump to examples ↓

PUT /tag/{tag}/passes

Security:

Request headers:

  • Api-Revision stringREQUIRED
    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

Path parameters:

  • tag stringREQUIRED
    The tag associated with the passes you want to update.

Request body:

Provide only the fields you want to update.

  • Content-Type: application/json

    OBJECT PROPERTIES
    • fields object

Responses

  • 200

    A successful request returns a ticketId.

    Response body:

    • Content-Type: application/json
      OBJECT PROPERTIES
      • ticketId integer

Examples

Example request

PUT /v1/tag/tag-name/passes HTTP/1.1
Authorization: Basic <Base64 key>
Content-Type: application/json
Api-Revision: 1.2

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

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
   "ticketId": 123
}

Update tags for pass with external ID

Assign or update tags on a pass with an external ID.

Jump to examples ↓

PUT /pass/template/{templateId}/id/{passExternalId}/tags

Security:

Request headers:

  • Api-Revision stringREQUIRED
    The particular API revision you want to use. In general, this is 1.2.

    Possible values: 1.2

Path parameters:

  • templateId stringREQUIRED
    The template of the pass that you want to apply tags to.
  • passExternalId stringREQUIRED
    The external ID of the pass you want to apply tags to.

Request body:

An array of tags that you want to associate with the pass.

  • Content-Type: application/json

    Add Tags to PassRequest

    An array of tags that you want to add to a pass.

    OBJECT PROPERTIES
    • tags array[string]REQUIRED

      An array of strings, each string representing a tag.

Responses

  • 200

    Lists the tags added to the pass.

    Response body:

    • Content-Type: application/json
      OBJECT PROPERTIES
      • mappings integer

        The number of tags added.

      • newTags array[string]

        A list of tags successfully added to the pass.

  • 404

    The pass or template ID does not exist.

Examples

Example request

PUT /v1/pass/template/123/id/mypass/tags HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>
Api-Revision: 1.2

{
    "tags": ["tag-name"]
}

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "newTags": ["tag-name"],
  "mappings": 1
}