Get Link

Retrieve details for a single link or list all links in your organization.

Get Single Link

GET /api/links/:id

Retrieve detailed information about a specific link, including click count and template information.

Authentication

Requires authentication via:

Bearer token (user session)
API key in Authorization header

Path Parameters

Parameter	Type	Required	Description
`id`	string (UUID)	Yes	Link ID

Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "userId": "user_123",
  "organizationId": "org_456",
  "projectId": "proj_789",
  "templateId": "tmpl_abc",
  "templateSlug": "instagram-campaign",
  "shortCode": "abc123",
  "originalUrl": "https://example.com/products/123",
  "title": "Wireless Headphones Product Page",
  "description": "Premium noise-cancelling headphones",
  "iosUrl": "https://apps.apple.com/app/id123456789",
  "androidUrl": "https://play.google.com/store/apps/details?id=com.example.app",
  "webFallbackUrl": null,
  "utmParameters": {
    "source": "instagram",
    "medium": "social",
    "campaign": "spring-sale-2024",
    "content": "story-swipe-up"
  },
  "targetingRules": {
    "countries": ["US", "CA"],
    "devices": ["ios", "android"],
    "languages": ["en"]
  },
  "attributionWindowHours": 168,
  "expiresAt": null,
  "isActive": true,
  "clickCount": 1248,
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-20T14:22:00Z"
}

Response Fields

Field	Type	Description
`id`	string	Unique link identifier
`userId`	string	ID of user who created the link
`organizationId`	string	Organization ID
`projectId`	string\|null	Optional project grouping
`templateId`	string	Link template used
`templateSlug`	string	Human-readable template identifier
`shortCode`	string	Unique short code (e.g., "abc123")
`originalUrl`	string	Default destination URL
`title`	string\|null	Link title/name
`description`	string\|null	Link description
`iosUrl`	string\|null	iOS-specific redirect URL
`androidUrl`	string\|null	Android-specific redirect URL
`webFallbackUrl`	string\|null	Web fallback URL
`utmParameters`	object	UTM tracking parameters
`targetingRules`	object	Geographic/device targeting
`attributionWindowHours`	number	Hours for install attribution (default: 168)
`expiresAt`	string\|null	ISO 8601 expiration timestamp
`isActive`	boolean	Whether link is active
`clickCount`	number	Total number of clicks
`createdAt`	string	ISO 8601 creation timestamp
`updatedAt`	string	ISO 8601 last update timestamp

Example Request

curl https://api.linkforty.com/api/links/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer $LINKFORTY_API_KEY"

Example Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "shortCode": "abc123",
  "originalUrl": "https://example.com/products/headphones",
  "title": "Spring Sale - Wireless Headphones",
  "iosUrl": "https://apps.apple.com/app/id123",
  "androidUrl": "https://play.google.com/store/apps/details?id=com.app",
  "utmParameters": {
    "source": "instagram",
    "medium": "social",
    "campaign": "spring-sale"
  },
  "attributionWindowHours": 168,
  "clickCount": 523,
  "isActive": true,
  "createdAt": "2024-03-01T12:00:00Z"
}

List All Links

GET /api/links

Retrieve all links belonging to your organization.

Authentication

Requires authentication via:

Bearer token (user session)
API key in Authorization header

Query Parameters

Parameter	Type	Required	Description
`projectId`	string (UUID)	No	Filter links by project

Response

Returns an array of link objects with click counts.

[
  {
    "id": "link_1",
    "shortCode": "abc123",
    "title": "Product A",
    "originalUrl": "https://example.com/products/a",
    "clickCount": 1248,
    "templateSlug": "instagram-campaign",
    "createdAt": "2024-01-15T10:30:00Z"
  },
  {
    "id": "link_2",
    "shortCode": "def456",
    "title": "Product B",
    "originalUrl": "https://example.com/products/b",
    "clickCount": 892,
    "templateSlug": "facebook-ads",
    "createdAt": "2024-01-16T14:20:00Z"
  }
]

Example Request

Get all links:

curl https://api.linkforty.com/api/links \
  -H "Authorization: Bearer $LINKFORTY_API_KEY"

Filter by project:

curl "https://api.linkforty.com/api/links?projectId=proj_789" \
  -H "Authorization: Bearer $LINKFORTY_API_KEY"

Sorting

Links are returned in descending order by creation date (newest first).

