Zervixa API Reference

Welcome to Zervixa API

Zervixa is a powerful cloud-based affiliate tracking platform designed to help you manage campaigns, track conversions, and optimize your affiliate marketing performance. Our REST API provides full access to your Zervixa account programmatically.

This documentation covers all available API endpoints, request/response formats, authentication methods, and error handling. Use the navigation on the left to explore specific endpoints.

Authentication

All API requests require Bearer token authentication using your API key. You can generate and manage API keys from your Account Settings page.

Bearer Token

Include your API key in the Authorization header of every request:

Authorization: Bearer your_api_key_here

Example with cURL:

curl -H "Authorization: Bearer your_api_key_here" https://zervixa.com/api/v1/campaigns

Base URL

All API requests should be made to:

https://zervixa.com/api/v1/

Rate Limiting

Rate Limits

1,000 requests per hour — This limit is per API key and resets every hour.

Response headers include rate limit information:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1648742400
                        

Request Format

All API requests should use the following format:

Method: HTTP method (GET, POST, PUT, DELETE)
Headers: Content-Type: application/json, Authorization: Bearer {api_key}
Body: JSON-formatted request data (for POST/PUT requests)

Response Format

All API responses are returned in JSON format with the following structure:

{
  "success": true,
  "data": { "key": "value" },
  "message": "Operation completed successfully"
}
                    

On error:

{
  "success": false,
  "error": "error_code",
  "message": "Error description"
}
                    

Pagination

List Endpoints Pagination

Endpoints that return lists support pagination using page and per_page parameters.

Default: page=1, per_page=20 (max 100)

Responses include pagination metadata in the response envelope for easy navigation between pages.

GET List Campaigns

Retrieve a paginated list of all campaigns in your account with their current status and key metrics.

GET /campaigns

Query Parameters

Parameter	Type	Required	Description
status	string	No	Filter by status: active, paused, archived
page	integer	No	Page number (default: 1)
per_page	integer	No	Results per page (default: 20, max: 100)

Example Request

curl -X GET "https://zervixa.com/api/v1/campaigns?status=active&page=1&per_page=20" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json"
                    

Example Response (200 OK)

{
  "success": true,
  "data": {
    "campaigns": [
      {
        "id": 1,
        "name": "Summer Promo 2026",
        "status": "active",
        "traffic_source_id": 5,
        "created_at": "2026-01-15T10:30:00Z",
        "clicks": 1250,
        "conversions": 85
      }
    ],
    "pagination": {
      "page": 1,
      "per_page": 20,
      "total": 45
    }
  }
}
                    

POST Create Campaign

Create a new campaign with traffic source and geo-targeting settings.

POST /campaigns

Request Body

Field	Type	Required	Description
name	string	Yes	Campaign name (max 255 characters)
traffic_source_id	integer	Yes	ID of the traffic source
country_code	string	No	ISO 3166-1 country code (e.g., US, UK, CA)
description	string	No	Campaign description

Example Request

curl -X POST "https://zervixa.com/api/v1/campaigns" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Winter Campaign",
    "traffic_source_id": 3,
    "country_code": "US",
    "description": "Q4 promotional campaign"
  }'
                    

Example Response (201 Created)

{
  "success": true,
  "data": {
    "id": 42,
    "name": "Winter Campaign",
    "status": "active",
    "traffic_source_id": 3,
    "country_code": "US",
    "created_at": "2026-04-06T12:00:00Z"
  },
  "message": "Campaign created successfully"
}
                    

GET Get Campaign Details

Retrieve detailed information about a specific campaign including performance metrics.

GET /campaigns/{id}

Path Parameters

Parameter	Type	Required	Description
id	integer	Yes	Campaign ID

Example Request

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

Example Response (200 OK)

{
  "success": true,
  "data": {
    "id": 42,
    "name": "Winter Campaign",
    "status": "active",
    "traffic_source_id": 3,
    "country_code": "US",
    "description": "Q4 promotional campaign",
    "created_at": "2026-04-06T12:00:00Z",
    "total_clicks": 5420,
    "total_conversions": 342,
    "conversion_rate": 6.31,
    "total_payout": 1710.50
  }
}
                    

PUT Update Campaign

Update campaign details such as name, status, or description.

PUT /campaigns/{id}

Request Body

Field	Type	Required	Description
name	string	No	New campaign name
status	string	No	active, paused, or archived
description	string	No	Campaign description

Example Request

