Create Link

Create a new short link with platform-specific routing, attribution tracking, and UTM parameters.

Prerequisites

You must create a template before creating links. The templateId field is required and must reference an existing template that defines default settings for your links.

See Link Templates for details on creating templates.

Endpoint

POST /api/links

Authentication

Requires a valid API key in the Authorization header.

Authorization: Bearer YOUR_API_KEY

See Authentication for details.

Request Body

Field	Type	Required	Description
templateId	string (UUID)	✅ Yes	Template to use for default values
originalUrl	string (URL)	✅ Yes	Destination URL (fallback)
title	string	No	Internal title for organization
description	string	No	Internal description
iosUrl	string (URL)	No	Destination for iOS users
androidUrl	string (URL)	No	Destination for Android users
webFallbackUrl	string (URL)	No	Destination for web users
attributionWindowHours	number	No	Attribution window (1-2160 hours). Default: 168 (7 days)
utmParameters	object	No	UTM parameters to append
targetingRules	object	No	Geographic/language/device targeting
customCode	string	No	Custom short code (4-30 chars, alphanumeric)
expiresAt	string (ISO 8601)	No	Expiration timestamp

UTM Parameters Object

{
  utm_source?: string;    // Traffic source (e.g., "instagram")
  utm_medium?: string;    // Marketing medium (e.g., "social")
  utm_campaign?: string;  // Campaign name (e.g., "spring-sale-2024")
  utm_term?: string;      // Paid keywords (e.g., "wireless-headphones")
  utm_content?: string;   // Content variant (e.g., "carousel-ad-1")
}

Targeting Rules Object

{
  countries?: string[];   // ISO 3166-1 alpha-2 codes (e.g., ["US", "CA", "GB"])
  languages?: string[];   // ISO 639-1 codes (e.g., ["en", "es", "fr"])
  platforms?: string[];   // ["ios", "android", "web"]
}

Response

Success Response

Status Code: 201 Created

{
  "id": "link_a1b2c3d4e5f6g7h8",
  "short_code": "abc123",
  "short_url": "https://lnk.forty.com/abc123",
  "user_id": "user_123",
  "organization_id": "org_456",
  "project_id": null,
  "template_id": "template_789",
  "original_url": "https://example.com/products/wireless-headphones",
  "title": "Wireless Headphones - Spring Sale",
  "description": "Q2 2024 Instagram campaign",
  "ios_url": "https://apps.apple.com/app/your-store/id123456789",
  "android_url": "https://play.google.com/store/apps/details?id=com.yourstore",
  "web_fallback_url": "https://example.com/products/wireless-headphones?platform=web",
  "attribution_window_hours": 168,
  "utm_parameters": {
    "utm_source": "instagram",
    "utm_medium": "social",
    "utm_campaign": "spring-sale-2024",
    "utm_term": "wireless-headphones",
    "utm_content": "carousel-ad-1"
  },
  "targeting_rules": {
    "countries": ["US", "CA", "GB"],
    "languages": ["en"],
    "platforms": ["ios", "android"]
  },
  "is_active": true,
  "expires_at": null,
  "created_at": "2024-01-20T15:30:00.000Z",
  "updated_at": "2024-01-20T15:30:00.000Z"
}

Error Responses

400 Bad Request - Invalid URL

{
  "error": "Bad Request",
  "message": "Invalid URL format",
  "statusCode": 400,
  "validation": {
    "originalUrl": "Must be a valid URL"
  }
}

400 Bad Request - Invalid Attribution Window

{
  "error": "Bad Request",
  "message": "Attribution window must be between 1 and 2160 hours",
  "statusCode": 400,
  "validation": {
    "attributionWindowHours": "Attribution window must be at least 1 hour"
  }
}

409 Conflict - Custom Code Already Exists

{
  "error": "Conflict",
  "message": "Short code 'spring-sale' is already in use",
  "statusCode": 409
}

401 Unauthorized

{
  "error": "Unauthorized",
  "message": "Missing or invalid API key",
  "statusCode": 401
}

404 Not Found - Template Not Found

{
  "error": "Not Found",
  "message": "Template not found",
  "statusCode": 404
}

Examples

Basic Link Creation

curl -X POST https://api.linkforty.com/api/links \
  -H "Authorization: Bearer lf_live_a1b2c3d4e5f6g7h8" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "550e8400-e29b-41d4-a716-446655440000",
    "originalUrl": "https://example.com/product/123"
  }'

With Platform-Specific URLs

curl -X POST https://api.linkforty.com/api/links \
  -H "Authorization: Bearer lf_live_a1b2c3d4e5f6g7h8" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "550e8400-e29b-41d4-a716-446655440000",
    "originalUrl": "https://example.com/product/123",
    "title": "Product 123 Campaign",
    "iosUrl": "https://apps.apple.com/app/your-store/id123456789",
    "androidUrl": "https://play.google.com/store/apps/details?id=com.yourstore"
  }'

