Links API

Create, list, and manage affiliate tracking links programmatically. Requires authentication via JWT token.

List Links

curl https://api.affilync.com/api/links \
  -H "Authorization: Bearer YOUR_TOKEN"

Query Parameters:

Parameter	Type	Default	Description
search	string	--	Search links by name or URL
status	string	--	Filter by status: active, inactive
page	int	1	Page number
per_page	int	20	Results per page (max 100)
sort_by	string	created_at	Sort field
order	string	desc	Sort order: asc or desc

Response (200):

{
  "success": true,
  "data": {
    "links": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Spring Collection Link",
        "destination_url": "https://example.com/spring",
        "tracking_url": "https://track.affilync.com/c/abc123def456",
        "short_url": "https://afl.ink/abc123",
        "status": "active",
        "category": "promotional",
        "tags": ["spring", "sale"],
        "utm_source": "email",
        "utm_medium": "newsletter",
        "utm_campaign": "spring-2026",
        "utm_term": null,
        "utm_content": null,
        "commission_rate": 5.5,
        "clicks": 1423,
        "conversions": 87,
        "revenue": 5200.50,
        "created_at": "2026-03-10T08:15:00Z",
        "updated_at": "2026-03-15T14:30:00Z"
      }
    ],
    "total": 156,
    "page": 1,
    "total_pages": 8
  },
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 156,
    "total_pages": 8,
    "has_next": true,
    "has_prev": false
  }
}

Create a Link

curl -X POST https://api.affilync.com/api/links/generate \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "campaignId": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Spring Collection Link",
    "destinationUrl": "https://example.com/spring",
    "utmParams": {
      "utm_source": "email",
      "utm_medium": "newsletter",
      "utm_campaign": "spring-2026"
    }
  }'

Request Body:

Field	Type	Required	Description
campaignId	UUID string	No	Campaign ID (optional for custom links)
title	string	No	Link name/title
destinationUrl	string	Yes	Target URL
utmParams	object	No	UTM tracking parameters
customParams	object	No	Custom metadata

Response (201):

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "name": "Spring Collection Link",
    "destination_url": "https://example.com/spring",
    "tracking_url": "https://track.affilync.com/c/abc123def456",
    "short_url": "https://afl.ink/abc123",
    "status": "active",
    "utm_source": "email",
    "utm_medium": "newsletter",
    "utm_campaign": "spring-2026",
    "created_at": "2026-03-21T14:30:00Z"
  },
  "message": "Link generated successfully"
}

Bulk Create Links

Generate multiple links in one request:

curl -X POST https://api.affilync.com/api/batch/links/generate \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "links": [
      {
        "destination_url": "https://example.com/twitter",
        "campaign_id": "550e8400-e29b-41d4-a716-446655440000",
        "utm_source": "twitter",
        "utm_medium": "social"
      },
      {
        "destination_url": "https://example.com/instagram",
        "campaign_id": "550e8400-e29b-41d4-a716-446655440000",
        "utm_source": "instagram",
        "utm_medium": "social"
      },
      {
        "destination_url": "https://example.com/blog",
        "utm_source": "blog",
        "utm_medium": "organic"
      }
    ],
    "validate_urls": true
  }'

Response (201):

{
  "success": true,
  "data": {
    "created_count": 3,
    "failed_count": 0,
    "links": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440010",
        "tracking_url": "https://track.affilync.com/c/abc123def456",
        "short_url": "https://afl.ink/abc123"
      },
      {
        "id": "550e8400-e29b-41d4-a716-446655440011",
        "tracking_url": "https://track.affilync.com/c/def456ghi789",
        "short_url": "https://afl.ink/def456"
      },
      {
        "id": "550e8400-e29b-41d4-a716-446655440012",
        "tracking_url": "https://track.affilync.com/c/ghi789jkl012",
        "short_url": "https://afl.ink/ghi789"
      }
    ],
    "errors": [],
    "processing_time_ms": 245
  }
}

Maximum 100 links per bulk request.

Get a Link

Single-link operations use the /api/affiliate-links/{id} path.

curl https://api.affilync.com/api/affiliate-links/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (200):

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Spring Collection Link",
    "destination_url": "https://example.com/spring",
    "tracking_url": "https://track.affilync.com/c/abc123def456",
    "short_url": "https://afl.ink/abc123",
    "status": "active",
    "category": "promotional",
    "utm_source": "email",
    "utm_medium": "newsletter",
    "utm_campaign": "spring-2026",
    "commission_rate": 5.5,
    "created_at": "2026-03-10T08:15:00Z"
  }
}

Update a Link

curl -X PUT https://api.affilync.com/api/affiliate-links/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "inactive",
    "utm_source": "updated-source"
  }'

Deactivate a Link

To deactivate a link, send a PUT to /api/affiliate-links/{id} with status set to inactive — there is no dedicated deactivate verb.

curl -X PUT https://api.affilync.com/api/affiliate-links/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "status": "inactive" }'

Deactivated links return a 404 page instead of redirecting to the destination URL.

Delete a Link

curl -X DELETE https://api.affilync.com/api/affiliate-links/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_TOKEN"

Link Object Fields

Field	Type	Description
id	UUID	Unique link identifier
name	string	Link name/title
destination_url	string	Target URL that the link redirects to
tracking_url	string	Full tracking URL (includes tracking code)
short_url	string	Shortened URL for sharing
tracking_code	string	Unique tracking code for click tracking
affilync_id	string	User-friendly ID (e.g., AFF-A7B2F4C9-001)
qr_code_url	string	Generated QR code image URL
category	string	Optional link category
tags	array	List of tags for organization
status	string	active or inactive
campaign_id	UUID	Parent campaign ID (if applicable)
network_id	UUID	Affiliate network ID (if applicable)
utm_source	string	UTM source parameter
utm_medium	string	UTM medium parameter
utm_campaign	string	UTM campaign parameter
utm_term	string	UTM term parameter
utm_content	string	UTM content parameter
commission_rate	decimal	Commission rate as percentage
notes	string	Internal notes about the link
created_at	ISO 8601	Creation timestamp
updated_at	ISO 8601	Last update timestamp

Statistics

When fetching link analytics data, you can access click and conversion statistics:

Field	Type	Description
clicks	integer	Total number of clicks
unique_clicks	integer	Number of unique visitors
conversions	integer	Number of conversions attributed to this link
revenue	decimal	Total revenue generated
commission	decimal	Commission earned
ctr	decimal	Click-through rate
cr	decimal	Conversion rate
epc	decimal	Earnings per click

Error Responses

All errors follow this format:

{
  "success": false,
  "message": "Error description",
  "error_code": "error_code_value",
  "request_id": "correlation-id-for-support"
}

Common error codes:

• user_unidentified - User not authenticated
• invalid_campaign_id - Invalid campaign ID format
• missing_destination_url - Destination URL required for custom links
• link_conflict - Link already exists
• database_error - Database error occurred

Next Steps

• Affiliate Links Management
• Analytics API
• Webhook events for link clicks
• Error codes