Create Campaign

Creates a new campaign in WitnessChain.

Endpoint

POST /create-campaign

Before creating a campaign, you must complete the authentication flow using the pre-login and login endpoints.

The documentation for the endpoints can be found at Authentication

Request Body

{
  "type": "object",
  "required": [
    "campaign",
    "description",
    "type",
    "currency",
    "total_rewards",
    "reward_per_task",
    "fuel_required",
    "starts_at",
    "ends_at",
    "max_submissions",
    "is_active"
  ],
  "properties": {
    "campaign": {
      "type": "string",
      "description": "Name of the campaign"
    },
    "description": {
      "type": "string",
      "description": "Detailed description of the campaign"
    },
    "type": {
      "type": "string",
      "enum": ["individual", "group", "task"],
      "description": "Type of campaign. Currently only 'individual' is supported",
      "default": "individual"
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Array of tags associated with the campaign"
    },
    "latitude": {
      "type": "number",
      "format": "float",
      "description": "Geographical latitude for campaign visibility (recommended)"
    },
    "longitude": {
      "type": "number",
      "format": "float",
      "description": "Geographical longitude for campaign visibility (recommended)"
    },
    "radius": {
      "type": "number",
      "description": "Radius in kilometers within which the campaign is valid",
      "default": 100
    },
    "banner_url": {
      "type": "string",
      "format": "uri",
      "description": "URL of the banner image shown to users"
    },
    "poster_url": {
      "type": "string",
      "format": "uri",
      "description": "URL of the poster image shown to users"
    },
    "currency": {
      "type": "string",
      "enum": ["POINTS"],
      "description": "Reward currency type. Currently only 'POINTS' is supported"
    },
    "total_rewards": {
      "type": "number",
      "format": "float",
      "description": "Maximum total rewards available for the campaign"
    },
    "reward_per_task": {
      "type": "number",
      "format": "float",
      "description": "Reward amount given per completed task"
    },
    "fuel_required": {
      "type": "number",
      "format": "float",
      "description": "Amount of fuel spent by user per task (recommended: 1.0)",
      "default": 1.0
    },
    "starts_at": {
      "type": "string",
      "format": "date-time",
      "description": "Campaign start date and time"
    },
    "ends_at": {
      "type": "string",
      "format": "date-time",
      "description": "Campaign end date and time"
    },
    "max_submissions": {
      "type": "integer",
      "description": "Maximum number of submissions allowed for the campaign"
    },
    "is_active": {
      "type": "boolean",
      "description": "Whether the campaign is immediately available to users",
      "default": true
    }
  }
}

Example Request

{
  "campaign": "Summer Promotion",
  "description": "Special summer promotional campaign",
  "type": "individual",
  "tags": ["summer", "promotion"],
  "latitude": 37.7749,
  "longitude": -122.4194,
  "radius": 100,
  "banner_url": "https://example.com/banner.png",
  "poster_url": "https://example.com/poster.png",
  "currency": "POINTS",
  "total_rewards": 10.0,
  "reward_per_task": 2.0,
  "fuel_required": 1.0,
  "starts_at": "2025-06-01T00:00:00Z",
  "ends_at": "2025-08-31T23:59:59Z",
  "max_submissions": 10000,
  "is_active": true
}

Example response

{
  "result" : {
    "success" : true
  }
}

Sample reference code

Please see tutorial on create campaign here:

https://github.com/witnesschain-com/tutorials/tree/main/create-campaign

Status Code	Description
400	Bad Request - Invalid parameters
401	Unauthorized - Authentication required
403	Forbidden - Insufficient permissions
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error

Notes

• The type field currently only supports "individual" campaigns

• For group campaigns (future feature), additional fields will be required:

  • location_limit_in_meters: Distance limit for group members

  • time_limit_in_minutes: Validity period for referral links

• Geographical coordinates (latitude, longitude) are recommended for better campaign targeting

• Setting is_active to true makes the campaign immediately available to users