DOCS

Last updated: 3:11 PM - December 8, 2024

Login

Introduction toggle icon

Customers toggle icon

Wallet Pass Templates toggle icon

Wallet Pass (Users) toggle icon

Push Notifications toggle icon

Offers toggle icon

Analytics

User Wallet Passes

This object represents a wallet pass owned by a user. Use it to create, retrieve, update, or delete wallet passes and manage the pass details, including the appearance, status, and behavior of each pass in a user's digital wallet.

ENDPOINTS
  • POST /v1/wallet_passes
  • PATCH /v1/wallet_passes/:id
  • GET /v1/wallet_passes/:id
  • GET /v1/wallet_passes
  • DELETE /v1/wallet_passes/:id

The User Wallet Pass object

Attributes

id string

Unique identifier for the wallet pass (MongoDB ObjectID).

serialNumber string

Unique identifier for the pass.

pass_type string

Type of the pass (e.g., 'membership', 'event').

name string

Name of the wallet pass holder.

customerID string

ID of the customer who owns the wallet pass.

apnPushToken string

Apple Push Notification (APN) token for the customer's device.

passHolder string

The ID of the individual holding the pass.

creatorID string

ID of the user who created the pass.

passTemplateID string

ID of the wallet pass template used to create this pass.

status string

Status of the wallet pass (e.g., 'claimed', 'active').

metadata map

Additional metadata associated with the wallet pass.

created int64

Timestamp when the wallet pass was created.

updated_at int64

Timestamp of the last update to the wallet pass.

v integer

Version number of the wallet pass.

pass_json object

The complete pass structure.

The User Wallet Pass object
                    {
  "id": "890e8f60d3ff66832b0124f9",
  "serialNumber": "550e8400-e29b-41d4-a716-446655440000",
  "passType": "loyalty",
  "name": "John Doe",
  "customerID": "66c39410f772e80b520398fb",
  "apnPushToken": "abc123",
  "passHolder": "John Doe",
  "creatorID": "creator123",
  "passTemplateID": "template456",
  "status": "active",
  "metadata": {
  },
  "created": 1729006624,
  "updated_at": 1729006624,
  "v": 1,
}

Generate a Wallet Pass

This endpoint generates a new wallet pass using a specified pass template.

Required Parameters

passTemplateID string

The ID of the wallet pass template used to generate the pass.

customerID string

The ID of the customer for whom the pass is generated.

X-API-Key string

API key for authenticating the request.

Optional Parameters

Response Parameters

download_url string

A URL to download the generated wallet pass file (.pkpass format). This link provides access to the actual pass that can be added to a wallet application.

status string

Indicates the status of the pass generation request. Expected values include 'success' for a successful creation or 'error' if there was a problem generating the pass.

userPassID string

A unique identifier for the generated user pass. This ID can be used to reference the pass in future operations, such as updates or tracking.

POST v1/wallet-passes/create 
curl -L 'https://api.gowithpush.com/wallet-passes/create' \
  
-H 'Content-Type: application/json' \
  
-H 'X-API-Key: 1ad2aaa2958064e116e24d25dd0fe800' \
  
-d '{
    "passTemplateID": "671ff9f9643ac63dc7decf7e",
    "customerID": "66cd471f5efb4a24dd3456f2"
  }'

RESPONSE

{
    "download_url": "https://d1sppi04ftcdzp.cloudfront.net/wallet-passes/671fff866ade1a8edfe888c4.pkpass",
    "status": "success",
    "userPassID": "671fff866ade1a8edfe888c4"
  }

Retrieve a User Wallet Pass

This endpoint retrieves a paginated list of wallet pass template objects.

Required Parameters

userID string

The ID of the user requesting the wallet pass templates.

X-API-Key string

API Key for authenticating the request.

Optional Parameters

page integer

The page number of the paginated results. Default is 1.

per_page integer

The number of results per page. Default is 25.

GET /v1/wallet_passes/:id 
curl --location 'https://api.gowithpush.com/v1/wallet_passes/:id'   
-H 'userID: 66abe34930ac8b1edfd40a96'   
-H 'X-API-Key: <YOUR-API-KEY>'

RESPONSE

