Recipients API

Recipients are always associated with a campaign. Wallet cards are automatically created when recipients are added to a campaign.

Add Single Recipient

POST

/campaigns/{campaignId}/recipients

Required scope: campaigns:write

Add a single recipient to a campaign. Wallet cards are automatically created in the background.

Request Parameters

Parameter	Type	Required	Description
`email`	string	Yes	Recipient email address
`name`	string	No	Recipient full name
`phone`	string	No	Phone number (E.164 format)
`externalId`	string	No	Your internal ID for this recipient
`recipientData`	object	No	Recipient-specific data (merged with campaign data)
`recipientData.barcodeValue`	string	No	Custom barcode value (required if campaign uses `barcodeValueStrategy: "custom"`)
`providerTypes`	array	No	Override: `["all"]`, `["apple"]`, `["google"]`, `["eudiw"]` (default: inherits from campaign)

curl -X POST https://api.walletwerk.eu/api/v1/campaigns/campaign_abc123/recipients \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john@example.com",
    "name": "John Doe",
    "phone": "+1234567890",
    "externalId": "user_123",
    "recipientData": {
      "ticketNumber": "TICKET-001",
      "seatNumber": "A15",
      "barcodeValue": "TICKET-12345-ABC"
    },
      "providerTypes": ["apple"]
  }'

const campaignId = 'campaign_abc123';

const response = await fetch(
  `https://api.walletwerk.eu/api/v1/campaigns/${campaignId}/recipients`,
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      email: 'john@example.com',
      name: 'John Doe',
      phone: '+1234567890',
      externalId: 'user_123',
      recipientData: {
        ticketNumber: 'TICKET-001',
        seatNumber: 'A15',
        barcodeValue: 'TICKET-12345-ABC'
      },
      providerTypes: ['apple']
    })
  }
);

const data = await response.json();
console.log('Recipient added:', data.data);

import requests

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

payload = {
    'email': 'john@example.com',
    'name': 'John Doe',
    'phone': '+1234567890',
    'externalId': 'user_123',
    'recipientData': {
        'ticketNumber': 'TICKET-001',
        'seatNumber': 'A15',
        'barcodeValue': 'TICKET-12345-ABC'
    },
    'providerTypes': ['apple']
}

response = requests.post(
    f'https://api.walletwerk.eu/api/v1/campaigns/{campaign_id}/recipients',
    headers=headers,
    json=payload
)

data = response.json()
print('Recipient added:', data['data'])

Response

{
  "success": true,
  "data": {
    "id": "recipient_xyz789",
    "campaignId": "campaign_abc123",
    "email": "john@example.com",
    "name": "John Doe",
    "phone": "+1234567890",
    "externalId": "user_123",
    "status": "pending",
    "createdAt": "2025-12-09T10:00:00Z",
    "updatedAt": "2025-12-09T10:00:00Z"
  }
}

Recipients are created with status "pending". Call the /invite endpoint to create the wallet card and send the invitation.

Bulk Add Recipients

POST

/campaigns/{campaignId}/recipients/bulk

Required scope: campaigns:write

Add multiple recipients to a campaign at once.

Request Parameters

Parameter	Type	Required	Description
`recipients`	array	Yes	Array of recipient objects
`recipients[].email`	string	Yes	Recipient email address
`recipients[].name`	string	No	Recipient full name
`recipients[].phone`	string	No	Phone number
`recipients[].externalId`	string	No	Your internal ID
`recipients[].recipientData`	object	No	Recipient-specific data
`recipients[].recipientData.barcodeValue`	string	No	Custom barcode value (required if campaign uses `barcodeValueStrategy: "custom"`)
`recipients[].providerTypes`	array	No	Override provider types (default: inherits from campaign)
`sendEmail`	boolean	No	Send invite emails (default: `true`)

