🚀

Quick Start

Get up and running with the Zaki-Pass API in five steps. This guide walks you through creating your first wallet pass from scratch.

Base URL

https://api.zakipass.com/api/v1

Get Your API Key

Create an API key from the dashboard Settings page. Navigate to Settings > API Keys and generate a new key with the scopes you need. Your key will start with the zk_ prefix.

Test your key by fetching your templates:

bash

curl -X GET https://api.zakipass.com/api/v1/templates \
  -H "X-API-Key: zk_your_key_here"

Create a Template

Templates define the structure and design of your wallet passes. A template specifies the colors, fields, and layout that all passes issued from it will share.

Using cURL:

bash

curl -X POST https://api.zakipass.com/api/v1/templates \
  -H "X-API-Key: zk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "VIP Loyalty Card",
    "type": "LOYALTY",
    "description": "Premium loyalty card for top customers",
    "colors": {
      "background": "#1a1a2e",
      "foreground": "#ffffff",
      "accent": "#e94560"
    },
    "fieldsConfig": [
      { "key": "points", "label": "Points", "type": "number" },
      { "key": "tier", "label": "Tier", "type": "string" }
    ]
  }'

Using Node.js:

javascript

const response = await fetch('https://api.zakipass.com/api/v1/templates', {
  method: 'POST',
  headers: {
    'X-API-Key': 'zk_your_key_here',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'VIP Loyalty Card',
    type: 'LOYALTY',
    description: 'Premium loyalty card for top customers',
    colors: {
      background: '#1a1a2e',
      foreground: '#ffffff',
      accent: '#e94560',
    },
    fieldsConfig: [
      { key: 'points', label: 'Points', type: 'number' },
      { key: 'tier', label: 'Tier', type: 'string' },
    ],
  }),
});

const template = await response.json();
console.log('Template ID:', template._id);

Publish the Template

Templates must be published before they can be used to issue passes. Publishing locks the template configuration and makes it available for pass issuance.

bash

curl -X POST https://api.zakipass.com/api/v1/templates/TEMPLATE_ID/publish \
  -H "X-API-Key: zk_your_key_here"

Issue a Pass

Issuing a pass creates a wallet pass for a specific user based on your published template. Each pass gets a unique smart URL that auto-detects whether the user is on Apple or Google and serves the correct wallet format.

bash

curl -X POST https://api.zakipass.com/api/v1/passes/issue \
  -H "X-API-Key: zk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "TEMPLATE_ID",
    "userName": "Ahmad Al-Mansour",
    "userEmail": "ahmad@example.com",
    "payload": {
      "points": 500,
      "tier": "Gold"
    }
  }'

The response contains a smartUrl that automatically detects Apple or Google Wallet:

json

{
  "_id": "pass_abc123",
  "templateId": "TEMPLATE_ID",
  "userName": "Ahmad Al-Mansour",
  "userEmail": "ahmad@example.com",
  "smartUrl": "https://pass.zakipass.com/s/abc123",
  "payload": {
    "points": 500,
    "tier": "Gold"
  },
  "status": "active",
  "createdAt": "2026-02-05T12:00:00.000Z"
}

Send to User

The smartUrl can be sent to your user via email, SMS, or embedded in a QR code. When the user opens the link, it detects their device and adds the pass to Apple Wallet or Google Wallet automatically.

Conceptual example — sending the pass link via email:

javascript

// Conceptual example: send the pass link via email
const pass = await response.json();

await sendEmail({
  to: pass.userEmail,
  subject: 'Your VIP Loyalty Card is ready!',
  html: `
    <h1>Welcome, ${pass.userName}!</h1>
    <p>Your loyalty card is ready. Tap the link below to add it to your wallet:</p>
    <a href="${pass.smartUrl}">Add to Wallet</a>
  `,
});

console.log('Pass sent to', pass.userEmail);

Next Steps

Now that you have issued your first pass, dive deeper into the API:

🔐

Authentication deep dive