Campaigns API

Campaigns are the primary resource in the API — all recipients and wallet cards are organized under campaigns.

List Campaigns

GET

/campaigns

Required scope: campaigns:read

Retrieve a list of campaigns for your organization.

Query Parameters

Parameter	Type	Required	Description
`limit`	integer	No	Maximum results (1-100, default: 20)
`offset`	integer	No	Number of results to skip (default: 0)
`status`	string	No	Filter by status: `draft`, `active`, `completed`, `archived`
`campaignType`	string	No	Filter by type: `event`, `coupon`, `loyalty`, `access`, `generic`

Response

{
  "success": true,
  "data": {
    "campaigns": [
      {
        "id": "campaign_abc123",
        "name": "Tech Conference 2025",
        "campaignType": "event",
        "status": "active",
        "createdAt": "2025-12-01T10:00:00Z"
      }
    ],
    "pagination": {
      "total": 10,
      "limit": 20,
      "offset": 0,
      "hasMore": false
    }
  }
}

Create Campaign

POST

/campaigns

Required scope: campaigns:write

Create a new campaign. Campaigns are the primary resource in the API.

Request Parameters

Parameter	Type	Required	Description
`name`	string	Yes	Campaign name
`campaignType`	string	Yes	Type: `event`, `coupon`, `loyalty`, `access`, `generic`
`campaignData`	object	Yes	Campaign-specific data (inherited by recipients)
`campaignData.barcodeType`	string	No	Barcode type: `none`, `qr` (default), `aztec`, `pdf417`, `code128`
`campaignData.barcodeValueStrategy`	string	No	Barcode value strategy: `auto` (default) or `custom`
`startDate`	string	No	Start date (ISO 8601 format: YYYY-MM-DD)
`endDate`	string	No	End date (ISO 8601 format: YYYY-MM-DD). For single-day events the platform may persist `startDate + 1` day when not split.
`timezone`	string	No	IANA timezone (e.g. `Europe/Amsterdam`); merged into `campaignData.timezone` (default `UTC`)
`providerTypes`	array	No	Providers: `["all"]`, `["apple"]`, `["google"]`, `["eudiw"]` (default: `["all"]`)
`metadata`	object	No	Custom metadata (key-value pairs)

curl -X POST https://api.walletwerk.eu/api/v1/campaigns \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Tech Conference 2025",
    "campaignType": "event",
    "campaignData": {
      "location": "San Francisco Convention Center",
      "barcodeType": "qr",
      "barcodeValueStrategy": "auto"
    },
    "startDate": "2025-12-15",
    "endDate": "2025-12-17",
    "providerTypes": ["all"]
  }'

const response = await fetch('https://api.walletwerk.eu/api/v1/campaigns', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Tech Conference 2025',
    campaignType: 'event',
    campaignData: {
      location: 'San Francisco Convention Center',
      barcodeType: 'qr',
      barcodeValueStrategy: 'auto'
    },
    startDate: '2025-12-15',
    endDate: '2025-12-17',
    providerTypes: ['all']
  })
});

const data = await response.json();

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
}

payload = {
    'name': 'Tech Conference 2025',
    'campaignType': 'event',
    'campaignData': {
        'location': 'San Francisco Convention Center',
        'barcodeType': 'qr',
        'barcodeValueStrategy': 'auto'
    },
    'startDate': '2025-12-15',
    'endDate': '2025-12-17',
    'providerTypes': ['all']
}

response = requests.post(
    'https://api.walletwerk.eu/api/v1/campaigns',
    headers=headers,
    json=payload
)
data = response.json()

Response

{
  "success": true,
  "data": {
    "id": "campaign_abc123",
    "name": "Tech Conference 2025",
    "campaignType": "event",
    "status": "active",
    "campaignData": {
      "location": "San Francisco Convention Center",
      "barcodeType": "qr",
      "barcodeValueStrategy": "auto"
    },
    "startDate": "2025-12-15",
    "endDate": "2025-12-17",
    "eventStartsAt": "2025-12-15T17:00:00.000Z",
    "eventEndsAt": "2025-12-16T17:00:00.000Z",
    "providerTypes": ["all"],
    "createdAt": "2025-12-01T10:00:00Z",
    "updatedAt": "2025-12-01T10:00:00Z"
  }
}

Get Campaign

GET

/campaigns/{campaignId}

Required scope: campaigns:read

Retrieve details of a specific campaign.

Response

{
  "success": true,
  "data": {
    "id": "campaign_abc123",
    "name": "Tech Conference 2025",
    "campaignType": "event",
    "status": "active",
    "campaignData": {
      "location": "San Francisco Convention Center",
      "barcodeType": "qr",
      "barcodeValueStrategy": "auto"
    },
    "startDate": "2025-12-15",
    "endDate": "2025-12-17",
    "eventStartsAt": "2025-12-15T17:00:00.000Z",
    "eventEndsAt": "2025-12-16T17:00:00.000Z",
    "providerTypes": ["all"],
    "createdAt": "2025-12-01T10:00:00Z",
    "updatedAt": "2025-12-01T10:00:00Z"
  }
}

Update Campaign

PATCH

/campaigns/{campaignId}

Required scope: campaigns:write

Update a campaign. Changes automatically propagate to all active wallet cards for this campaign.

Response

{
  "success": true,
  "data": {
    "id": "campaign_abc123",
    "name": "Tech Conference 2025 Updated",
    "status": "active",
    "eventStartsAt": "2025-12-15T17:00:00.000Z",
    "eventEndsAt": "2025-12-16T17:00:00.000Z",
    "updatedAt": "2025-12-01T11:00:00Z"
  }
}

Immutable Settings: Once a campaign has recipients, barcodeValueStrategy becomes immutable and cannot be changed. Attempting to change this setting will return a 400 Bad Request error with code SETTING_LOCKED.

Campaign Status

Campaigns have four possible status values:

Response Fields

Status	Description	When Set	Can Change To
`draft`	Campaign is being set up, not yet launched	Initial status when campaign is created	`active` (when first recipient is invited), `archived` (manual)
`active`	Campaign is live and has invited recipients	Automatically set when first recipient is invited, or manually via API	`archived` (manual), `completed` (automatic when `eventEndsAt` is in the past)
`completed`	Event window has ended	Set automatically by the platform when `event_ends_at` is before the current time. Cannot be set via `PATCH` (`status: "completed"` is rejected).	`archived` (manual)
`archived`	Campaign is hidden from main list	Manually set via API or dashboard	`draft` (via unarchive)

Schedule fields eventStartsAt / eventEndsAt (UTC instants) are returned on campaign resources and are derived from startDate, optional multi-day endDate, campaignData times (doors_open_time, start_time, end_time), and campaignData.timezone.

Delete Campaign

DELETE

/campaigns/{campaignId}

Required scope: campaigns:write

Delete a campaign.

Response

{
  "success": true,
  "data": {
    "id": "campaign_abc123",
    "deleted": true
  }
}