Status Queries

Examples for querying recipient status and tracking wallet card lifecycle.

List Recipients by Status

Query recipients filtered by status:

async function getRecipientsByStatus(campaignId, status) {
  const response = await fetch(
    `https://api.walletwerk.eu/api/v1/campaigns/${campaignId}/recipients?status=${status}&includeDownloadUrls=true`,
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    }
  );

  const data = await response.json();
  return data.data.recipients;
}

// Get all active recipients
const activeRecipients = await getRecipientsByStatus('campaign_abc123', 'active');
console.log(`Found ${activeRecipients.length} active recipients`);

// Get all invited recipients with download URLs
const invitedRecipients = await getRecipientsByStatus('campaign_abc123', 'invited');
invitedRecipients.forEach(recipient => {
  console.log(`${recipient.email}: ${recipient.downloadUrl}`);
});

import requests

def get_recipients_by_status(campaign_id, status):
    headers = {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
    
    params = {
        'status': status,
        'includeDownloadUrls': True
    }
    
    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()
    return data['data']['recipients']

# Get all active recipients
active_recipients = get_recipients_by_status('campaign_abc123', 'active')
print(f"Found {len(active_recipients)} active recipients")

# Get all invited recipients with download URLs
invited_recipients = get_recipients_by_status('campaign_abc123', 'invited')
for recipient in invited_recipients:
    print(f"{recipient['email']}: {recipient.get('downloadUrl', 'N/A')}")

Get Recipient with Status History

Retrieve a recipient with complete status change history:

async function getRecipientWithHistory(campaignId, recipientId) {
  const response = await fetch(
    `https://api.walletwerk.eu/api/v1/campaigns/${campaignId}/recipients/${recipientId}?includeHistory=true&includeStatus=true`,
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    }
  );

  const data = await response.json();
  const recipient = data.data;
  
  console.log(`Current status: ${recipient.status}`);
  console.log(`Status history:`);
  
  if (recipient.statusHistory) {
    recipient.statusHistory.forEach(entry => {
      console.log(`  ${entry.changedAt}: ${entry.oldStatus} → ${entry.newStatus} (${entry.eventType})`);
    });
  }
  
  return recipient;
}

getRecipientWithHistory('campaign_abc123', 'recipient_xyz789');

def get_recipient_with_history(campaign_id, recipient_id):
    headers = {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
    
    params = {
        'includeHistory': True,
        'includeStatus': True
    }
    
    response = requests.get(
        f'https://api.walletwerk.eu/api/v1/campaigns/{campaign_id}/recipients/{recipient_id}',
        headers=headers,
        params=params
    )
    response.raise_for_status()
    data = response.json()
    recipient = data['data']
    
    print(f"Current status: {recipient['status']}")
    print("Status history:")
    
    if recipient.get('statusHistory'):
        for entry in recipient['statusHistory']:
            print(f"  {entry['changedAt']}: {entry['oldStatus']} → {entry['newStatus']} ({entry['eventType']})")
    
    return recipient

get_recipient_with_history('campaign_abc123', 'recipient_xyz789')

Monitor Status Changes

Poll for status changes or use webhooks for real-time updates:

async function monitorRecipientStatus(campaignId, recipientId, intervalMs = 5000) {
  let lastStatus = null;
  
  const checkStatus = async () => {
    const response = await fetch(
      `https://api.walletwerk.eu/api/v1/campaigns/${campaignId}/recipients/${recipientId}`,
      {
        headers: {
          'Authorization': 'Bearer YOUR_API_KEY'
        }
      }
    );
    
    const data = await response.json();
    const currentStatus = data.data.status;
    
    if (currentStatus !== lastStatus) {
      console.log(`Status changed: ${lastStatus} → ${currentStatus}`);
      lastStatus = currentStatus;
      
      // Stop monitoring if card is active
      if (currentStatus === 'active') {
        console.log('Card is now active!');
        return;
      }
    }
    
    // Continue monitoring
    setTimeout(checkStatus, intervalMs);
  };
  
  checkStatus();
}

// Monitor until card becomes active
monitorRecipientStatus('campaign_abc123', 'recipient_xyz789');

import time

def monitor_recipient_status(campaign_id, recipient_id, interval_seconds=5):
    headers = {
        'Authorization': 'Bearer YOUR_API_KEY'
    }
    
    last_status = None
    
    while True:
        response = requests.get(
            f'https://api.walletwerk.eu/api/v1/campaigns/{campaign_id}/recipients/{recipient_id}',
            headers=headers
        )
        response.raise_for_status()
        data = response.json()
        current_status = data['data']['status']
        
        if current_status != last_status:
            print(f"Status changed: {last_status} → {current_status}")
            last_status = current_status
            
            # Stop monitoring if card is active
            if current_status == 'active':
                print('Card is now active!')
                break
        
        time.sleep(interval_seconds)

# Monitor until card becomes active
monitor_recipient_status('campaign_abc123', 'recipient_xyz789')

Polling for status changes is not recommended for production. Use webhooks instead for real-time status updates.