{
    "pass": {
        "id": "671fff866ade1a8edfe888c4",
        "pass_json": {
            "description": "So Hot it's supa",
            "formatVersion": 1,
            "organizationName": "SupaFireLLC",
            "passTypeIdentifier": "pass.studio.keyspace.push",
            "webServiceURL": "https://ksb-wallet-pass.keyspacestudio.tech",
            "authenticationToken": "igefwsdhiryiew9r9832uyerigewifOCR37wu3ryoc7t82tpr9VWq3Glawtlr3ac893tarwlegliai",
            "serialNumber": "671fff866ade1a8edfe888c4",
            "groupingIdentifier": "662eacdd93c3237c5873dc20",
            "teamIdentifier": "BNQD3U7A97",
            "foregroundColor": "rgb(200, 200, 200)",
            "backgroundColor": "rgb(255, 117, 117)",
            "logoText": "SupaHot",
            "barcodes": [
                {
                    "message": "671fff866ade1a8edfe888c4",
                    "format": "PKBarcodeFormatQR",
                    "messageEncoding": "iso-8859-1"
                }
            ],
            "strip": "strip.png",
            "logo": "logo.png",
            "storeCard": {
                "primaryFields": [
                    {
                        "key": "membership_id",
                        "label": "",
                        "value": " ",
                        "changeMessage": "%@"
                    }
                ],
                "backFields": [
                    {
                        "key": "f205207e-e005-447c-bd91-512187d5c521",
                        "label": "View Offers",
                        "value": "<a href="https://ks-pages-119byl.web.app/671ff9f9643ac63dc7decf7e/offers">🔗 Visit</a>",
                        "changeMessage": "%@"
                    },
                    {
                        "key": "lastMessage",
                        "label": "Last Message",
                        "value": "Powered by Keyspace",
                        "changeMessage": "%@"
                    }
                ],
                "auxiliaryFields": [
                    {
                        "key": "last_updated",
                        "label": "Last Updated",
                        "value": "10/28/2024",
                        "changeMessage": "%@"
                    }
                ],
                "secondaryFields": [
                    {
                        "key": "membership_id",
                        "label": "Membership ID",
                        "value": "6506096",
                        "changeMessage": "%@"
                    }
                ]
            }
        },
        "pass_type": "membership",
        "serialNumber": "671fff866ade1a8edfe888c4",
        "name": "",
        "apn_push_token": "",
        "pass_holder": "",
        "creatorID": "662eacdd93c3237c5873dc20",
        "passTemplateID": "671ff9f9643ac63dc7decf7e",
        "status": "generated",
        "metadata": {
            "download_link": "https://ksb-push.media.s3.amazonaws.com/wallet-passes/671ff9f9643ac63dc7decf7e.pkpass"
        },
        "created": 1730150278,
        "updated_at": 1730150278,
        "v": 1
    },
    "status": "success"
}

Retrieve User Wallet Pass List

This endpoint retrieves a paginated list of wallet pass template objects.

Required Parameters

userID string

The ID of the user requesting the wallet pass templates.

X-API-Key string

API Key for authenticating the request.

Optional Parameters

page integer

The page number of the paginated results. Default is 1.

per_page integer

The number of results per page. Default is 25.

GET /v1/wallet_passes/:id 
curl --location 'https://api.gowithpush.com/v1/wallet_passes/:id'   
-H 'userID: 66abe34930ac8b1edfd40a96'   
-H 'X-API-Key: <YOUR-API-KEY>'

RESPONSE

{
    "pagination": {
        "current_page": 1,
        "has_next": true,
        "has_prev": false,
        "per_page": 10,
        "total_items": 36,
        "total_pages": 4
    },
    "passes": [
        "id": "671fff866ade1a8edfe888c4",
        "pass_json": {
            "description": "So Hot it's supa",
            "formatVersion": 1,
            "organizationName": "SupaFireLLC",
            "passTypeIdentifier": "pass.studio.keyspace.push",
            "webServiceURL": "https://ksb-wallet-pass.keyspacestudio.tech",
            "authenticationToken": "igefwsdhiryiew9r9832uyerigewifOCR37wu3ryoc7t82tpr9VWq3Glawtlr3ac893tarwlegliai",
            "serialNumber": "671fff866ade1a8edfe888c4",
            "groupingIdentifier": "662eacdd93c3237c5873dc20",
            "teamIdentifier": "BNQD3U7A97",
            "foregroundColor": "rgb(200, 200, 200)",
            "backgroundColor": "rgb(255, 117, 117)",
            "logoText": "SupaHot",
            "barcodes": [
                {
                    "message": "671fff866ade1a8edfe888c4",
                    "format": "PKBarcodeFormatQR",
                    "messageEncoding": "iso-8859-1"
                }
            ],
            "strip": "strip.png",
            "logo": "logo.png",
            "storeCard": {
                "primaryFields": [
                    {
                        "key": "membership_id",
                        "label": "",
                        "value": " ",
                        "changeMessage": "%@"
                    }
                ],
                "backFields": [
                    {
                        "key": "f205207e-e005-447c-bd91-512187d5c521",
                        "label": "View Offers",
                        "value": "<a href="https://ks-pages-119byl.web.app/671ff9f9643ac63dc7decf7e/offers">🔗 Visit</a>",
                        "changeMessage": "%@"
                    },
                    {
                        "key": "lastMessage",
                        "label": "Last Message",
                        "value": "Powered by Keyspace",
                        "changeMessage": "%@"
                    }
                ],
                "auxiliaryFields": [
                    {
                        "key": "last_updated",
                        "label": "Last Updated",
                        "value": "10/28/2024",
                        "changeMessage": "%@"
                    }
                ],
                "secondaryFields": [
                    {
                        "key": "membership_id",
                        "label": "Membership ID",
                        "value": "6506096",
                        "changeMessage": "%@"
                    }
                ]
            }
        },
        "pass_type": "membership",
        "serialNumber": "671fff866ade1a8edfe888c4",
        "name": "",
        "apn_push_token": "",
        "pass_holder": "",
        "creatorID": "662eacdd93c3237c5873dc20",
        "passTemplateID": "671ff9f9643ac63dc7decf7e",
        "status": "generated",
        "metadata": {
            "download_link": "https://ksb-push.media.s3.amazonaws.com/wallet-passes/671ff9f9643ac63dc7decf7e.pkpass"
        },
        "created": 1730150278,
        "updated_at": 1730150278,
        "v": 1
    }
  ]
    "status": "success"
}
Provide additional feedback