Pull List Members

Pull / OriginList Export

Overview

The Pull List Members action allows you to retrieve all subscribers from a Klaviyo list and export them to other systems. This action is essential for synchronizing Klaviyo contacts with CRMs, databases, data warehouses, or other marketing platforms.

Use this action when you need to export Klaviyo list data for analysis, backup, synchronization with other systems, or reporting purposes.

Key Features

📤 Full List Export

Pull all members from Klaviyo lists with email and phone data

🔄 Bi-Directional Sync

Enable two-way data flow between Klaviyo and your systems

📊 Data Analysis

Export list data for reporting, analytics, or data warehouse integration

💾 Backup & Archive

Create backups of your subscriber lists for disaster recovery

Configuration

Required Fields

Ensure your Klaviyo integration is configured with valid credentials:

{
  "klaviyo": {
    "api_key": "pk_8eef70f5c90d76f5ecd2c10487b7f9c402",
    "list_id": "KKbLLU"
  }
}

🔑 Configuration Requirements

api_key: Your Klaviyo Private API Key (starts with pk_)
list_id: The ID of the Klaviyo list to export members from

Field Mapping

Map Klaviyo fields to your destination system's expected format:

{
  "mapped_fields": [
    {
      "origin_field": "email",
      "destination_field": "email_address",
      "convert_function": ""
    },
    {
      "origin_field": "phone_number",
      "destination_field": "phone",
      "convert_function": ""
    }
  ]
}

Available Fields

email

Always Available

Type: String

Description: The subscriber's email address

Notes: Always present for all list members.

phone_number

If Available

Type: String

Description: The subscriber's phone number

Format: Usually includes country code (e.g., +1234567890)

Notes: Only present if phone number was collected for the profile.

💡 Mapping Tips

Email field is always available for all list members
Phone number may be empty/null if not collected
You can extend mapping to include custom Klaviyo profile properties
Use convert_function for data transformation during export

Workflow Configuration

Example workflow configuration for pulling list members:

{
  "name": "Export Klaviyo List to CRM",
  "origin": {
    "microservice": "integrations",
    "action": "list_member_list",
    "type": "pull",
    "integration": {
      "name": "klaviyo"
    },
    "mapped_fields": [
      {
        "origin_field": "email",
        "destination_field": "email"
      },
      {
        "origin_field": "phone_number",
        "destination_field": "phone"
      }
    ]
  },
  "destination": {
    "microservice": "customer",
    "action": "push_customers",
    "chunk_size": 200,
    "chunk_waiting_time": 1500
  }
}

Workflow Parameters

action: Set to list_member_list
type: Set to pull (origin operation)
chunk_size: Number of records to process per batch (100-500 recommended)
chunk_waiting_time: Delay between batches in milliseconds (1000-2000 recommended)
mapped_fields: Array of field mappings from Klaviyo to destination system

Use Cases

🔄 CRM Synchronization

Scenario: Sync Klaviyo list members to your CRM system to maintain unified customer records.

Benefit: Sales and support teams have access to complete subscriber information from Klaviyo.

📊 Data Warehouse Integration

Scenario: Export Klaviyo lists to data warehouses for analytics and business intelligence.

Benefit: Combine email marketing data with other business metrics for comprehensive reporting.

💾 Backup & Disaster Recovery

Scenario: Regularly export Klaviyo lists as backups to prevent data loss.

Benefit: Maintain independent copies of subscriber data for disaster recovery scenarios.

🔀 Platform Migration

Scenario: Export lists when migrating from Klaviyo to another email marketing platform.

Benefit: Preserve subscriber data during platform transitions.

📧 Multi-Platform Campaigns

Scenario: Sync Klaviyo lists to other marketing automation tools for coordinated campaigns.

Benefit: Run campaigns across multiple platforms with consistent audience data.

📈 Reporting & Analytics

Scenario: Pull list data for custom reports, segmentation analysis, or growth tracking.

Benefit: Analyze subscriber trends, growth rates, and list composition over time.

Behavior & Logic

Pull Operation

Understanding how list member export works:

1. List Query

Retrieve sends API request to Klaviyo to fetch all members from the specified list.

↓

2. Pagination

Klaviyo returns members in pages. Retrieve automatically handles pagination to get all records.

↓

3. Field Extraction

Extract email, phone_number, and any custom properties according to field mapping.

↓

4. Destination Push

Processed data is sent to destination system in chunks according to workflow configuration.

📝 Important Notes