Error Responses

Link Not Found

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

Possible causes:

Link ID doesn't exist
Link belongs to different organization
Link was deleted

Unauthorized

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Authentication required"
}

Possible causes:

Missing API key/bearer token
Invalid API key
Expired session token

Use Cases

1. Display Link Details in Dashboard

const link = await fetch('https://api.linkforty.com/api/links/abc123', {
  headers: {
    'Authorization': `Bearer ${apiKey}`
  }
}).then(r => r.json());

console.log(`Link: ${link.shortCode}`);
console.log(`Clicks: ${link.clickCount}`);
console.log(`Created: ${new Date(link.createdAt).toLocaleDateString()}`);

2. Get Link by Short Code

Since the endpoint requires UUID, you'll need to list all links and filter:

const links = await fetch('https://api.linkforty.com/api/links', {
  headers: { 'Authorization': `Bearer ${apiKey}` }
}).then(r => r.json());

const link = links.find(l => l.shortCode === 'abc123');

3. Monitor Link Performance

const link = await getLinkById('link_id');

if (link.clickCount > 1000) {
  console.log('High-performing link!');
}

if (link.expiresAt && new Date(link.expiresAt) < new Date()) {
  console.log('Link expired - needs renewal');
}

4. Audit Recent Links

const links = await getAllLinks();

const recentLinks = links.filter(link => {
  const createdDate = new Date(link.createdAt);
  const weekAgo = new Date();
  weekAgo.setDate(weekAgo.getDate() - 7);
  return createdDate > weekAgo;
});

console.log(`${recentLinks.length} links created in last 7 days`);

Best Practices

1. Cache Link Data

Link details rarely change, so cache them:

const linkCache = new Map();

async function getLinkWithCache(linkId: string) {
  if (linkCache.has(linkId)) {
    return linkCache.get(linkId);
  }

  const link = await fetch(`/api/links/${linkId}`, {
    headers: { 'Authorization': `Bearer ${apiKey}` }
  }).then(r => r.json());

  linkCache.set(linkId, link);
  return link;
}

2. Handle Pagination (Future)

While the current API returns all links, plan for pagination:

// Future-proof for when pagination is added
async function getAllLinksWithPagination() {
  let allLinks = [];
  let page = 1;
  let hasMore = true;

  while (hasMore) {
    const response = await fetch(
      `/api/links?page=${page}&limit=100`,
      { headers: { 'Authorization': `Bearer ${apiKey}` } }
    );
    const data = await response.json();

    allLinks = allLinks.concat(data.links || data);
    hasMore = data.hasMore || false;
    page++;
  }

  return allLinks;
}

3. Filter Client-Side

For small datasets, filter in your application:

const links = await getAllLinks();

// Active links only
const activeLinks = links.filter(l => l.isActive);

// High-performing links
const topLinks = links
  .filter(l => l.clickCount > 100)
  .sort((a, b) => b.clickCount - a.clickCount);

// Links by campaign
const campaignLinks = links.filter(
  l => l.utmParameters?.campaign === 'spring-sale-2024'
);

Create Link - Create a new link
Update Link - Modify link properties
Delete Link - Remove a link
Link Analytics - View click analytics

Guides

Creating Links - Complete guide
Link Templates - Using templates
UTM Parameters - Campaign tracking

Get Single Link​

Authentication​

Path Parameters​

Response​

Response Fields​

Example Request​

Example Response​

List All Links​

Authentication​

Query Parameters​

Response​

Example Request​

Sorting​

Error Responses​

Link Not Found​

Unauthorized​

Use Cases​

1. Display Link Details in Dashboard​

2. Get Link by Short Code​

3. Monitor Link Performance​

4. Audit Recent Links​

Best Practices​

1. Cache Link Data​

2. Handle Pagination (Future)​

3. Filter Client-Side​

Related Endpoints​

Guides​

Get Single Link

Authentication

Path Parameters

Response

Response Fields

Example Request

Example Response

List All Links

Authentication

Query Parameters

Response

Example Request

Sorting

Error Responses

Link Not Found

Unauthorized

Use Cases

1. Display Link Details in Dashboard

2. Get Link by Short Code

3. Monitor Link Performance

4. Audit Recent Links

Best Practices

1. Cache Link Data

2. Handle Pagination (Future)

3. Filter Client-Side

Related Endpoints

Guides