curl -X PUT "https://zervixa.com/api/v1/campaigns/42" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "paused",
    "description": "Campaign paused for budget review"
  }'
                    

Example Response (200 OK)

{
  "success": true,
  "data": {
    "id": 42,
    "status": "paused"
  },
  "message": "Campaign updated successfully"
}
                    

DELETE Delete Campaign

Permanently delete a campaign. This action cannot be undone.

DELETE /campaigns/{id}

Path Parameters

Parameter	Type	Required	Description
id	integer	Yes	Campaign ID

Example Request

curl -X DELETE "https://zervixa.com/api/v1/campaigns/42" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json"
                    

Example Response (204 No Content)

Response body is empty. Check the status code to confirm deletion.

GET List Offers

Retrieve all available offers that can be promoted through campaigns.

GET /offers

Query Parameters

Parameter	Type	Required	Description
page	integer	No	Page number (default: 1)
per_page	integer	No	Results per page (default: 20, max: 100)

Example Request

curl -X GET "https://zervixa.com/api/v1/offers?page=1&per_page=20" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json"
                    

Example Response (200 OK)

{
  "success": true,
  "data": {
    "offers": [
      {
        "id": 1,
        "name": "Premium SaaS Subscription",
        "url": "https://example.com/offer",
        "payout": 45.00,
        "payout_type": "cps",
        "category": "SaaS"
      }
    ]
  }
}
                    

POST Create Offer

Create a new offer with payout details for affiliates to promote.

POST /offers

Request Body

Field	Type	Required	Description
name	string	Yes	Offer name
url	string	Yes	Landing page URL
payout	decimal	Yes	Payout amount
payout_type	string	Yes	cps (cost per sale), cpl (cost per lead), cpc (cost per click)
category	string	No	Offer category

Example Request

curl -X POST "https://zervixa.com/api/v1/offers" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Cloud Storage Pro",
    "url": "https://cloudstorage.example.com",
    "payout": 25.50,
    "payout_type": "cps",
    "category": "Cloud Services"
  }'
                    

Example Response (201 Created)

{
  "success": true,
  "data": {
    "id": 15,
    "name": "Cloud Storage Pro",
    "payout": 25.50,
    "payout_type": "cps"
  },
  "message": "Offer created successfully"
}
                    

GET List Traffic Sources

Retrieve all available traffic sources for campaign targeting.

GET /traffic-sources

Example Request

curl -X GET "https://zervixa.com/api/v1/traffic-sources" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json"
                    

Example Response (200 OK)

{
  "success": true,
  "data": {
    "traffic_sources": [
      {
        "id": 1,
        "name": "Facebook",
        "type": "social_media"
      },
      {
        "id": 2,
        "name": "Google Ads",
        "type": "paid_search"
      },
      {
        "id": 3,
        "name": "Email List",
        "type": "email"
      }
    ]
  }
}
                    

POST Record Conversion

Record a conversion event with click ID and payout information. Use this endpoint for server-side conversion tracking.

POST /conversions

Request Body

Field	Type	Required	Description
click_id	string	Yes	Unique click identifier from tracking link
payout	decimal	No	Custom payout amount (uses offer default if not provided)
status	string	Yes	approved, pending, rejected
notes	string	No	Additional conversion notes

Example Request

curl -X POST "https://zervixa.com/api/v1/conversions" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "click_id": "c9e8f7g6h5i4j3k2l1m0",
    "payout": 25.50,
    "status": "approved",
    "notes": "Conversion verified via webhook"
  }'
                    

Example Response (201 Created)

{
  "success": true,
  "data": {
    "id": 8521,
    "click_id": "c9e8f7g6h5i4j3k2l1m0",
    "status": "approved",
    "payout": 25.50,
    "recorded_at": "2026-04-06T15:30:00Z"
  },
  "message": "Conversion recorded successfully"
}
                    

GET List Clicks

Retrieve click log data with filtering and pagination for campaign analysis.

GET /clicks

Query Parameters

Parameter	Type	Required	Description
campaign_id	integer	No	Filter by campaign ID
date_from	string	No	Start date (YYYY-MM-DD)
date_to	string	No	End date (YYYY-MM-DD)
page	integer	No	Page number (default: 1)

Example Request

curl -X GET "https://zervixa.com/api/v1/clicks?campaign_id=42&date_from=2026-04-01&date_to=2026-04-06&page=1" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json"
                    

Example Response (200 OK)

