API Reference

The WalletHero API is a RESTful API that allows you to create and manage mobile wallet passes for Apple Wallet and Google Wallet.

Prefer using TypeScript?

Check out the TypeScript SDK for a more convenient way to integrate with WalletHero. The SDK provides type-safe methods, automatic error handling, and a simpler developer experience.

→ Get started with the SDK

Base URL

https://api.wallethero.app

API Versioning

The API is versioned through the URL path. All endpoints documented here are part of the current stable version.

Content Type

All API requests must use JSON for request and response bodies:

Content-Type: application/json
Accept: application/json

Authentication

The API uses Bearer token authentication. Include your API token in the Authorization header:

Authorization: Bearer your-api-token

See the Authentication Guide for details on obtaining and managing API tokens.

Response Format

Successful Responses

Single item responses:

{
  "data": {
    "id": "uuid",
    "name": "Example",
    // ... other fields
  }
}

List responses:

{
  "data": [
    { "id": "uuid-1", "name": "Item 1" },
    { "id": "uuid-2", "name": "Item 2" }
  ],
  "meta": {
    "total_count": 100,
    "filter_count": 50
  }
}

Error Responses

{
  "errors": [
    {
      "message": "Error description",
      "extensions": {
        "code": "ERROR_CODE"
      }
    }
  ]
}

Rate Limiting

API requests are rate limited to ensure fair usage. Current limits:

• Standard: 100 requests per minute
• Batch operations: 10 requests per minute

Rate limit headers are included in responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640000000

Endpoints Overview

All WalletHero endpoints are dedicated routes served by the wallethero-api extension and are prefixed with /wallethero-api. The SDK, frontend, and mobile apps call these dedicated endpoints — not the generic Directus /items/* REST collection routes. The only Directus-native routes used are the auth flow (/auth/login, /auth/refresh, /auth/logout) and file upload / asset delivery for pass-template images (POST /files, GET /assets/:id).

Most endpoints are workspace-scoped and require the caller to be a member of the target workspace. A subset is public or uses a scoped session token (the public loyalty portal, the embeddable distribution widget, SSO, and the mobile-app pairing flow).

Area	Base path	Reference
Auth & account	/wallethero-api/register, /wallethero-api/user/*	Auth
Workspaces & members	/wallethero-api/workspace/*	Workspaces
System admin (platform)	/wallethero-api/system/*	System Admin
Clients	/wallethero-api/workspace/:workspaceId/clients/*	Clients
Pass templates	/wallethero-api/workspace/:workspaceId/pass-templates, /wallethero-api/pass-templates/:id	Pass Templates
Passes	/wallethero-api/workspace/:workspaceId/passes, /wallethero-api/passes/:id	Passes
Segments	/wallethero-api/workspace/:workspaceId/segments, /wallethero-api/segments/*	Segments
Campaigns	/wallethero-api/workspace/:workspaceId/campaigns, /wallethero-api/campaigns/*	Campaigns
Events	/wallethero-api/events/*	Events
Loyalty (config, points, wallets)	/wallethero-api/workspace/:workspaceId/loyalty/*	Loyalty
Tiers	/wallethero-api/workspace/:workspaceId/tiers/*	Tiers
Rewards	/wallethero-api/workspace/:workspaceId/rewards/*	Rewards
Referrals	/wallethero-api/workspace/:workspaceId/referral*	Referrals
Automations	/wallethero-api/workspace/:workspaceId/automations/*	Automations
Transactions	/wallethero-api/transactions/*	Transactions
Distributions	/wallethero-api/workspace/:workspaceId/distributions, /wallethero-api/distribution/*	Distributions
Projects	/wallethero-api/workspace/:workspaceId/projects, /wallethero-api/projects/*	Projects
Reports	/wallethero-api/workspace/:workspaceId/reports/*	Reports
Webhooks	/wallethero-api/workspace/:workspaceId/webhooks/*	Webhooks
Integrations	/wallethero-api/workspace/:workspaceId/integrations/*	Integrations
Notifications	/wallethero-api/notifications/*, /wallethero-api/public/loyalty/notifications/*	Notifications
iOS certificates	/wallethero-api/workspace/:workspaceId/certificates/*	Certificates
Mobile app	/wallethero-api/mobile-app/*, /wallethero-api/workspace/:workspaceId/mobile-app*	Mobile App
Public loyalty portal	/wallethero-api/public/loyalty/*	Public Loyalty
Data model (custom fields)	/wallethero-api/workspace/:workspaceId/data-model/*	Data Model
Other & internal	/wallethero-api/workspace/:workspaceId/settings, /wallethero-api/auth/sso, …	Other & Internal

SDK

For a more convenient integration, use our TypeScript SDK:

import { WalletHero } from '@wallethero/sdk';

const client = new WalletHero({
  apiToken: 'your-api-token'
});

// List all pass templates
const templates = await client.passTemplates.list({
  filter: { workspace_id: { _eq: 'your-workspace-id' } }
});