Campaigns API

Manage campaigns programmatically. Requires authentication via JWT token or API key (X-API-Key).

List Campaigns

Brand campaigns are accessed via the brand-scoped endpoint. For affiliates or cross-user views, use the compatibility endpoint.

Brand Campaigns (Brand-scoped)

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

Query Parameters:

Parameter	Type	Default	Description
status	string	None	Filter by status: draft, active, paused, completed, archived
campaign_type	string	None	Filter by type: sale, lead, click, call, whatsapp, etc.
search	string	None	Search by campaign name or description
page	int	1	Page number
per_page	int	20	Results per page (max 100)
limit	int	None	Alternative to per_page for explicit limit (up to 1000)
sort_by	string	created_at	Sort field: created_at, name, commission_rate, start_date, status
order	string	desc	Sort order: asc or desc

Response (200):

{
  "success": true,
  "data": {
    "campaigns": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Spring Sale 2026",
        "description": "Promote our new spring collection",
        "status": "active",
        "campaign_type": "sale",
        "commission_rate": 25.00,
        "budget": 5000.00,
        "spent": 1234.56,
        "start_date": "2026-03-01T12:00:00Z",
        "end_date": "2026-04-30T23:59:59Z",
        "created_at": "2026-03-01T12:00:00Z",
        "metrics": {
          "clicks": 4521,
          "conversions": 143,
          "revenue": 3567.89,
          "affiliates": 12,
          "roi": 187.45,
          "conversion_rate": 3.16
        }
      }
    ],
    "pagination": {
      "total": 42,
      "page": 1,
      "per_page": 20,
      "pages": 3
    }
  },
  "message": "Campaigns retrieved successfully"
}

General Campaigns (User-scoped)

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

Automatically returns:

• For brands: Campaigns they have created
• For affiliates: Active campaigns they can join

Query Parameters:

Parameter	Type	Default	Description
status	string	None	Filter: active, paused, completed
page	int	1	Page number
per_page	int	20	Results per page (max 100)
sort_by	string	created_at	Sort field: name, performance, created_at
order	string	desc	Sort order: asc or desc

Get a Campaign

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

Response (200):

{
  "success": true,
  "data": {
    "campaign": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Spring Sale 2026",
      "description": "Promote our new spring collection",
      "status": "active",
      "campaign_type": "sale",
      "commission_rate": 25.00,
      "commission_type": "percentage",
      "budget": 5000.00,
      "spent": 1234.56,
      "start_date": "2026-03-01T12:00:00Z",
      "end_date": "2026-04-30T23:59:59Z",
      "created_at": "2026-03-01T12:00:00Z",
      "updated_at": "2026-03-15T09:30:00Z"
    }
  },
  "message": "Campaign retrieved successfully"
}

Create a Campaign

curl -X POST https://api.affilync.com/api/brand/campaigns \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Summer Launch",
    "description": "Promote our new summer collection",
    "campaign_type": "sale",
    "commission_rate": 30.00,
    "commission_type": "percentage",
    "budget": 10000.00,
    "start_date": "2026-06-01T00:00:00Z",
    "end_date": "2026-08-31T23:59:59Z",
    "launch_mode": "now",
    "auto_approve_affiliates": false
  }'

Request Fields:

Field	Type	Required	Description
name	string	Yes	Campaign name (1-200 chars)
description	string	No	Campaign description
campaign_type	string	Yes	Campaign type: sale, lead, click, call, whatsapp, impression, subscription, app_install, custom, self_tracking
commission_rate	float	Yes	Commission percentage (0-100) or fixed amount
commission_type	string	No	percentage (default) or fixed
budget	float	Yes	Total campaign budget
start_date	string	No	Campaign start date (ISO 8601)
end_date	string	No	Campaign end date (ISO 8601)
launch_mode	string	No	now to activate immediately; otherwise creates as draft
auto_approve_affiliates	boolean	No	Auto-approve affiliate applications (default: false)
alert_config	object	No	Performance alert configuration
use_template	string	No	Template ID to use as base
requirements	array	No	Campaign requirements for affiliates

Call Campaign Fields (when campaign_type is call):

Field	Type	Default	Description
call_payout_type	string	per_call	per_call or per_minute
call_payout_amount	float	Required	Payout amount per call or minute
call_min_duration	int	90	Minimum call duration in seconds
call_max_duration	int	3600	Maximum call duration in seconds
call_recording_enabled	boolean	true	Enable call recording
call_whisper_enabled	boolean	false	Enable whisper message before call connects
call_whisper_message	string	None	Whisper message to play
call_destination_number	string	None	Destination phone number for forwarding
call_numbers_to_provision	int	10	Number of tracking numbers to provision (1-100)

Response (201):

{
  "success": true,
  "data": {
    "campaign": {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "name": "Summer Launch",
      "status": "active",
      "campaign_type": "sale",
      "commission_rate": 30.00,
      "commission_type": "percentage",
      "budget": 10000.00,
      "created_at": "2026-06-01T14:00:00Z"
    }
  },
  "message": "Campaign created successfully"
}

Update a Campaign

curl -X PUT https://api.affilync.com/api/brand/campaigns/550e8400-e29b-41d4-a716-446655440001 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "active",
    "commission_rate": 35.00,
    "budget": 12000.00,
    "name": "Summer Launch 2026"
  }'

Request Fields (all optional):

Field	Type	Description
name	string	Campaign name (1-200 chars)
description	string	Campaign description
commission_rate	float	Commission percentage (0-100) or fixed amount
budget	float	Total campaign budget
end_date	string	Campaign end date (ISO 8601)
status	string	Campaign status: draft, active, paused, completed, archived
requirements	array	Campaign requirements for affiliates

Response (200):

{
  "success": true,
  "data": {
    "campaign": {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "name": "Summer Launch 2026",
      "status": "active",
      "commission_rate": 35.00,
      "budget": 12000.00,
      "updated_at": "2026-06-15T10:30:00Z"
    }
  },
  "message": "Campaign updated successfully"
}

Delete a Campaign

curl -X DELETE https://api.affilync.com/api/brand/campaigns/550e8400-e29b-41d4-a716-446655440001 \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (200 - Soft Delete):

{
  "success": true,
  "data": {
    "campaign": {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "status": "archived"
    }
  },
  "message": "Campaign deleted successfully"
}

Note: Campaigns are soft-deleted (status set to archived, marked as deleted) rather than permanently removed from the database. This preserves historical analytics and commission data. Child records (clicks, conversions, commissions) are preserved.

Campaign Object Fields

Field	Type	Description
id	string (UUID)	Unique campaign identifier
name	string	Campaign display name
description	string	Campaign description
campaign_type	string	Campaign type (see list above)
status	string	draft, active, paused, completed, archived
commission_rate	float	Commission value (percentage or fixed amount)
commission_type	string	percentage or fixed
budget	float	Total campaign budget
spent	float	Amount spent to date
start_date	string	Campaign start date (ISO 8601 timestamp)
end_date	string	Campaign end date (ISO 8601 timestamp)
created_at	string	ISO 8601 timestamp
updated_at	string	ISO 8601 timestamp

Metrics Object (returned in list view):

Field	Type	Description
clicks	integer	Total clicks from all affiliates
conversions	integer	Total conversions
revenue	float	Total revenue (sale amount)
affiliates	integer	Number of active affiliate promoters
roi	float	Return on investment percentage
conversion_rate	float	Conversion rate percentage

Tier Requirements

Campaign CRUD operations require at least the Starter tier or higher.

• Free: No campaigns
• Starter+: Full campaign management

Next Steps

• Links API
• Analytics API
• Error codes and rate limits