{
  "success": true,
  "data": {
    "clicks": [
      {
        "id": 1,
        "click_id": "c9e8f7g6h5i4j3k2l1m0",
        "campaign_id": 42,
        "timestamp": "2026-04-06T10:30:00Z",
        "ip_address": "203.0.113.42",
        "country": "US",
        "status": "pending"
      }
    ],
    "pagination": {
      "page": 1,
      "per_page": 20,
      "total": 5420
    }
  }
}
                    

GET Get Reports

Retrieve aggregated performance reports with flexible grouping and filtering options.

GET /reports

Query Parameters

Parameter	Type	Required	Description
date_from	string	No	Start date (YYYY-MM-DD)
date_to	string	No	End date (YYYY-MM-DD)
group_by	string	No	campaign, offer, country, date, or traffic_source
filters	object	No	Filter by campaign_id, offer_id, country_code

Example Request

curl -X GET "https://zervixa.com/api/v1/reports?date_from=2026-03-01&date_to=2026-04-06&group_by=campaign" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json"
                    

Example Response (200 OK)

{
  "success": true,
  "data": {
    "reports": [
      {
        "campaign_id": 42,
        "campaign_name": "Winter Campaign",
        "total_clicks": 5420,
        "total_conversions": 342,
        "conversion_rate": 6.31,
        "total_payout": 8710.50,
        "roi": 435.5
      }
    ]
  }
}
                    

GET List Domains

Retrieve all custom domains configured for your account.

GET /domains

Example Request

curl -X GET "https://zervixa.com/api/v1/domains" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json"
                    

Example Response (200 OK)

{
  "success": true,
  "data": {
    "domains": [
      {
        "id": 1,
        "domain": "track.example.com",
        "status": "active",
        "ssl_enabled": true,
        "created_at": "2026-01-15T10:00:00Z"
      }
    ]
  }
}
                    

POST Add Domain

Add a new custom domain for tracking links. SSL certificates are provisioned automatically.

POST /domains

Request Body

Field	Type	Required	Description
domain	string	Yes	Domain name (e.g., track.example.com)
ssl_enabled	boolean	No	Enable SSL certificate (default: true)

Example Request

curl -X POST "https://zervixa.com/api/v1/domains" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "track.example.com",
    "ssl_enabled": true
  }'
                    

Example Response (201 Created)

{
  "success": true,
  "data": {
    "id": 2,
    "domain": "track.example.com",
    "status": "pending",
    "ssl_enabled": true,
    "dns_records": [
      {
        "type": "A",
        "name": "track.example.com",
        "value": "203.0.113.1"
      }
    ]
  },
  "message": "Domain added successfully. Please configure DNS records."
}
                    

Error Codes & Responses

Reference guide for HTTP status codes and error responses returned by the Zervixa API.

HTTP Status Codes

Code	Status	Description
200	OK	Request succeeded. Response body contains requested data.
201	Created	Resource created successfully. Response body contains new resource.
204	No Content	Request succeeded. No content in response (e.g., DELETE operations).
400	Bad Request	Request validation failed. Check request parameters and body.
401	Unauthorized	Invalid or missing API key. Check Authorization header.
403	Forbidden	You don't have permission to access this resource.
404	Not Found	Resource not found. Check the ID or endpoint path.
429	Too Many Requests	Rate limit exceeded. Wait before making additional requests.
500	Internal Server Error	Server error. Try again later or contact support.

Error Response Examples

Validation Error (400)

{
  "success": false,
  "error": "validation_error",
  "message": "Campaign name is required",
  "details": {
    "name": ["Name field is required"]
  }
}
                    

Unauthorized Error (401)

{
  "success": false,
  "error": "unauthorized",
  "message": "Invalid API key or token expired"
}
                    

Not Found Error (404)

{
  "success": false,
  "error": "not_found",
  "message": "Campaign with ID 42 not found"
}
                    

Rate Limit Error (429)

{
  "success": false,
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Try again after 3600 seconds.",
  "retry_after": 3600
}
                    

Common Error Codes

invalid_token API key is invalid or has been revoked. Generate a new key from Account Settings.

token_expired API key has expired. Generate a new key from Account Settings.

resource_not_found The requested resource (campaign, offer, domain, etc.) does not exist.

validation_error Request body contains invalid data. Check field types and required fields.

duplicate_entry A resource with this name or identifier already exists.

insufficient_permissions Your API key does not have permission for this operation.

rate_limit_exceeded You have exceeded the 1,000 requests per hour limit. Wait before retrying.

internal_server_error An unexpected server error occurred. Contact support if the issue persists.