Documentation

Getting Started

What is vsl.im?

vsl.im is a modern URL shortening and link management platform. It allows you to create short, memorable links, track their performance, and manage them through a powerful dashboard or API.

Quick Start

1. Create a link: Paste any URL on the homepage or dashboard and click "Shorten"
2. Share your link: Copy the short URL (e.g., vsl.im/abc123) and share it anywhere
3. Track performance: View clicks, geographic data, and referrers in your dashboard

Account Benefits

While you can create links without an account, registered users get:

• Custom aliases (e.g., vsl.im/summer-sale)
• Link editing and management
• Detailed analytics and reporting
• QR code generation
• API access for automation

Creating Links

Basic Link Creation

Enter any valid URL starting with http:// or https://. The system will generate a random short code for you.

Custom Aliases

Choose your own memorable short code instead of random characters. Aliases must be:

• 3-50 characters long
• Alphanumeric with hyphens and underscores allowed
• Unique within the selected domain

Domain Selection

If you have custom domains configured, you can select which domain to use for your link. Your default domain (set in settings) will be pre-selected.

Custom Domains

Adding a Domain

1. Go to Settings → Custom Domains
2. Enter your domain name (e.g., link.yourdomain.com)
3. Add the required DNS records to your domain registrar
4. Click "Verify" once DNS propagation is complete (usually 5-30 minutes)

Required DNS Records

SSL Certificates

SSL certificates are automatically provisioned via Let's Encrypt once your domain is verified. This process typically takes 1-5 minutes.

Custom Landing Pages

You can customize the page visitors see when accessing your domain root (e.g., link.yourdomain.com). Add custom HTML, CSS, and JavaScript in the domain settings.

QR Codes

Every link you create can have a QR code generated. QR codes are ideal for:

• Print materials (flyers, business cards, posters)
• Product packaging
• Digital signage
• Event materials

Generating QR Codes

1. Go to Tools → QR Generator
2. Search and select the link you want
3. Customize size and format (PNG, SVG, PDF)
4. Download or copy the QR code

Best Practices

• Use at least 300 DPI for print materials
• Ensure adequate contrast between QR code and background
• Test QR codes before printing at scale
• Include a short URL text fallback for accessibility

Analytics

Available Metrics

• Clicks: Total number of times your link was accessed
• Unique visitors: Deduplicated by IP/device combination
• Geographic data: Country, region, and city breakdown
• Devices: Desktop, mobile, tablet breakdown
• Browsers: Chrome, Firefox, Safari, Edge, etc.
• Operating systems: Windows, macOS, iOS, Android, Linux
• Referrers: Where traffic is coming from
• Time series: Clicks over time with hourly/daily/weekly views

Data Retention

Analytics data is retained based on your plan:

• Free: 30 days
• Pro: 1 year
• Business: 2 years
• Enterprise: Unlimited

Exporting Data

Export analytics data as CSV or JSON from the link details page or via the API.

Password Protection

Protect sensitive links with a password. When visitors access the link, they'll be prompted to enter the password before being redirected.

Setting a Password

1. When creating or editing a link, expand "Advanced Options"
2. Enter a password in the "Password Protection" field
3. Save the link

Password Requirements

• Minimum 4 characters
• Stored securely using bcrypt hashing
• Can be changed or removed at any time

Link Expiration

Set links to automatically expire after a certain date. Useful for:

• Time-limited promotions
• Event registrations
• Temporary file sharing
• Beta access links

Setting Expiration

Use the date picker in "Advanced Options" when creating or editing a link. After expiration, visitors will see a "Link Expired" page.

API Reference

Authentication

All API requests require authentication via Bearer token. Get your API token from Settings → API.

Base URL

Endpoints

{
  "url": "https://example.com/long-url",
  "alias": "my-custom-alias",  // optional
  "domain_id": 123,            // optional, use custom domain
  "password": "secret",        // optional
  "expiration": "2026-12-31"   // optional, ISO 8601 date
}

View Full API Documentation →

Integrations

Official Integrations

Developer Libraries

cURL Example

curl -X POST https://dev.vsl.im/api.php \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/my-long-url"}'

Organizations & Teams

Organizations allow you to collaborate with team members, share resources, and manage links collectively.

Creating an Organization

1. Go to Tools → Organization
2. Click "Create Organization"
3. Enter a name for your organization

Roles

• Owner: Full control, billing, can delete organization
• Admin: Manage members, settings, domains
• Member: Create and manage own links, use shared domains

Inviting Members

Click "Invite Member" in your organization dashboard. Enter their email address and select a role. They'll receive an invitation link to join.

SSO Configuration

Enterprise organizations can configure Single Sign-On (SSO) to allow members to authenticate using their existing identity provider.

Supported Providers

• Microsoft Entra ID (Azure AD)
• Google Workspace
• Okta
• Any SAML 2.0 provider
• Any OAuth 2.0/OpenID Connect provider

Setup Steps

1. Go to Organization → SSO Settings
2. Select your identity provider type
3. Enter Client ID, Client Secret, and issuer URL
4. Configure the callback URL in your identity provider
5. Test the connection and enable SSO

Webhooks

Receive real-time notifications when events occur in your account.

Available Events

• link.created - New link created
• link.clicked - Link was clicked
• link.updated - Link was modified
• link.deleted - Link was deleted
• link.expired - Link reached expiration date
• domain.verified - Custom domain verified

Payload Format

{
  "event": "link.clicked",
  "timestamp": "2026-01-26T12:00:00Z",
  "data": {
    "short_code": "abc123",
    "long_url": "https://example.com",
    "visitor": {
      "country": "US",
      "device": "mobile",
      "browser": "Chrome"
    }
  }
}

Rate Limits

API requests are rate-limited based on your plan:

Rate Limit Headers

Every API response includes headers showing your current rate limit status:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1706270400

Security

Data Protection

• All data encrypted in transit (TLS 1.3)
• Sensitive data encrypted at rest (AES-256)
• Passwords hashed using bcrypt
• API tokens securely generated and stored

Link Security

• Automatic malware scanning of destination URLs
• Phishing detection and blocking
• Spam and abuse prevention
• Manual review and reporting system

Account Security

• Two-factor authentication (TOTP)
• Session management and revocation
• Login history and notifications
• API token rotation

Troubleshooting

Common Issues

Contact Support →