curl -X POST https://api.walletwerk.eu/api/v1/campaigns/campaign_abc123/recipients/bulk \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipients": [
      {
        "email": "john@example.com",
        "name": "John Doe",
        "recipientData": {
          "ticketNumber": "TICKET-001",
          "barcodeValue": "TICKET-12345-ABC"
        },
        "providerTypes": ["apple"]
      },
      {
        "email": "jane@example.com",
        "name": "Jane Smith",
        "recipientData": {
          "ticketNumber": "TICKET-002",
          "barcodeValue": "TICKET-12346-DEF"
        }
      }
    ],
    "sendEmail": true
  }'

const campaignId = 'campaign_abc123';

const response = await fetch(
  `https://api.walletwerk.eu/api/v1/campaigns/${campaignId}/recipients/bulk`,
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      recipients: [
        {
          email: 'john@example.com',
          name: 'John Doe',
          recipientData: {
            ticketNumber: 'TICKET-001',
            barcodeValue: 'TICKET-12345-ABC'
          },
          providerTypes: ['apple']
        },
        {
          email: 'jane@example.com',
          name: 'Jane Smith',
          recipientData: {
            ticketNumber: 'TICKET-002',
            barcodeValue: 'TICKET-12346-DEF'
          }
        }
      ],
      sendEmail: true
    })
  }
);

const data = await response.json();
console.log(`Created: ${data.data.created}, Failed: ${data.data.failed}`);

import requests

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

payload = {
    'recipients': [
        {
            'email': 'john@example.com',
            'name': 'John Doe',
            'recipientData': {
                'ticketNumber': 'TICKET-001',
                'barcodeValue': 'TICKET-12345-ABC'
            },
            'providerTypes': ['apple']
        },
        {
            'email': 'jane@example.com',
            'name': 'Jane Smith',
            'recipientData': {
                'ticketNumber': 'TICKET-002',
                'barcodeValue': 'TICKET-12346-DEF'
            }
        }
    ],
    'sendEmail': True
}

response = requests.post(
    f'https://api.walletwerk.eu/api/v1/campaigns/{campaign_id}/recipients/bulk',
    headers=headers,
    json=payload
)

data = response.json()
print(f"Created: {data['data']['created']}, Failed: {data['data']['failed']}")

List Recipients

GET

/campaigns/{campaignId}/recipients

Required scope: campaigns:read

List all recipients for a campaign.

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)
`email`	string	No	Filter by email address
`status`	string	No	Filter by status: `pending`, `created`, `invited`, `active`, `revoked`, `removed`, `deleted`
`includeHistory`	boolean	No	Include status change history in response (default: `false`)
`includeStatus`	boolean	No	Include detailed status information (cards array) for each recipient (default: `false`)
`includeDownloadUrls`	boolean	No	Include download URLs for each recipient's wallet cards (default: `false`)

# List all invited recipients
curl -X GET "https://api.walletwerk.eu/api/v1/campaigns/campaign_abc123/recipients?status=invited&limit=50&includeDownloadUrls=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

const campaignId = 'campaign_abc123';

async function listRecipients(status = null, limit = 50) {
  const params = new URLSearchParams({ limit: limit.toString() });
  if (status) params.append('status', status);
  params.append('includeDownloadUrls', 'true');
  
  const response = await fetch(
    `https://api.walletwerk.eu/api/v1/campaigns/${campaignId}/recipients?${params}`,
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    }
  );
  
  const data = await response.json();
  console.log(`Found ${data.data.recipients.length} recipients`);
  return data.data;
}

// List invited recipients
listRecipients('invited', 50);

import requests

campaign_id = 'campaign_abc123'
headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

def list_recipients(status=None, limit=50):
    params = {'limit': limit, 'includeDownloadUrls': True}
    if status:
        params['status'] = status
    
    response = requests.get(
        f'https://api.walletwerk.eu/api/v1/campaigns/{campaign_id}/recipients',
        headers=headers,
        params=params
    )
    response.raise_for_status()
    data = response.json()
    print(f"Found {len(data['data']['recipients'])} recipients")
    return data['data']

# List invited recipients
list_recipients(status='invited', limit=50)

Response