With UTM Parameters

curl -X POST https://api.linkforty.com/api/links \
  -H "Authorization: Bearer lf_live_a1b2c3d4e5f6g7h8" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "550e8400-e29b-41d4-a716-446655440000",
    "originalUrl": "https://example.com/product/123",
    "utmParameters": {
      "utm_source": "facebook",
      "utm_medium": "cpc",
      "utm_campaign": "summer-2024",
      "utm_term": "wireless-headphones",
      "utm_content": "image-ad-1"
    }
  }'

With Custom Short Code

curl -X POST https://api.linkforty.com/api/links \
  -H "Authorization: Bearer lf_live_a1b2c3d4e5f6g7h8" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "550e8400-e29b-41d4-a716-446655440000",
    "originalUrl": "https://example.com/summer-sale",
    "customCode": "summer-sale-2024"
  }'

Generated URL: https://lnk.forty.com/summer-sale-2024

With Attribution Window

curl -X POST https://api.linkforty.com/api/links \
  -H "Authorization: Bearer lf_live_a1b2c3d4e5f6g7h8" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "550e8400-e29b-41d4-a716-446655440000",
    "originalUrl": "https://example.com/product/123",
    "attributionWindowHours": 336
  }'

Attribution Window: 336 hours = 14 days

With Targeting Rules

curl -X POST https://api.linkforty.com/api/links \
  -H "Authorization: Bearer lf_live_a1b2c3d4e5f6g7h8" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "550e8400-e29b-41d4-a716-446655440000",
    "originalUrl": "https://example.com/product/123",
    "targetingRules": {
      "countries": ["US", "CA"],
      "languages": ["en"],
      "platforms": ["ios", "android"]
    }
  }'

Behavior: Only users in US/Canada, with English language settings, on mobile devices will be redirected. Others see default URL or error.

With Expiration

curl -X POST https://api.linkforty.com/api/links \
  -H "Authorization: Bearer lf_live_a1b2c3d4e5f6g7h8" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "550e8400-e29b-41d4-a716-446655440000",
    "originalUrl": "https://example.com/flash-sale",
    "title": "24-Hour Flash Sale",
    "expiresAt": "2024-12-31T23:59:59Z"
  }'

Behavior: After December 31, 2024 23:59:59 UTC, link shows "This link has expired."

Complete Example (All Fields)

curl -X POST https://api.linkforty.com/api/links \
  -H "Authorization: Bearer lf_live_a1b2c3d4e5f6g7h8" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "550e8400-e29b-41d4-a716-446655440000",
    "originalUrl": "https://example.com/products/wireless-headphones",
    "title": "Wireless Headphones - Spring Sale",
    "description": "Q2 2024 Instagram campaign for new wireless headphones launch",
    "iosUrl": "https://apps.apple.com/app/your-store/id123456789",
    "androidUrl": "https://play.google.com/store/apps/details?id=com.yourstore",
    "webFallbackUrl": "https://example.com/products/wireless-headphones?platform=web",
    "attributionWindowHours": 168,
    "utmParameters": {
      "utm_source": "instagram",
      "utm_medium": "social",
      "utm_campaign": "spring-sale-2024",
      "utm_term": "wireless-headphones",
      "utm_content": "carousel-ad-1"
    },
    "targetingRules": {
      "countries": ["US", "CA", "GB"],
      "languages": ["en"],
      "platforms": ["ios", "android"]
    },
    "customCode": "spring-headphones",
    "expiresAt": "2024-06-30T23:59:59Z"
  }'

SDK Examples

JavaScript/TypeScript

import { LinkFortySDK } from '@linkforty/sdk';

const client = new LinkFortySDK({
  apiKey: process.env.LINKFORTY_API_KEY
});

// Basic creation
const link = await client.links.create({
  templateId: '550e8400-e29b-41d4-a716-446655440000',
  originalUrl: 'https://example.com/product/123'
});

console.log(link.short_url); // https://lnk.forty.com/abc123

// With full options
const campaignLink = await client.links.create({
  templateId: '550e8400-e29b-41d4-a716-446655440000',
  originalUrl: 'https://example.com/product/123',
  title: 'Product 123 Campaign',
  iosUrl: 'https://apps.apple.com/app/id123',
  androidUrl: 'https://play.google.com/store/apps/details?id=com.app',
  attributionWindowHours: 168,
  utmParameters: {
    utm_source: 'instagram',
    utm_medium: 'social',
    utm_campaign: 'spring-2024'
  }
});

Python

from linkforty import LinkForty

client = LinkForty(api_key=os.environ['LINKFORTY_API_KEY'])

# Basic creation
link = client.links.create(
    template_id='550e8400-e29b-41d4-a716-446655440000',
    original_url='https://example.com/product/123'
)

