Back to Documentation

Bulk Import/Export Guide

Public Document • Documentation

Manage multiple links efficiently

Related Document: API Documentation

Programmatic bulk operations

Bulk Import/Export Guide

Manage multiple links efficiently

Overview

PVTLNK’s bulk operations allow you to:

  • Import multiple links - Create hundreds of links at once
  • Export link data - Download analytics for external analysis
  • Batch updates - Update multiple links simultaneously

Requirements

Plan Availability
Starter ❌ Not available
Pro ❌ Not available
Enterprise ✅ Available

Bulk Import

Import Format

Create a CSV file with the following columns:

Column Required? Description Example
destination_url ✅ Yes Target URL https://example.com/page1
title ❌ No Link title Summer Campaign
description ❌ No Link description Promotional link for summer sale
short_code ❌ No Custom short code summer2026
password ❌ No Password protection secret123
expires_at ❌ No Expiration date 2026-12-31T23:59:59Z

Example CSV

csv destination_url,title,description,short_code https://example.com/landing1,Campaign Landing,Spring sale landing page,spring-sale https://example.com/landing2,Product Page,New product announcement,new-product https://example.com/about,About Us,Company information,about-us

Import via Dashboard

  1. Go to All Links
  2. Click Import (or Bulk Operations)
  3. Upload your CSV file
  4. Review the preview
  5. Click Import Links

Import via API

```bash POST /api/v1/links/bulk_import Content-Type: application/json

{ “links”: [ { “destination_url”: “https://example.com/page1”, “title”: “Link 1”, “short_code”: “link1” }, { “destination_url”: “https://example.com/page2”, “title”: “Link 2”, “short_code”: “link2” } ] } ```

Response:

json { "success": true, "imported": 2, "errors": [], "links": [ { "id": 1, "short_code": "link1", "short_url": "https://pvtlnk.com/link1" }, { "id": 2, "short_code": "link2", "short_url": "https://pvtlnk.com/link2" } ] }

Bulk Export

Export via Dashboard

  1. Go to All Links
  2. Click Export CSV
  3. Choose export options:
    • All links
    • Active links only
    • Archived links only
    • Date range
  4. Click Generate Export
  5. Download the CSV file

Export Fields

The exported CSV includes:

Field Description
short_url Full shortened URL
destination_url Original destination URL
short_code Short code identifier
title Link title
description Link description
collection Collection name
click_count Total clicks
unique_visitors Unique visitors
created_at Creation timestamp
status Active/Archived/Expired
password_protected Yes/No

Export via API

```bash # Export all links GET /api/v1/links/export

Export with filters

GET /api/v1/links/export?active=true&collection_id=123

Export with date range

GET /api/v1/links/export?created_after=2026-01-01&created_before=2026-01-31 ```

Response: CSV file download

Batch Updates

You can update properties for multiple links at once:

```bash POST /api/v1/links/batch_update Content-Type: application/json

{ “link_ids”: [1, 2, 3, 4, 5], “updates”: { “archived”: true } } ```

Supported Batch Operations

Operation Field Example
Archive archived { "archived": true }
Unarchive archived { "archived": false }
Update collection collection_id { "collection_id": 123 }
Update title title { "title": "New Title" }
Update description description { "description": "New description" }

Bulk Delete

```bash POST /api/v1/links/bulk_destroy Content-Type: application/json

{ “link_ids”: [1, 2, 3] } ```

Note: Deleted links cannot be recovered.

Import Error Handling

If some links fail to import, the response includes details:

json { "success": true, "imported": 48, "failed": 2, "errors": [ { "row": 49, "destination_url": "invalid-url", "error": "Invalid destination URL format" }, { "row": 52, "short_code": "existing", "error": "Short code already in use" } ] }

Rate Limits

Operation Limit
Bulk import 1,000 links per request
Bulk export No limit (paginated)
Batch update 500 links per request
Bulk delete 100 links per request

Best Practices

1. Test with Small Batches

Start with 10-20 links to verify your CSV format:

bash # Test import with 5 links # If successful, proceed with full import

2. Use Unique Short Codes

If importing with custom short codes:

  • Avoid duplicates
  • Use descriptive names
  • Keep them short (4-8 characters)

3. Validate URLs Before Import

Check that all destination URLs are valid:

```bash # Example validation script require ‘uri’

urls = CSV.read(‘import.csv’, headers: true)[‘destination_url’] invalid = urls.reject { |url| url =~ /\Ahttps?:\/\// } puts “Invalid URLs: #{invalid.count}” ```

4. Organize with Collections

Import links into collections for easier management:

csv destination_url,title,collection https://example.com/link1,Link 1,Marketing Campaign https://example.com/link2,Link 2,Marketing Campaign https://example.com/link3,Link 3,Product Launch

Use Cases

1. Marketing Campaign Launch

Import 100+ tracking links for a new campaign:

csv destination_url,title,short_code,utm_source,utm_medium,utm_campaign https://site.com/lp1,LP Facebook,fb_001,facebook,cpc,spring_sale https://site.com/lp2,LP Google,go_001,google,cpc,spring_sale # ... add 98 more rows

2. Migration from Another Service

Import existing short links:

csv destination_url,short_code,title https://old-service.com/abc,old-code-abc,Original Link 1 https://old-service.com/def,old-code-def,Original Link 2

3. Regular Analytics Export

Schedule regular exports for reporting:

bash # Weekly export script curl -H "Authorization: Bearer $API_TOKEN" \ "https://pvtlnk.com/api/v1/links/export?active=true" \ -o "links_export_$(date +%Y%m%d).csv"

Troubleshooting

Issue Solution
Import fails Check CSV format and encoding
Duplicate short codes Remove or rename duplicates
URLs not valid Ensure https:// prefix
Links not appearing Check import response for errors
Export times out Use pagination (?page=1)

FAQ

Q: What’s the maximum import file size? A: 10MB per file.

Q: Can I import links with UTM parameters? A: Yes, add them to the destination URL or use separate columns.

Q: Do imported links count toward my monthly limit? A: Yes, all created links count toward your plan limit.

Q: Can I cancel a bulk import in progress? A: No, imports are atomic - all or nothing.

Q: How long does a bulk import take? A: Approximately 1 second per 100 links.