{
  "success": true,
  "data": {
    "recipients": [
      {
        "id": "recipient_xyz789",
        "campaignId": "campaign_abc123",
        "email": "john@example.com",
        "name": "John Doe",
        "phone": "+1234567890",
        "externalId": "user_123",
        "status": "invited",
        "walletCardId": "card_abc123",
        "walletCardStatus": "active",
        "createdAt": "2025-12-09T10:00:00Z",
        "updatedAt": "2025-12-09T11:00:00Z"
      }
    ],
    "pagination": {
      "total": 50,
      "limit": 20,
      "offset": 0,
      "hasMore": true
    }
  }
}

Get Recipient

GET

/campaigns/{campaignId}/recipients/{recipientId}

Required scope: campaigns:read

Retrieve details of a specific recipient in a campaign.

Response

{
  "success": true,
  "data": {
    "id": "recipient_xyz789",
    "campaignId": "campaign_abc123",
    "email": "john@example.com",
    "name": "John Doe",
    "phone": "+1234567890",
    "externalId": "user_123",
    "status": "invited",
    "walletCardId": "card_abc123",
    "walletCardStatus": "active",
    "createdAt": "2025-12-09T10:00:00Z",
    "updatedAt": "2025-12-09T11:00:00Z"
  }
}

Update Recipient

PATCH

/campaigns/{campaignId}/recipients/{recipientId}

Required scope: campaigns:write

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

Response

{
  "success": true,
  "data": {
    "id": "recipient_xyz789",
    "campaignId": "campaign_abc123",
    "email": "john@example.com",
    "name": "John Doe Updated",
    "status": "invited",
    "updatedAt": "2025-12-09T12:00:00Z"
  }
}

Delete Recipient

DELETE

/campaigns/{campaignId}/recipients/{recipientId}

Required scope: campaigns:write

Delete a recipient from a campaign. This removes them from the system but keeps their cards in the wallet.

Response

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

Invite Recipient

POST

/campaigns/{campaignId}/recipients/{recipientId}/invite

Required scope: campaigns:write

Send an invite to a recipient. This updates their status to invited and optionally sends an email.

Request Parameters

Parameter	Type	Required	Description
`sendEmail`	boolean	No	Send invite email (default: `false`)
`email`	object	No	Customize email content (only used if `sendEmail: true`)
`email.subject`	string	No	Email subject line (supports placeholders: `{{name}}`, `{{eventName}}`, etc.)
`email.body`	string	No	Email body text (supports same placeholders)
`email.buttonText`	string	No	Button text in email (default: `"Add to Wallet"`)

Response

{
  "success": true,
  "data": {
    "id": "recipient_xyz789",
    "status": "invited",
    "downloadUrl": "https://walletwerk.eu/c/abc123",
    "updatedAt": "2025-12-09T11:00:00Z"
  }
}

Bulk Invite Recipients

POST

/campaigns/{campaignId}/recipients/bulk-invite

Required scope: campaigns:write

Bulk invite recipients with status created (have wallet cards but not yet invited). Processes up to 100 recipients per call.

Request Parameters

Parameter	Type	Required	Description
`sendEmail`	boolean	No	Send invite emails (default: `true`)
`limit`	number	No	Max recipients to invite (1-100, default: `100`)
`email`	object	No	Customize email content (only used if `sendEmail: true`)

Response

{
  "success": true,
  "data": {
    "invited": 10,
    "emailsSent": 10,
    "emailsFailed": 0,
    "remaining": 0,
    "downloadUrls": [
      {
        "recipientId": "recipient_001",
        "email": "john@example.com",
        "downloadUrl": "https://walletwerk.eu/c/abc123"
      }
    ]
  }
}

The response includes downloadUrls for all successfully invited recipients, allowing you to distribute wallet card links without additional API calls.

Revoke Recipient

POST

/campaigns/{campaignId}/recipients/{recipientId}/revoke

Required scope: campaigns:write

Revoke a recipient's cards. This voids all wallet cards for this recipient in this campaign.

Response

{
  "success": true,
  "data": {
    "id": "recipient_xyz789",
    "status": "revoked",
    "updatedAt": "2025-12-09T13:00:00Z"
  }
}