print(link.short_url)  # https://lnk.forty.com/abc123

# With full options
campaign_link = client.links.create(
    template_id='550e8400-e29b-41d4-a716-446655440000',
    original_url='https://example.com/product/123',
    title='Product 123 Campaign',
    ios_url='https://apps.apple.com/app/id123',
    android_url='https://play.google.com/store/apps/details?id=com.app',
    attribution_window_hours=168,
    utm_parameters={
        'utm_source': 'instagram',
        'utm_medium': 'social',
        'utm_campaign': 'spring-2024'
    }
)

Use Cases

E-commerce Product Link

{
  "templateId": "550e8400-e29b-41d4-a716-446655440000",
  "originalUrl": "https://shop.example.com/products/wireless-headphones",
  "title": "Wireless Headphones Product Page",
  "iosUrl": "https://apps.apple.com/app/shop-app/id123",
  "androidUrl": "https://play.google.com/store/apps/details?id=com.shop",
  "attributionWindowHours": 168,
  "utmParameters": {
    "utm_source": "instagram",
    "utm_medium": "social",
    "utm_campaign": "product-launch",
    "utm_content": "product-123"
  }
}

User Flow:

1. User clicks link on Instagram
2. Mobile user → App Store/Google Play
3. User installs app
4. App opens and navigates to wireless headphones product page
5. Install attributed to Instagram campaign

Referral Link

{
  "templateId": "550e8400-e29b-41d4-a716-446655440000",
  "originalUrl": "https://example.com/referral/john-doe",
  "customCode": "john-referral",
  "attributionWindowHours": 2160,
  "utmParameters": {
    "utm_source": "referral",
    "utm_medium": "friend",
    "utm_campaign": "refer-a-friend",
    "utm_content": "john-doe"
  }
}

Generated: https://lnk.forty.com/john-referral

User Flow:

1. John shares his referral link
2. Friend clicks and installs app (up to 90 days later)
3. Install attributed to John
4. John receives referral reward

Event Promotion

{
  "templateId": "550e8400-e29b-41d4-a716-446655440000",
  "originalUrl": "https://example.com/events/summer-concert",
  "customCode": "summer-concert",
  "attributionWindowHours": 720,
  "expiresAt": "2024-07-31T23:59:59Z",
  "utmParameters": {
    "utm_source": "facebook",
    "utm_medium": "event",
    "utm_campaign": "summer-concert-2024"
  }
}

Expires: July 31, 2024 (after event ends)

QR Code for Print Ad

{
  "templateId": "550e8400-e29b-41d4-a716-446655440000",
  "originalUrl": "https://example.com/print-promotion",
  "customCode": "magazine-june",
  "attributionWindowHours": 720,
  "utmParameters": {
    "utm_source": "magazine",
    "utm_medium": "print",
    "utm_campaign": "june-2024",
    "utm_content": "full-page-ad"
  }
}

Use with QR Code: Generate QR code from https://lnk.forty.com/magazine-june

30-day window: Accounts for delay between seeing print ad and taking action.

Best Practices

1. Always Provide Platform-Specific URLs

Bad:

{
  "originalUrl": "https://example.com/product"
}

Good:

{
  "originalUrl": "https://example.com/product",
  "iosUrl": "https://apps.apple.com/app/id123",
  "androidUrl": "https://play.google.com/store/apps/details?id=com.app"
}

Why: Improves attribution accuracy by 3-5x.

2. Use Descriptive Titles

Bad:

{
  "title": "Link 1"
}

Good:

{
  "title": "Instagram Story - Spring Sale - Wireless Headphones"
}

Why: Makes links easier to find and manage.

3. Set Attribution Window Based on Campaign

Campaign Type	Window
Flash sale	24-72 hours
Product launch	7-14 days
Referral program	30-90 days

4. Use Custom Codes for Memorable Links

For marketing materials, print ads, and verbal sharing:

{
  "customCode": "summer-sale"
}

Generated: https://lnk.forty.com/summer-sale

5. Include UTM Parameters

Always track campaign source:

{
  "utmParameters": {
    "utm_source": "instagram",
    "utm_medium": "social",
    "utm_campaign": "spring-2024"
  }
}

Rate Limiting

• Rate Limit: 100 requests/minute per API key
• Burst: 200 requests/minute (short bursts)
• Header: X-RateLimit-Remaining shows remaining quota

See Rate Limits for details.

Related Endpoints

• Get Link - Retrieve link details
• Update Link - Modify existing link
• Delete Link - Remove link
• Bulk Operations - Create multiple links at once
• Link Analytics - View link performance

Guides

• Creating Links - Complete guide with examples
• Attribution Windows - Choosing the right window
• Link Templates - Using templates for defaults
• UTM Parameters - Campaign tracking best practices