Full list export: This action retrieves ALL members from the list (not incremental)
Automatic pagination: Retrieve handles Klaviyo's pagination automatically
Read-only: This action only reads data—no changes are made to Klaviyo
Snapshot: Exports current state of list at time of execution
Large lists: Very large lists may take time to export completely

⚠️ Performance Consideration

For lists with hundreds of thousands or millions of members, export operations can take significant time. Consider scheduling during off-peak hours and monitoring workflow progress. For incremental syncing, consider implementing timestamp-based filtering in your workflow logic.

Data Structure

Exported Data Format

Each list member is exported with the following structure:

{
  "email": "customer@example.com",
  "phone_number": "+15551234567",
  "id": "01GQVN5C8YXPZQ2FJYM3KXBCZT",
  "created": "2023-01-15T10:30:00Z",
  "updated": "2024-01-20T14:22:00Z",
  "properties": {
    "first_name": "John",
    "last_name": "Doe",
    "$consent": ["email"],
    "$source": "Website Form"
  }
}

📋 Field Details

email: Always present, primary identifier
phone_number: Present only if collected for the profile
id: Klaviyo's internal profile ID (included if needed)
created: When profile was created (timestamp)
updated: Last profile update (timestamp)
Custom properties: Any additional profile fields you've configured

Performance Optimization

⚡ Chunk Size Optimization

Optimize for export performance:

Small lists (<10k): chunk_size: 500-1000
Medium lists (10k-100k): chunk_size: 200-500
Large lists (>100k): chunk_size: 100-200
Balance between speed and memory usage

⏱️ Scheduling Best Practices

When to run list exports:

Regular sync: Daily or weekly scheduled exports
Off-peak hours: Schedule large exports during low-traffic times
Incremental logic: Implement timestamp filtering to reduce data volume
Rate limits: Set chunk_waiting_time (1000-2000ms) to avoid API throttling

🎯 Selective Exports

Reduce processing time:

Only map fields you actually need in destination
Use destination filters to skip unchanged records
Consider incremental sync patterns for frequently updated data

Best Practices

✅ Data Integrity

Validate exported data before writing to destination
Implement error handling for missing or invalid fields
Log export statistics (total records, success/failure counts)
Compare record counts between Klaviyo and destination

✅ Privacy & Security

Ensure destination systems have proper data protection
Encrypt data in transit and at rest
Limit access to exported data based on business need
Maintain audit logs of export operations
Comply with GDPR, CCPA, and privacy regulations

✅ Monitoring & Alerts

Monitor export completion times for anomalies
Set up alerts for failed exports
Track list growth trends over time
Verify data consistency post-export

Troubleshooting

🔴 Issue: "List not found"

Cause: list_id is incorrect or list was deleted.

Solution: Verify list_id in Klaviyo Lists → Settings. Ensure list exists and ID is correct.

🔴 Issue: "Authentication failed"

Cause: API key is invalid, expired, or lacks read permissions.

Solution: Verify api_key is a Private API Key (starts with pk_). Check permissions include list read access.

🔴 Issue: "Export incomplete or missing records"

Cause: Pagination not handled properly or API timeout.

Solution: Retrieve handles pagination automatically. Check workflow logs for errors. Verify no API rate limit issues.

🔴 Issue: "Export taking too long"

Cause: List is very large or chunk_waiting_time is too high.

Solution: Reduce chunk_waiting_time, increase chunk_size (with caution), or schedule export during off-peak hours.

🔴 Issue: "Rate limit exceeded"

Cause: Too many API requests in short time period.

Solution: Increase chunk_waiting_time (try 2000-3000ms) to add delays between batches.

🔴 Issue: "Missing phone numbers in export"

Cause: Phone numbers weren't collected for many profiles.

Solution: This is expected—not all profiles have phone numbers. Handle null/empty values in destination logic.

API Response

Success Response

When list members are successfully retrieved:

{
  "status": "success",
  "total_members": 5420,
  "exported": 5420,
  "list_id": "KKbLLU",
  "export_time": "2024-01-25T10:15:00Z",
  "members": [
    {
      "email": "customer1@example.com",
      "phone_number": "+15551234567"
    },
    {
      "email": "customer2@example.com",
      "phone_number": null
    }
  ]
}

Error Response

If an error occurs during export:

{
  "status": "error",
  "message": "List not found",
  "details": {
    "list_id": "INVALID",
    "reason": "The specified list does not exist"
  }
}