API Documentation

Integrate Links DNA into your applications with our RESTful API

Enterprise Feature: API access requires an Enterprise plan

API Reference

Authentication
Endpoints
Examples
Webhooks

Getting Started

Base URL

https://yourdomain.com/api/v1/

Rate Limits

  • Standard: 1,000 requests per hour
  • Enterprise: 10,000 requests per hour
  • Burst: Up to 50 requests per minute

Response Format

All API responses are in JSON format with the following structure:

{
  "success": true,
  "data": {...},
  "message": "Operation completed successfully",
  "timestamp": "2024-01-01T12:00:00Z"
}

Authentication

API Key Authentication

Include your API key in the request headers:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Getting Your API Key: Contact our enterprise team to receive your API credentials after upgrading to an Enterprise plan.

Error Responses

Error responses include standard HTTP status codes:

Status Code Meaning Description
401 Unauthorized Invalid or missing API key
403 Forbidden Access denied for this resource
429 Rate Limited Too many requests
500 Server Error Internal server error

API Endpoints

Links Management

POST /api/v1/links

Create a new tracked link

Request Body:

{
  "original_url": "https://example.com",
  "name": "My Campaign Link",
  "custom_variables": {
    "campaign": "summer2024",
    "source": "email"
  }
}

Response:

{
  "success": true,
  "data": {
    "id": "abc123",
    "short_url": "https://yourdomain.com/abc123",
    "original_url": "https://example.com",
    "name": "My Campaign Link",
    "created_at": "2024-01-01T12:00:00Z",
    "total_clicks": 0
  }
}
GET /api/v1/links

Retrieve all your links with pagination

Query Parameters:

  • page - Page number (default: 1)
  • limit - Results per page (default: 50, max: 100)
  • search - Search by link name
GET /api/v1/links/{id}/analytics

Get detailed analytics for a specific link

Query Parameters:

  • start_date - Filter from date (YYYY-MM-DD)
  • end_date - Filter to date (YYYY-MM-DD)
  • group_by - Group results by: hour, day, week, month

Analytics & Reporting

GET /api/v1/analytics/dashboard

Get overview statistics for your account

Response:

{
  "success": true,
  "data": {
    "total_links": 25,
    "total_clicks": 1547,
    "unique_visitors": 892,
    "top_countries": ["United States", "Canada", "United Kingdom"],
    "performance_trend": "up",
    "ai_insights": [
      "Your links perform 40% better on weekdays",
      "Mobile users show higher engagement rates"
    ]
  }
}
POST /api/v1/analytics/export

Export analytics data in CSV format

Request Body:

{
  "link_ids": ["abc123", "def456"],
  "start_date": "2024-01-01",
  "end_date": "2024-01-31",
  "format": "csv"
}

Code Examples

Python Example

import requests

# Configuration
API_KEY = "your_api_key_here"
BASE_URL = "https://yourdomain.com/api/v1"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# Create a new link
def create_link(original_url, name, variables=None):
    data = {
        "original_url": original_url,
        "name": name
    }
    if variables:
        data["custom_variables"] = variables
    
    response = requests.post(
        f"{BASE_URL}/links",
        json=data,
        headers=headers
    )
    return response.json()

# Get analytics
def get_analytics(link_id):
    response = requests.get(
        f"{BASE_URL}/links/{link_id}/analytics",
        headers=headers
    )
    return response.json()

# Example usage
link = create_link(
    "https://example.com",
    "My Campaign",
    {"campaign": "summer", "source": "email"}
)
print(f"Created link: {link['data']['short_url']}")

analytics = get_analytics(link['data']['id'])
print(f"Total clicks: {analytics['data']['total_clicks']}")

JavaScript Example

// Configuration
const API_KEY = 'your_api_key_here';
const BASE_URL = 'https://yourdomain.com/api/v1';

const headers = {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
};

// Create a new link
async function createLink(originalUrl, name, variables = {}) {
    const response = await fetch(`${BASE_URL}/links`, {
        method: 'POST',
        headers: headers,
        body: JSON.stringify({
            original_url: originalUrl,
            name: name,
            custom_variables: variables
        })
    });
    return await response.json();
}

// Get analytics
async function getAnalytics(linkId) {
    const response = await fetch(`${BASE_URL}/links/${linkId}/analytics`, {
        headers: headers
    });
    return await response.json();
}

// Example usage
(async () => {
    try {
        const link = await createLink(
            'https://example.com',
            'My Campaign',
            { campaign: 'summer', source: 'email' }
        );
        console.log(`Created link: ${link.data.short_url}`);
        
        const analytics = await getAnalytics(link.data.id);
        console.log(`Total clicks: ${analytics.data.total_clicks}`);
    } catch (error) {
        console.error('API Error:', error);
    }
})();

Webhooks

Real-time Event Notifications

Receive instant notifications when events occur on your links.

Available Events:

  • link.clicked - A link was clicked
  • link.created - A new link was created
  • analytics.daily - Daily analytics summary
  • insights.generated - New AI insights available

Webhook Payload Example:

{
  "event": "link.clicked",
  "timestamp": "2024-01-01T12:00:00Z",
  "data": {
    "link_id": "abc123",
    "visitor_id": "visitor_xyz",
    "country": "United States",
    "device_type": "Mobile",
    "custom_variables": {
      "campaign": "summer",
      "source": "email"
    }
  }
}

Setting Up Webhooks

Configure webhook endpoints through your Enterprise dashboard or contact our support team.

Security: All webhooks include a signature header for verification. Contact support for webhook signature validation details.

Need API Access?

Upgrade to Enterprise to unlock full API capabilities and dedicated support.

Contact Enterprise Sales Technical Support