1. Exports
  2. Exports API Overview

Exports

Exports API Overview

The Exports API enables you to export data from PackageX in CSV or JSON format. This powerful feature allows you to extract and analyze your data for reporting, integration, or backup purposes.

Key Features

  • Multiple Formats: Export data in CSV or JSON format
  • Flexible Filtering: Use the same filtering options as the List APIs
  • Customizable Output: Control which columns to include and their order
  • Temporary Storage: Exports are stored for 24 hours for easy retrieval
  • Batch Processing: Handle large datasets efficiently

How It Works

  1. Create Export: Submit an export request with your desired parameters
  2. Processing: The system queues and processes your export
  3. Retrieval: Download your completed export within 24 hours
  4. Cleanup: Exports are automatically deleted after 24 hours

Supported Resources

The following resources can be exported:

Resource Description
contact Contact information and details
group Contact groups and hierarchies
fulfillment Fulfillment orders and status
item Product catalog items
location Warehouse and facility data
manifest Shipping manifests
shipment Shipping data and tracking
tracker Package tracking information
shipping_label_inference OCR label processing results
asset Asset management data

Data Format Options

CSV Export Options

When exporting to CSV, you have two options for handling nested data:

1. Merge (Recommended for most use cases)

  • Behavior: Nested data is formatted in a human-readable way or as JSON objects
  • Best for: Quick analysis, data review, and when you need to preserve data relationships
  • Example: A contact's groups might appear as "Group A, Group B" or as a JSON string

2. Flatten (Recommended for data analysis)

  • Behavior: Nested data is flattened into separate CSV columns
  • Best for: Data analysis tools, spreadsheets, and when you need individual fields
  • Example:
    • Contact with 2 groups: Creates columns groups.0.name, groups.1.name
    • Contact with location: Creates columns location.name, location.id

JSON Export

  • Behavior: Preserves all data structure and relationships
  • Best for: API integrations, data processing, and when you need the complete data structure

Export Lifecycle

Processing Statuses

Initial Statuses

  • queued: Export request is valid and waiting to be processed
  • processing: Export is currently being generated

Final Statuses

  • completed: Export has been successfully generated and is ready for download
  • failed: Export could not be processed (check error details)
  • timed_out: Export took too long to process (consider reducing data scope)

Best Practices

Performance Optimization

  • Use filters: Limit data scope with specific filters rather than exporting everything
  • Select columns: Only include columns you need to reduce processing time
  • Time ranges: Use date filters to export data in manageable chunks
  • Avoid peak times: Large exports during business hours may take longer

Data Management

  • Download promptly: Exports are deleted after 24 hours
  • Store locally: Save important exports to your local system
  • Validate data: Check export completeness before relying on results
  • Monitor status: Use the status endpoint to track export progress

Common Use Cases

  • Daily reports: Export daily shipment summaries
  • Data migration: Extract data for system migrations
  • Compliance: Generate audit trails and compliance reports
  • Analytics: Export data for external analysis tools
  • Backup: Create data backups for disaster recovery

Error Handling

Common error scenarios and solutions:

Error Cause Solution
invalid_resource Unsupported resource type Check the supported resources list
invalid_filter Malformed filter syntax Review filter documentation
timeout Export too large or complex Reduce data scope or use pagination
Previous <- Retrieve Imports
Next Model ->