← Back to Home

🔌 API Documentation

The GoViralPro API allows you to programmatically interact with your campaigns, track referrals, and integrate our platform into your existing workflows.

📌 Base URL: https://api.goviralpro.com/v1
📌 Format: All requests and responses are in JSON

🔐 Authentication

All API requests require authentication using an API key. You can generate an API key from your account settings dashboard.

API Key Authentication

Include your API key in the request header:

Authorization: Bearer YOUR_API_KEY_HERE
Content-Type: application/json

Example Request

curl -X GET "https://api.goviralpro.com/v1/campaigns" \
  -H "Authorization: Bearer sk_live_abc123xyz456" \
  -H "Content-Type: application/json"

⚠️ Security Warning: Never expose your API key in client-side code or public repositories. Always make API calls from your server.

📋 Campaigns API

GET List All Campaigns

/campaigns

Retrieves a list of all your campaigns.

Query Parameters

Parameter	Type	Description
`limit`	integer	Number of results per page (default: 50, max: 100)
`page`	integer	Page number for pagination (default: 1)
`status`	string	Filter by status: `active` or `inactive`

Example Response

{
  "success": true,
  "data": [
    {
      "id": 1,
      "title": "Win a MacBook Pro",
      "slug": "macbook-giveaway",
      "status": "active",
      "total_participants": 1250,
      "total_referrals": 3420,
      "created_at": "2026-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 3,
    "total_results": 15
  }
}

GET Get Campaign by ID

/campaigns/{id}

Retrieves detailed information about a specific campaign.

Example Response

{
  "success": true,
  "data": {
    "id": 1,
    "title": "Win a MacBook Pro",
    "description": "Enter for a chance to win...",
    "slug": "macbook-giveaway",
    "giveaway_item": "MacBook Pro 16-inch",
    "points_required": 500,
    "is_active": true,
    "countdown_enabled": true,
    "countdown_end": "2026-03-01T23:59:59Z",
    "total_participants": 1250,
    "total_referrals": 3420,
    "views_count": 15600,
    "created_at": "2026-01-15T10:30:00Z"
  }
}

POST Create Campaign

/campaigns

Creates a new viral campaign.

Request Body

Field	Type	Required	Description
`title`	string	Yes	Campaign title
`description`	string	Yes	Campaign description
`giveaway_item`	string	Yes	Prize description
`points_required`	integer	Yes	Points needed to unlock reward
`slug`	string	No	Custom URL slug (auto-generated if not provided)

Example Request

{
  "title": "Win a MacBook Pro",
  "description": "Enter for a chance to win the latest MacBook Pro!",
  "giveaway_item": "MacBook Pro 16-inch",
  "points_required": 500,
  "slug": "macbook-2026"
}

🔗 Referrals API

GET List Campaign Referrals

/campaigns/{id}/referrals

Retrieves all referrals for a specific campaign.

Query Parameters

Parameter	Type	Description
`limit`	integer	Number of results (default: 50, max: 100)
`sort`	string	Sort by: `points`, `date`, `referrals`

Example Response

{
  "success": true,
  "data": [
    {
      "id": 42,
      "name": "John Doe",
      "email": "[email protected]",
      "referrer_code": "ABC123XYZ",
      "points_earned": 450,
      "total_referrals": 8,
      "reward_unlocked": false,
      "created_at": "2026-01-20T14:22:00Z"
    }
  ]
}

POST Track Share Event

/track/share

Records a share event and awards points to the referrer.

Request Body

{
  "campaign_id": 1,
  "referrer_code": "ABC123XYZ",
  "platform": "facebook"
}

Supported Platforms

facebook, twitter, whatsapp, telegram, linkedin, email, sms, reddit, pinterest

🔔 Webhooks

Subscribe to real-time events by configuring webhook endpoints in your account settings. We'll send POST requests to your URL when events occur.

Available Events

campaign.created - New campaign created
referral.registered - New participant registered
referral.converted - Referral successfully converted
reward.unlocked - Participant unlocked reward
campaign.completed - Campaign ended

Webhook Payload Example

{
  "event": "referral.registered",
  "timestamp": "2026-02-02T16:30:00Z",
  "data": {
    "campaign_id": 1,
    "referral_id": 42,
    "name": "Jane Smith",
    "email": "[email protected]",
    "referrer_code": "XYZ789ABC",
    "points_awarded": 50
  }
}

⏱️ Rate Limits

API rate limits are applied per API key:

Plan	Requests per Minute	Requests per Hour
Free	30	500
Basic	60	2,000
Standard	120	5,000
Premium	300	15,000
Platinum	Unlimited	Unlimited

Rate Limit Headers

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1643832600

❌ Error Codes

The API uses standard HTTP status codes:

Code	Description
`200`	Success
`201`	Created
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Invalid API key
`403`	Forbidden - Insufficient permissions
`404`	Not Found - Resource doesn't exist
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error

Error Response Format

{
  "success": false,
  "error": {
    "code": "invalid_request",
    "message": "Campaign with ID 999 not found",
    "details": []
  }
}

Need Help?

Questions about our API? Contact our developer support team:

Email: [email protected]
Contact Form →